RoyalComply Documentation

Getting Started

RoyalComply handles privacy and cookie compliance the right way — with real script blocking, not just banner theater. No SaaS dependency, no locked features, no external API calls. Everything runs locally on your WordPress site.

Why You Need Cookie Compliance

Requirements

• WordPress 5.9 or higher
• PHP 7.4 or higher

Installation

From WordPress.org

Manual Installation

Quick Start

Get privacy compliance set up on your site in under 10 minutes:

Banner Design

RoyalComply lets you choose between two banner layout styles to match your site design:

• Bar layout — A full-width banner that spans the entire width of the viewport. Best for top or bottom positions where you want maximum visibility without obstructing content.
• Box layout — A floating, contained box that appears in a corner or center of the screen. More subtle and modern, suitable for sites that want a less intrusive approach.

Both layouts are fully responsive and adapt to mobile screens automatically.

Positions & Layout

Choose from 6 position options for your consent banner:

Colors & Text

Every visual aspect of the consent banner is customizable:

• Background color — The banner's background (default: dark charcoal)
• Text color — The banner's body text (default: white)
• Accept button color — The primary "Accept All" button background
• Reject button color — The "Reject All" button background
• Preferences button — The "Manage Preferences" link style

All text labels are customizable, including:

• Banner headline and description text
• "Accept All" button label
• "Reject All" button label
• "Manage Preferences" button label
• Cookie category names and descriptions

Cookie Categories

RoyalComply organizes cookies into 4 standard categories used by privacy regulations worldwide:

Users can accept or reject each category individually through the "Manage Preferences" panel, giving them granular control over their privacy.

How Script Blocking Works

RoyalComply uses the WordPress script_loader_tag filter to change the script type attribute from text/javascript to text/plain for non-consented categories. This prevents execution at the browser level — the browser simply ignores scripts with an unrecognized type.

When a visitor gives consent for a specific category, RoyalComply dynamically changes the script type back to text/javascript and re-enables execution. This all happens client-side without a page reload.

Why This Matters

Most cookie consent plugins only show a banner and set a cookie recording the visitor's choice. The actual tracking scripts still load and execute regardless. This is not compliant with GDPR, which requires that non-essential scripts do NOT run before consent is given.

RoyalComply's approach is real blocking — scripts are genuinely prevented from executing until the visitor explicitly consents.

Analytics Scripts

The following analytics scripts are automatically detected and blocked until the visitor grants analytics consent:

• Google Analytics (GA4 / Universal Analytics) — gtag.js, analytics.js
• Hotjar — Session recordings and heatmaps
• Microsoft Clarity — Session recordings and click tracking
• Matomo — Self-hosted and cloud analytics
• Plausible — Privacy-focused analytics

RoyalComply identifies these scripts by their known script URLs and handle names. If you use a custom analytics tool, you can manually assign it to the analytics category in the cookie scanner.

Marketing Scripts

The following marketing and advertising scripts are blocked until marketing consent is given:

• Facebook Pixel — fbevents.js
• Google Ads — Conversion tracking and remarketing tags
• LinkedIn Insight Tag — snap.licdn.com
• TikTok Pixel — analytics.tiktok.com
• Pinterest Tag — pintrk
• Google Tag Manager — gtm.js (categorized as marketing since it typically loads marketing tags)

Necessary Cookies

Necessary cookies are essential for your website to function and are never blocked by RoyalComply, regardless of the visitor's consent choices. These include:

• WordPress sessions — wordpress_logged_in_*, wordpress_sec_*
• WooCommerce cart — woocommerce_cart_hash, woocommerce_items_in_cart, wp_woocommerce_session_*
• PHP session — PHPSESSID
• RoyalComply consent cookie — The cookie that stores the visitor's consent preferences

GDPR (EU)

The General Data Protection Regulation requires an opt-in consent model for EU visitors. This means:

• The consent banner must appear before any non-essential scripts run
• Non-essential cookies must be blocked by default (not just after the user rejects)
• Users must be able to accept or reject each cookie category individually
• Consent must be freely given, specific, informed, and unambiguous
• Consent records must be stored as proof for regulatory audits

RoyalComply satisfies all of these requirements through real script blocking and the consent log feature. Visitor identifiers in the consent log are SHA-256 hashed with your site's unique salt, ensuring no personally identifiable information is stored.

CCPA (California)

The California Consumer Privacy Act uses an opt-out model, meaning businesses must:

• Inform consumers about data collection practices
• Provide a "Do Not Sell My Personal Information" link
• Honor opt-out requests and stop data sales
• Not discriminate against consumers who exercise their rights

RoyalComply supports CCPA by providing the consent banner with a reject option and supporting the Global Privacy Control (GPC) browser signal. When GPC is detected, RoyalComply automatically treats the visitor as having opted out.

US State Privacy Laws

Beyond California, 19 additional US states have enacted privacy legislation. RoyalComply helps you comply with all of them through its consent management framework:

While each state law has unique nuances, they share common themes: notice requirements, opt-out mechanisms, and data protection obligations. RoyalComply's category-based consent and real script blocking provide a solid compliance foundation for all of them.

Google Consent Mode v2

Google Consent Mode v2 is a framework that lets you adjust how Google tags behave based on your visitors' consent status. It is required for EU Google Ads campaigns as of March 2024.

How It Works

When enabled, RoyalComply outputs the following consent defaults before any Google tags load:

gtag('consent', 'default', {
  'ad_storage': 'denied',
  'ad_user_data': 'denied',
  'ad_personalization': 'denied',
  'analytics_storage': 'denied'
});

When a visitor accepts specific categories, RoyalComply updates the consent state:

gtag('consent', 'update', {
  'ad_storage': 'granted',
  'ad_user_data': 'granted',
  'ad_personalization': 'granted',
  'analytics_storage': 'granted'
});

This ensures Google Analytics and Google Ads respect the visitor's consent choices while maintaining measurement capabilities through Google's modeled conversions.

Cookie Scanner

The built-in cookie scanner auto-detects cookies on your site and helps you categorize them correctly.

How It Works

• HTTP header analysis — Detects cookies set via Set-Cookie response headers
• Script pattern matching — Identifies cookies set by known third-party scripts (Google Analytics, Facebook, etc.)
• Built-in database — Matches against a database of 50+ known cookies with pre-assigned categories and descriptions
• Unknown cookie flagging — Cookies not in the database are flagged for manual review and categorization

Consent Log

RoyalComply records every consent decision for audit and regulatory compliance. Each log entry includes:

• Anonymized visitor hash — SHA-256 hash using your site's unique salt (not the visitor's IP or email)
• Country/Region — Detected via CDN headers or timezone fallback
• User agent — Browser and device information
• Page URL — The page where consent was given
• Consent choices — Which categories were accepted or rejected
• Timestamp — When the consent was recorded

Consent records are automatically cleaned up based on the retention period you set (default: 90 days). This keeps your database lean while maintaining audit records for the legally required period.

CSV Export

Export your consent log data as a CSV file for regulatory audits, legal review, or compliance documentation. The export includes all fields from the consent log:

• Visitor hash, timestamp, page URL
• Country/region and user agent
• Individual consent choices per category

Navigate to the Consent Log page and click "Export CSV" to download the full log for the selected date range.

Policy Generator

RoyalComply includes a cookie policy and privacy policy text generator that creates starter text based on:

• Cookies detected by the cookie scanner
• Cookie categories you have enabled
• Your site name and contact information

Geo Detection

RoyalComply uses privacy-respecting methods to detect visitor location for showing region-appropriate consent banners:

Detection Methods (in priority order)

1. Cloudflare header — CF-IPCountry header (if using Cloudflare CDN)
2. CDN headers — X-Forwarded-For and other CDN-provided location headers
3. Browser timezone — Falls back to the visitor's browser timezone to infer region

No external geo-IP API calls are made. All detection happens using data already available in the HTTP request or browser environment. This means zero additional latency and zero third-party dependencies.

Settings Reference

A complete reference of all RoyalComply settings, found under Settings > RoyalComply in your WordPress admin:

Troubleshooting

Scripts still running after blocking is enabled

• Check if the scripts are enqueued via wp_enqueue_script. Raw HTML <script> tags embedded directly in your theme or via a page builder cannot be blocked by the WordPress filter method.
• Solution: Move inline scripts to use wp_enqueue_script or wp_add_inline_script so RoyalComply can intercept them.
• Check your browser's developer tools (Network tab) to verify which scripts are still loading.

Banner not showing

• Ensure the plugin is activated and the banner is enabled in Settings > RoyalComply.
• Check for JavaScript errors in the browser console (F12 > Console) that may prevent the banner from rendering.
• If "Hide for Admins" is enabled, log out or use an incognito window to test.
• Clear any page caching (plugin cache, CDN cache, browser cache) and try again.

Wrong region detected

• If you use Cloudflare, check that the CF-IPCountry header is present in your server's request headers.
• Without a CDN, detection falls back to browser timezone, which provides region-level (not country-level) accuracy.
• You can switch to Manual mode in settings to set a specific region for all visitors if auto-detection is unreliable.

Google Ads showing consent errors

• Enable Google Consent Mode v2 in RoyalComply settings.
• Verify that the gtag('consent', 'default', {...}) call fires before any other Google tags. Check the page source or use Google Tag Assistant to verify tag order.
• Ensure your Google Ads account is set up to use Consent Mode. Check the Consent section in Google Ads settings.

Frequently Asked Questions

Does RoyalComply actually block scripts?

Yes. Unlike most consent plugins that only show a banner, RoyalComply changes the script type attribute to prevent execution until consent is given. This is real blocking, not theater. You can verify this by checking your browser's Network tab before and after giving consent.

Does it work with Google Tag Manager?

Yes. GTM scripts are categorized as marketing and blocked until consent is given. Google Consent Mode v2 consent signals are sent to Google regardless, so GTM can still use consent-based triggers and Google's modeled conversions continue to work.

Is the consent log GDPR compliant?

Yes. Visitor identifiers are SHA-256 hashed with your site's unique salt. No IP addresses, no email addresses, no PII is stored. The consent log exists specifically to provide proof of consent for regulatory audits, which is itself a GDPR requirement.

Does it slow down my site?

No. Frontend CSS and JS combined are under 8KB. Script blocking actually speeds up initial page load since analytics and marketing scripts don't run until consent is given. Visitors who reject non-essential cookies will experience faster page loads throughout their session.

Does it need a SaaS subscription?

No. Everything runs locally on your WordPress site. No external API calls, no cloud services, no ongoing fees. Your consent data stays on your server, under your control.

What happens if a visitor doesn't interact with the banner?

Non-essential scripts remain blocked. GDPR requires explicit consent (opt-in), so silence is not consent. The banner will continue to appear on each page visit until the visitor makes a choice.

Can I customize which scripts go in which category?

Yes. The cookie scanner auto-categorizes known scripts, but you can override the category assignment for any script. Unknown scripts flagged by the scanner can be manually assigned to any category.

Does it support consent-per-purpose for IAB TCF?

RoyalComply uses a simplified 4-category model (Necessary, Analytics, Marketing, Preferences) rather than the full IAB TCF framework. This covers the vast majority of use cases. If you need full IAB TCF 2.2 compliance (typically required only for programmatic advertising), a dedicated CMP may be more appropriate.