ShieldConsent docs

Getting started

ShieldConsent is a WordPress plugin that handles cookie consent, script blocking, and legal proof of consent — entirely from your own server. No cloud, no external API, no data leaving your infrastructure.

Requirements

• WordPress 6.0 or higher
• PHP 7.4 or higher (8.0+ recommended)
• MySQL 5.7+ or MariaDB 10.3+

Installation

Upload the plugin ZIP from Plugins → Add New → Upload Plugin, then activate it. The Setup Wizard starts automatically on first activation.

Setup Wizard

The wizard runs the first time you activate the plugin. You can re-run it any time from ShieldConsent → Settings → Setup Wizard.

Steps

• Welcome — Quick overview.
• Regulations — Pick which privacy laws apply (GDPR, UK GDPR, CCPA, LGPD, Loi 25, nFADP). Each maps visitors from its region to the correct consent mode.
• Protection — Choose how scripts are blocked: signals only (Mode A), standard blocking (Mode B), or advanced/e-commerce (Mode C).
• Appearance — Banner title, text, position, and accent color.
• Analytics — GA4 Measurement ID and/or GTM Container ID. Enable Google Consent Mode v2.
• Categories — Enable or disable categories, edit their descriptions.
• Compliance — Data controller info, DPO, supervisory authority, privacy policy URL, consent duration. Optionally create the Cookie Policy page.
• Scan — Run your first cookie scan.
• Finish — Summary with a compliance score and next steps.

Every setting can be changed later. The wizard just gives you a guided starting point.

Protection modes

Three levels of script blocking, configured under Settings → Protection.

Mode A — Signals only

Sends Google Consent Mode signals (granted/denied) without blocking any scripts. Third-party scripts continue to load normally. Best for simple sites that only use Google services and rely on Google to respect the signals.

Mode B — Standard blocking

Blocks third-party scripts by category (analytics, marketing, bot protection) until the visitor gives consent. Scripts are detected by domain and neutralized server-side in the HTML buffer before the page reaches the browser. This is the recommended mode for most sites.

Mode C — Advanced blocking (e-commerce)

Everything in Mode B, plus a smart whitelist for WooCommerce. Automatically detects checkout, cart, and account pages and unblocks payment gateways (Stripe, PayPal, Klarna, Mollie, Braintree, Square, Razorpay, Google Pay, Apple Pay and more) so checkout is not disrupted by consent requirements. You can also allow reCAPTCHA without consent.

Banner & customizer

The visual customizer is under Settings → Appearance. Every change shows a live preview.

What you can control

• Accent color — 6 presets or any custom hex value.
• Banner background — White, light gray, warm cream, or dark. Text color auto-switches.
• Corner radius — Sharp (0px), Subtle (8px), Rounded (16px), Extra Rounded (24px).
• Shadow depth — None, Subtle, Medium, or Strong.
• Title icon — Shield, Cookie, Fingerprint, Lock, Sliders, or none.
• Button gradient — Toggle gradient on the Accept button.
• Button icon — Small icon inside the Accept button.
• Banner position — Bottom bar, floating card (left/right), top bar, or centered modal.

Consent modes

• Opt-in — Scripts blocked until the visitor accepts. Required for GDPR (EU).
• Opt-out — Scripts load by default, visitor can decline. Suitable for CCPA (US).
• Notice — Informational only, no blocking. Banner dismisses on click.

Auto-fill

Click "Auto-fill" in Settings → Appearance and all text fields (banner title, description, category labels, button labels) are pre-filled in your site language. Also available per language in the Translations tab.

Dark-themed sites

Background color and text color are independent. Set a dark background with light text, and all buttons, links and icons adapt automatically. The live preview in Settings shows exactly how it looks.

Cookie Scanner

The scanner identifies cookies on your site and matches them against the Open Cookie Database (2,200+ entries from 350+ platforms). Access it under ShieldConsent → Cookie Scanner.

How it works

Select the pages you want to scan — up to 20 at a time. By default, the homepage and your most recently modified pages are pre-selected. You can search for specific pages or add any custom URL.

For each selected page, the scanner performs a two-phase detection:

• Server-side (HTTP) — Fetches the page and reads Set-Cookie headers from the response.
• Client-side (Deep Scan) — Opens the page in a hidden iframe in your browser to detect cookies set by JavaScript after page load.

Every detected cookie is matched against the built-in database and the Open Cookie Database for automatic identification, categorization, and vendor attribution.

Enhanced scan

Enable Enhanced scan before running a scan to simulate scroll behavior. The scanner auto-scrolls to the bottom of each page, triggering lazy-loaded scripts, delayed tracking pixels, and scroll-activated cookies. It also uses a MutationObserver to catch dynamically injected scripts. Takes about 15 seconds longer per page, but catches cookies that only appear after user interaction.

Scheduled scans

Automate your scans from Settings → Scheduled Scan. Choose a frequency — daily, weekly, or monthly — and ShieldConsent runs the scan in the background via WP-Cron. The scheduled scanner covers the homepage plus your most recently modified pages and posts (configurable, max 200 — 50 is recommended for most sites). When new or unknown cookies are detected, you receive a report by email.

Third-Party Tracker Report

After each scan, a network analysis report shows every third-party domain contacted during the scan, matched against a database of known trackers. This helps identify tracking scripts that may not set cookies but still collect data (tracking pixels, beacons, fingerprinting scripts).

Cookie Catalog

Scanned cookies can be added to your catalog — either automatically (with the "auto-add" option) or manually by selecting individual cookies. The catalog is organized by category and powers the cookie table on your cookie policy page. Unrecognized cookies can be manually categorized, described, and assigned a vendor.

Cookie Monitor

The Cookie Monitor is a passive, real-traffic detection system. Instead of scanning pages once, it observes cookies set by actual visitors over a configurable time window — 24, 48, or 72 hours.

Why it matters

A traditional scanner visits pages as a clean visitor and captures whatever cookies appear in the first few seconds. But many cookies only appear after real user interactions — clicking a button, scrolling down, adding to cart, logging in, submitting a form, watching a video. The Cookie Monitor captures all of these naturally, because real visitors do real things.

How it works

When you activate the monitor, a lightweight micro-script (~800 bytes gzipped) is injected on every page of your site via wp_footer. The script is pure vanilla JavaScript — no jQuery, no external dependency.

• Periodically polls document.cookie to detect new cookies.
• Buffers newly detected cookie names and flushes them to the server in batches via navigator.sendBeacon() (with XHR fallback).
• Sends only cookie names and the page path — never cookie values, never visitor identity.
• Self-disables when the configured time window expires (checked both client-side and server-side).

Privacy & performance

The monitor is designed to be invisible and GDPR-safe:

• No cookies are set by the monitor itself.
• No visitor identification or fingerprinting — only technical cookie names and page URLs are collected.
• WordPress admin cookies (wordpress_*, wp-settings-*, etc.) are automatically filtered out server-side.
• Beacons are rate-limited per IP and the script only sends data when it has new cookies to report.
• An automatic safety valve pauses monitoring if beacon volume exceeds a threshold, protecting your server from unexpected traffic spikes.

Using the monitor

Find the Cookie Monitor section under ShieldConsent → Cookie Scanner, below the scan results.

• Choose a duration (24h, 48h, or 72h) and click Start Monitoring.
• The status bar shows elapsed time and time remaining. A green "LIVE" badge confirms monitoring is active.
• You can close your browser — monitoring runs autonomously as long as your site receives traffic.
• Click Refresh at any time to see detected cookies so far. The report auto-refreshes every 30 seconds while you're on the page.
• Each detected cookie is enriched with its category, vendor, description, hit count, and the pages where it was seen.
• Cookies not already in your catalog are flagged as New — select them and click Add Selected to Catalog to merge them.

Expiration email report

When the monitoring window expires, ShieldConsent automatically sends a summary email to the site administrator. The email includes the total number of cookies observed, how many are already in the catalog, and a detailed list of new cookies not yet declared — with their detected category, vendor, and hit count.

The email is sent via WP-Cron at the exact expiration time. On low-traffic sites where WP-Cron may be delayed, a fallback triggers the email on the next admin page load. The email is sent exactly once — duplicate prevention is built in.

Cookie categories

6 built-in categories, each can be enabled/disabled with editable titles and descriptions (per language).

• Essential — Always active. Login, cart, security tokens.
• Functional — Preferences, language settings, embedded content.
• Analytics — Traffic measurement (GA4, Hotjar, Matomo, etc.).
• Marketing — Advertising pixels, retargeting (Facebook Pixel, Google Ads, TikTok, etc.).
• Security — Security-related services and monitoring.
• Bot protection — Challenge widgets (reCAPTCHA, hCaptcha, Turnstile).

Configure categories under Settings → Categories.

Google Consent Mode v2

ShieldConsent sends consent signals automatically to Google services based on the visitor's choice. Required since March 2024 for EU ad measurement.

Signals sent

• ad_storage — Advertising cookies (Google Ads, remarketing).
• analytics_storage — Analytics cookies (GA4).
• ad_user_data — User data for advertising purposes.
• ad_personalization — Personalized advertising.
• functionality_storage — Functional cookies.
• personalization_storage — Personalization cookies.
• security_storage — Security cookies.

Enable it under Settings → Analytics with your GA4 Measurement ID and/or GTM Container ID. No manual tag configuration needed.

Content Blocker

Automatically detects and blocks third-party iframes, replacing them with a consent placeholder that matches the original dimensions.

Supported services

• Video: YouTube, Vimeo, Dailymotion, TikTok, Twitch, Wistia, Loom, Rumble, Vidyard
• Social: X (Twitter), Instagram, Facebook, Pinterest, LinkedIn, Reddit, Threads
• Audio: Spotify, SoundCloud, Apple Podcasts, Deezer, Anchor
• Maps: Google Maps, OpenStreetMap

When the visitor consents to the relevant category, the original iframe is restored. YouTube embeds show a video thumbnail in the placeholder.

Cookie Cleaner

When a visitor refuses a cookie category, ShieldConsent actively deletes known tracking cookies that may have been set previously. The cleaner works both server-side (PHP, via Set-Cookie headers) and client-side (JavaScript, via document.cookie).

What it covers

• Analytics: Google Analytics (_ga, _gid, _gat, _ga_*), Matomo (_pk_*), Hotjar (_hj*), Clarity (_clck, _clsk), Amplitude, Mixpanel, Segment, FullStory, Mouseflow, Lucky Orange, Sourcebuster, Jetpack Stats, and more.
• Marketing: Meta/Facebook (_fbp, _fbc), Google Ads (_gcl_*), TikTok, LinkedIn, Twitter/X, Pinterest, Snapchat, Microsoft/Bing, Criteo, HubSpot, Intercom, Drift, MailPoet, DoubleClick.
• Functional: WooCommerce cart/session, Stripe, PayPal, Mollie, Klarna (non-HttpOnly cookies only).
• Security: Cloudflare (__cf_bm, cf_clearance).

Cookies are matched against the Cookie Catalog (populated by the scanner) first, then against built-in patterns as a safety net. Each denied category is cleaned independently — refusing analytics does not affect marketing cookies, and vice versa.

What it cannot do

• Third-party domain cookies — Cookies set on .google.com, .facebook.com, or any domain other than yours cannot be deleted by JavaScript or PHP. This is a browser security restriction that applies to all CMPs. ShieldConsent blocks the scripts that create these cookies, but pre-existing third-party cookies persist until they expire.
• HttpOnly cookies — Some cookies (Stripe, Cloudflare session tokens, WooCommerce sessions) are marked HttpOnly by the server, making them invisible to JavaScript. These are cleaned server-side by PHP on the next page load.
• localStorage / sessionStorage / IndexedDB — The Cookie Cleaner targets HTTP cookies only. Some modern trackers also store data in browser storage APIs. ShieldConsent prevents these scripts from running (which prevents storage writes), but data from a previous session is not cleared.

Geolocation

Detects the visitor's country and automatically applies the correct consent mode per region.

Detection methods

• CDN/proxy headers — Cloudflare CF-IPCountry, Vercel, etc.
• Geolocation API — Configurable external API endpoint.
• Server GeoIP header — Server-level headers set by your hosting provider.

Recognized regions

• EU + EEA (30 countries) — Opt-in (GDPR).
• UK + Switzerland — Opt-in.
• Brazil — Opt-in (LGPD).
• US states with privacy laws — California (CCPA/CPRA), Virginia (VCDPA), Colorado (CPA), Connecticut (CTDPA), Montana (MCDPA), and more as legislation evolves. Opt-out + GPC enforcement.

Page caching compatibility

When geolocation is enabled, ShieldConsent signals caching plugins to bypass full-page caching via DONOTCACHEPAGE, Cache-Control: no-store headers, and plugin-specific hooks (WP Rocket, LiteSpeed, Kinsta, Cloudflare APO). A runtime geo-fix script corrects the consent mode if a stale cached version is served.

Languages & RTL

The banner detects the visitor's browser language and shows the matching translation. Arabic visitors get proper RTL layout automatically.

Add translations for any language from Settings → Translations. 53 languages are available in total:

36 languages with one-click auto-fill: English (US + GB), Bulgarian, Croatian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Greek, Hungarian, Irish, Italian, Latvian, Lithuanian, Maltese, Norwegian, Polish, Portuguese (PT + BR), Romanian, Slovak, Slovenian, Spanish, Swedish, Welsh, Arabic, Chinese (Simplified & Traditional), Hebrew, Hindi, Japanese, Turkish, and Vietnamese.

17 additional languages with manual entry: Albanian, Basque, Bosnian, Catalan, Filipino, Galician, Icelandic, Indonesian, Korean, Luxembourgish, Macedonian, Malay, Persian, Russian, Serbian, Thai, and Ukrainian. Select the language, fill in the banner and modal fields, and the consent banner will display in that language for matching visitors.

Need a language not listed above? Use the custom locale field to add any locale code manually.

IAB TCF 2.3

ShieldConsent implements the IAB Transparency & Consent Framework 2.3, including the CMP API (window.__tcfapi) and the consent string (TC string) required by participating vendors.

Enable it under Settings → Advanced → TCF.

Consent Logs & storage

Where is consent data stored?

• Browser cookies — An HttpOnly server-side cookie (source of truth) and a JavaScript-readable cookie (UI state).
• WordPress database — A dedicated table (wp_shieldconsent_logs). No data is sent to external servers.

Retention

Configurable in Settings → Legal. Old records are automatically deleted via WP-Cron. You can also delete records manually at any time.

Data integrity

Each consent record includes a SHA-256 integrity hash. Consent records are stored as standard database rows — the website operator retains full control.

Is ShieldConsent a data processor?

No. ShieldConsent does not transmit, receive, or store any consent data on external servers. All data stays on your infrastructure. There are no third-party data transfers to justify under GDPR Article 28.

Legal Proof & Audit

Individual consent proof

Each consent event generates a document containing the visitor's decision, timestamp, exact banner and category texts (in the visitor's language), policy version, and SHA-256 integrity hash. Download as PDF or HTML.

Legal ZIP bundle

An audit-ready package containing: consent dossier (CMP setup overview), settings snapshot, cookie catalog, and all consent logs. Supports GDPR Article 5 (accountability).

Audit Log

A journal of consent activity with filters, exports (CSV/JSON), and formal audit generation (PDF/HTML). Access it under ShieldConsent → Audit Log.

Cookie policy page

Generates a complete cookie policy page with a customizable introduction, a cookie table (auto-populated from your scan results, grouped by category), international data transfer information, browser instructions, and a customizable outro.

Create the page from Settings → Compliance or use the shortcode [shieldconsent_cookie_policy] on any page.

Dashboard & statistics

The dashboard under ShieldConsent → Dashboard shows:

• Consent rate over time (7, 30, 90, or 365 days)
• Decision distribution (accepted / refused / custom)
• Category acceptance rates
• Device breakdown (desktop / mobile / tablet)
• Hourly activity
• Language breakdown
• Source breakdown (banner / modal / floating button)
• Compliance score (checks your configuration against best practices)

Shortcodes

[shieldconsent_manage_consent]

Renders a "Manage cookies" button that reopens the consent modal. Attributes: label (button text), tag (button or a), class (CSS class).

[shieldconsent_cookies_table]

Displays a table of cookies from your scan results, grouped by category. Attribute: category (filter by a specific category key).

[shieldconsent_consent_proof]

Shows the current visitor's consent status: decision, timestamp, categories, and a link to modify preferences.

[shieldconsent_cookie_policy]

Generates a full cookie policy page with intro, cookie table, data transfer section, browser instructions, and outro.

WooCommerce

ShieldConsent includes a smart whitelist for WooCommerce (requires Protection Mode C).

What it does

• Auto-detects checkout, cart, and account pages.
• Unblocks Stripe, PayPal, Klarna, Mollie, Braintree, Square, Razorpay, Google Pay, Apple Pay and more on those pages.
• Optionally allows reCAPTCHA without consent.

No configuration needed — activate Mode C and WooCommerce pages are handled automatically.

Script whitelisting

Beyond WooCommerce, you can add custom managed endpoints (URL patterns always allowed through) and assign scripts to the strictly_necessary category so they're never blocked.

Import / Export

Export your entire ShieldConsent configuration as a JSON file from Settings → Import/Export. Import it on another site to replicate your setup — categories, appearance, protection mode, compliance settings, translations, and managed endpoints.

Useful for agencies managing multiple client sites with a consistent configuration.

Diagnostics

The Diagnostics page under ShieldConsent → Settings helps you detect issues:

• Google Site Kit detection — Warns if Site Kit may inject tracking independently of ShieldConsent.
• Competing plugins — Detects MonsterInsights, ExactMetrics, Insert Headers and Footers, etc.
• Database schema — Checks if the consent logs table is correctly created.
• Front-end scan — Fetches your home page HTML and looks for Google Fonts, reCAPTCHA, GTM/gtag snippets that might fire before consent.

Known limitations

ShieldConsent provides comprehensive cookie consent management, but like all consent management platforms, it operates within the constraints of browser security, server architecture, and third-party services. Understanding these boundaries helps you configure your site correctly.

Third-party domain cookies

When a third-party script (e.g., Facebook Pixel) sets a cookie on its own domain (.facebook.com), neither JavaScript nor PHP on your domain can delete it. This is a fundamental browser security restriction. ShieldConsent blocks the scripts that create these cookies, preventing them from being set. However, if a third-party cookie was set during a previous visit (before the plugin was installed or before the visitor refused consent), it persists until the browser clears it or the cookie expires.

Page caching & CDN compatibility

ShieldConsent filters scripts at the PHP level via output buffering. This works well with most caching plugins because the filtered HTML is what gets cached. However, certain edge cases require attention:

• Full-page edge caches (Cloudflare APO, Varnish, some hosting-level caches) may serve static HTML without executing PHP at all. In this case, purge the cache after installing ShieldConsent so the filtered version is cached.
• JS minification/concatenation — If an optimization plugin (WP Rocket, Autoptimize, LiteSpeed Cache) combines tracking scripts with other scripts into a single hashed file, ShieldConsent may not recognize the resulting filename. Exclude tracking scripts from JS concatenation, or add the combined file to Managed Endpoints.
• Geolocation + caching — When geolocation is enabled, ShieldConsent automatically signals caching plugins to bypass full-page caching. A runtime geo-fix script corrects the consent mode if a stale cached page is served.

Google Tag Manager as a container

ShieldConsent blocks or unblocks the GTM container script based on consent, and sends Google Consent Mode v2 signals that well-configured tags respect. However, ShieldConsent has no visibility into what tags are configured inside GTM. If a marketing team adds a new tag in GTM without configuring it to check Consent Mode, that tag will fire once the container is loaded — regardless of the visitor's preferences.

Recommendation: Ensure all tags in your GTM container are configured to respect Consent Mode signals. This is a GTM-side configuration step, not a ShieldConsent setting.

Setting up Google tags correctly

Option 1 — Via GTM (recommended): Enter your GTM container ID in ShieldConsent settings. Add your GA4 property and Google Ads conversion tag inside GTM with an "All Pages" trigger. ShieldConsent loads the GTM container only when analytics consent is granted and sends Consent Mode v2 signals, so marketing tags inside GTM are gated automatically.

Option 2 — Without GTM: Enter your GA4 Measurement ID (G-XXXXXXX) in ShieldConsent → Protection. ShieldConsent will inject and block the gtag.js script until consent. For Google Ads, add the Ads script URL pattern (e.g., gtag/js?id=aw-) to your Managed Endpoints so ShieldConsent blocks it until marketing consent.

localStorage, sessionStorage, IndexedDB

The Cookie Cleaner targets HTTP cookies only. Some modern analytics and marketing platforms also store identifiers in browser storage APIs (localStorage, sessionStorage, IndexedDB). ShieldConsent prevents these scripts from running when consent is not given (which prevents storage writes), but data written during a previous session with consent is not automatically cleared upon revocation.

Consent proof and network failures

The visitor's consent choice is always saved in a client-side cookie, so the visitor is protected regardless of server response. If the AJAX request to save the consent log fails (due to a 502 error, timeout, or network issue), the server-side audit trail may be incomplete for that specific visitor. The cookie serves as proof of consent, but the detailed log entry (with timestamp, policy version, and category breakdown) may be missing. On shared hosting with strict timeout limits, oversized request headers from many cookies can occasionally trigger this.

Troubleshooting

The banner doesn't appear

• Is the plugin activated?
• Is the consent mode set to "hidden" for your region (geolocation)?
• Is there already a valid consent cookie? Clear cookies or use incognito.
• Is a caching plugin serving a stale page? Purge your cache.
• Check Settings → Diagnostics for competing plugins.

Scripts still load before consent

• A caching plugin cached the page before ShieldConsent was activated — purge the cache.
• A competing plugin (Site Kit, MonsterInsights) injects tracking independently — run Diagnostics.
• The script is not in the known registry — add it manually in Settings → Managed Endpoints.

Google Analytics shows no data

This is expected if visitors haven't consented to analytics yet. GA4 data resumes once visitors accept. With Consent Mode v2, GA4 uses cookieless modeling to estimate data for non-consenting users.

Page reloads in a loop (Firefox private browsing)

Firefox private browsing sends the GPC signal by default. If "Auto reload on consent" is enabled AND GPC enforcement is active, this can cause a loop. Fix: disable "Auto reload on consent" in Settings.

Banner appears in the wrong language

ShieldConsent automatically detects the visitor's language via the Accept-Language header sent by the browser. If your banner shows in an unexpected language (Chinese, Arabic, etc.), the issue is almost certainly in your browser's language settings — not the plugin.

• Chrome: go to Settings → Languages and remove any language you don't use.
• macOS: also check System Settings → General → Language & Region → Preferred Languages.

Each browser manages its own language list, independently from the operating system. Note that extensions are disabled in private/incognito mode, which may explain different behavior between normal and private browsing. After correcting your settings, clear your browser cache and reload the page.