# RoyalComply Documentation

> RoyalComply cookie compliance guide: real script blocking, GDPR and CCPA compliance, Google Consent Mode v2, and consent audit logging, no SaaS dependency.

- Canonical: <https://royalplugins.com/support/royal-comply/>
- Last updated: 2026-08-21
- HTML version: <https://royalplugins.com/support/royal-comply/>

---

Complete guide to cookie consent and privacy compliance with RoyalComply. Configure real script blocking, GDPR/CCPA compliance, Google Consent Mode v2, and consent audit logging.

## 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

#### GDPR Requirement

EU law requires opt-in consent before setting non-essential cookies. Violations can result in fines up to 4% of annual revenue.

#### CCPA & US State Laws

California and 19 other US states have privacy laws requiring consent mechanisms. The landscape is expanding rapidly.

#### Google Requirements

Google Consent Mode v2 is required for EU ad campaigns. Without it, Google Ads and GA4 data collection may be limited.

#### Real Blocking

Most consent plugins only show a banner. RoyalComply actually prevents scripts from executing until consent is given.

### Requirements

- WordPress 5.9 or higher
- PHP 7.4 or higher

## Installation

### From WordPress.org

#### Search for the plugin

In your WordPress admin, go to Plugins > Add New and search for "RoyalComply"

#### Install and activate

Click "Install Now" then "Activate" once installation completes

#### Configure settings

Navigate to Settings > RoyalComply in your admin menu to begin setup

### Manual Installation

#### Download the plugin

Download the ZIP file from [WordPress.org](https://wordpress.org/plugins/royalcomply/)

#### Upload to WordPress

Go to Plugins > Add New > Upload Plugin, select the ZIP file, and click Install Now

#### Activate the plugin

Click "Activate Plugin" after installation completes

## Quick Start

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

#### Navigate to RoyalComply

Go to Settings > RoyalComply in your WordPress admin

#### Configure your banner

Choose position (top, bottom, center, etc.), colors, and consent text

#### Enable script blocking

Toggle on script blocking to actually prevent analytics and marketing scripts until consent is given

#### Enable Google Consent Mode

If you use Google Analytics or Ads, enable GCM v2 for proper consent signaling

#### Run the cookie scanner

Auto-detect cookies on your site and categorize them

#### Review consent log

Verify consent records are being logged for GDPR audit compliance

Recommendation

Enable script blocking FIRST, then test your site to make sure essential functionality works. Necessary cookies (WordPress sessions, WooCommerce cart) are never blocked.

## 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:

| Position | Layout | Description |
| --- | --- | --- |
| Top | Bar | Full-width bar fixed to the top of the viewport |
| Bottom | Bar | Full-width bar fixed to the bottom of the viewport (most common) |
| Left | Box | Floating box in the bottom-left corner |
| Right | Box | Floating box in the bottom-right corner |
| Center Fixed | Box | Centered modal overlay with backdrop |
| Slide-in | Box | Slides in from the bottom-right after a short delay |

## 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:

| Category | Blocked? | Examples |
| --- | --- | --- |
| **Necessary** | Never blocked | WordPress sessions, WooCommerce cart, PHP sessions |
| **Analytics** | Until consent | Google Analytics, Hotjar, Microsoft Clarity, Matomo |
| **Marketing** | Until consent | Facebook Pixel, Google Ads, LinkedIn Insight, TikTok |
| **Preferences** | Until consent | Language settings, theme preferences, site personalization |

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.

Important: Script Enqueue Requirement

If you embed third-party scripts via raw HTML (not `wp_enqueue_script`), RoyalComply cannot block them via the filter method. Use `wp_enqueue_script` for all third-party scripts to ensure they can be properly blocked.

## 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 Exemption

Under GDPR Article 5(3), cookies that are "strictly necessary" for a service explicitly requested by the user are exempt from consent requirements. Session cookies, shopping cart cookies, and consent-recording cookies all fall under this exemption.

## 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:

| State | Law |
| --- | --- |
| Virginia | VCDPA |
| Colorado | CPA |
| Connecticut | CTDPA |
| Utah | UCPA |
| Tennessee | TIPA |
| Indiana | ICDPA |
| Montana | MTCDPA |
| Texas | TDPSA |
| Oregon | OCPA |
| Delaware | DPDPA |
| Florida | FDBR |
| New Jersey | NJDPA |
| New Hampshire | NHDPA |
| Kentucky | KCDPA |
| Nebraska | NEBDPA |
| Iowa | ICDPA |
| Maryland | MCDPA |
| Minnesota | MNDPA |

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.

GCM v2 Requirements

Google requires both `ad_user_data` and `ad_personalization` consent signals (in addition to `ad_storage` and `analytics_storage`). RoyalComply sends all four signals automatically.

## 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

Run the Scanner Regularly

Run the cookie scanner after installing new plugins or adding third-party integrations. New plugins may introduce cookies that need to be categorized.

## 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

Zero PII Storage

No IP addresses, email addresses, or other personally identifiable information is stored in the consent log. Visitor identification uses only a SHA-256 hash of browser fingerprint data combined with your site's unique salt.

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

Not Legal Advice

The generated policy text is a starting point, not a substitute for professional legal review. Customize the generated text for your specific jurisdiction and business practices. Privacy laws vary by region and industry.

## 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.

Best Results with Cloudflare

If your site uses Cloudflare (free plan is sufficient), geo detection will be highly accurate using the `CF-IPCountry` header. Without a CDN, the timezone fallback provides reasonable region-level accuracy.

## Settings Reference

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

| Setting | Default | Description |
| --- | --- | --- |
| Region Detection Mode | Auto | Auto (CDN headers + timezone) or Manual (set region manually) |
| Script Blocking | On | Toggle real script blocking on or off. Strongly recommended to keep ON. |
| Google Consent Mode | Off | Enable Google Consent Mode v2 consent signaling for Google tags |
| Consent Expiry | 365 days | How long the consent cookie lasts before the visitor is asked again |
| Logging Retention | 90 days | How long consent log records are kept before automatic cleanup |
| Hide for Admins | On | Don't show the consent banner to logged-in users with `manage_options` capability |

## 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.

[Back to Support](https://royalplugins.com/support/)
[Royal Access Docs](https://royalplugins.com/support/royal-access/)