If your WordPress site uses Google Analytics, Meta Pixel, or any other tracking tool, you need a cookie consent WordPress plugin — not just a banner. Under GDPR, CCPA, and Google’s own advertising policies, tracking scripts must not fire until a visitor actively gives consent. That means you need proper script blocking, a consent-aware banner, and Google Consent Mode v2 integration. CookieRay delivers all three in a single free plugin — with no external SaaS dashboard, no data sent off your server, and no monthly subscription for the essentials. This guide walks you through everything: installing CookieRay, configuring your banner, enabling strict script blocking, connecting Google Consent Mode v2, running a cookie scan, and reviewing your compliance score. Whether you’re building a new site or fixing an existing one, you’ll finish this tutorial fully set up and GDPR-ready.
Table of Contents
What Is CookieRay and Why Use It?
CookieRay is a free WordPress cookie consent plugin that lets you display a compliant consent banner, block tracking scripts until consent is given, output Google Consent Mode v2 signals, scan your site for cookies, and log every consent decision — all without sending data to any external server. It was built by DevItems LLC and is available on WordPress.org at no cost, with an optional Pro upgrade starting at $49/year for agencies and multi-site operators.
What Makes CookieRay Different from Other Cookie Consent Plugins?
Most free cookie consent plugins only display a banner. They don’t actually block scripts, they don’t integrate with Google Consent Mode v2, and they ship your visitor consent data to an external SaaS platform you don’t own. CookieRay takes a different approach:
- No external SaaS dashboard — everything runs inside your WordPress admin
- No raw IP storage — visitor fingerprints are hashed from combined signals
- Strict script blocking — delays GA4, Meta Pixel, Hotjar, HubSpot, TikTok Pixel and more until consent is given
- Google Consent Mode v2 — outputs proper consent signals so Google tags adjust their behavior
- On-site cookie scanner — crawls up to 50 pages of your own site, surfaces cookies, and merges them into categories
- Consent logs with CSV and PDF export — a full audit trail for GDPR accountability
For WordPress site owners who want a lightweight, privacy-by-design tool that doesn’t create a new external dependency, CookieRay is the logical choice.
Who Should Use CookieRay?
- WordPress bloggers and content creators using Google Analytics
- WooCommerce stores that need GDPR and CCPA compliance
- Agencies managing multiple client sites (Pro plan)
- Developers who want a self-hosted, data-on-your-server solution
- Any site served to EU residents — compliance is required regardless of where you’re based
What Is Google Consent Mode v2 and Why Does It Matter?
Google Consent Mode v2 is Google’s framework for adjusting the behavior of Google tags — GA4, Google Ads, GTM — based on the consent choices a visitor makes on your site. Without it, if a visitor declines cookies, Google has no way to know that. Its scripts may still attempt to fire (depending on how your plugin blocks them), and your advertising data modeling breaks down.
The Four Consent Signals in Google Consent Mode v2
Google Consent Mode v2 introduces four key consent parameters that your plugin must pass to the browser:
- analytics_storage — controls whether Google Analytics can store cookies and measure sessions
- ad_storage — governs whether Google Ads can use cookies for conversion tracking
- ad_user_data — determines whether user data from your site can be sent to Google for advertising
- ad_personalization — controls personalized advertising and remarketing
When a visitor declines all non-essential cookies, your cookie consent plugin must signal ‘denied’ for all four of these parameters. When they accept, it signals ‘granted’. CookieRay handles this automatically once you enable the GCM v2 toggle in its settings.
Basic vs. Advanced Consent Mode: What’s the Difference?
In Basic Consent Mode, Google tags do not fire at all until the visitor accepts. This is the most privacy-preserving option but also means you lose conversion modeling for users who decline. In Advanced Consent Mode, Google tags load in a restricted mode before consent — they don’t set cookies or track sessions, but they do allow Google’s modeling to fill data gaps. CookieRay supports both modes. Most sites benefit from Advanced mode, as it preserves ad measurement modeling while still respecting user choices.
Why Google Now Requires Consent Mode for EEA Advertising
As of March 2024, Google requires certified Consent Management Platform (CMP) integration for all advertisers running campaigns targeting the European Economic Area. Without proper Google Consent Mode v2 implementation, your ad performance data will degrade and Google’s conversion modeling will not function. CookieRay implements the required consent signals directly, ensuring your Google Ads and GA4 data remain as accurate as possible within legal limits.
Installing CookieRay on WordPress
Installing CookieRay takes less than two minutes. There are two ways to do it: directly from the WordPress plugin directory or via WP-CLI.
Method 1: Install from WordPress Dashboard
- Log in to your WordPress admin panel.
- Navigate to Plugins → Add New.
- Search for ‘CookieRay’ in the search bar.
- Click Install Now on the CookieRay plugin card.
- Once installed, click Activate.
- You’ll be automatically redirected to the CookieRay Setup Dashboard.
Method 2: Install via WP-CLI
If you manage WordPress from the command line, you can install and configure CookieRay with a single command sequence:
wp plugin install cookieray –activate
Once activated, you can also configure the core settings from the CLI, which is useful for staging and production deployments.
What Happens After Activation
When you activate CookieRay for the first time, the plugin creates its database tables for consent logs and cookie inventory, then redirects you to the Setup Dashboard. This dashboard displays a compliance score (0–100) based on how many key settings are configured. It’s your roadmap through the entire setup process.
Configuring the Cookie Consent Banner
The consent banner is the first thing visitors see, so getting it right matters — both for compliance and for conversion. CookieRay gives you full control over layout, position, colors, text, and button labels, all with a live preview inside the admin.
Choosing a Banner Layout
CookieRay offers two core layouts:
- Card layout — A centered popup or corner card that floats above page content. Ideal for sites that want the consent decision made before the visitor interacts with content.
- Bar layout — A full-width bar at the top or bottom of the screen. Less intrusive, but still clearly visible.
The plugin supports 9 placement positions, giving you fine-grained control over where the banner appears. For GDPR compliance, a card layout placed centrally tends to get clearer and more deliberate consent decisions from visitors.
Configuring Button Labels and Consent Options
Your banner must offer three clear choices to comply with GDPR’s requirement for meaningful consent:
- Accept All — grants all consent categories
- Decline All — rejects all non-essential cookies and signals ‘denied’ to Google Consent Mode
- Preferences / Manage Cookies — opens a modal where visitors can toggle individual categories (Necessary, Analytics, Marketing, Functional)
CookieRay generates all three by default. You can customize the button text, colors, and order directly in the Banner Settings panel. Make sure your ‘Decline All’ option is as visually prominent as ‘Accept All’ — EU regulators have issued fines for dark patterns where rejection was deliberately hidden or minimized.
Customizing Colors and Branding
The live preview editor lets you set background color, button colors, text color, and font size. There are no restrictions on styling in the free version. Use colors consistent with your brand, but ensure sufficient contrast between button labels and backgrounds for WCAG accessibility compliance.
Adding Your Privacy Policy Link
Every cookie consent banner must link to your Privacy Policy. In CookieRay’s banner settings, you can specify the URL and anchor text for this link. If you don’t have a privacy policy page yet, create one in WordPress (Pages → Add New) before completing the banner configuration. The Setup Dashboard will flag this as missing and deduct points from your compliance score.
Enabling Strict Script Blocking
Script blocking is the most critical technical component of GDPR-compliant cookie consent. A banner that shows but doesn’t actually prevent tracking scripts from loading is not compliant — it’s decoration. CookieRay’s strict mode delays known trackers until the visitor’s consent categories cover them.
How CookieRay’s Script Blocking Works
CookieRay uses a frontend interception approach. When strict blocking is enabled, the plugin rewrites the type attribute of matching script tags from ‘text/javascript’ to a placeholder type that browsers ignore. The scripts are held in a queue. Once the visitor makes a consent decision, CookieRay evaluates which categories were granted, re-enables matching scripts, and they execute in order.
This approach works without a server-side proxy, meaning it’s compatible with any WordPress hosting environment and doesn’t require you to reroute traffic through a CDN or external service.
Which Trackers Does Strict Blocking Cover?
CookieRay’s built-in blocking rules cover the most common tracking services:
- Google Analytics 4 (GA4) — analytics_storage category
- Google Ads — ad_storage and ad_user_data categories
- Meta Pixel (Facebook Pixel) — marketing category
- Hotjar — analytics category
- HubSpot tracking — marketing category
- TikTok Pixel — marketing category
- LinkedIn Insight Tag — marketing category
Custom or less common scripts can be added manually via the Script Blocking configuration panel. If you’re using a less-common analytics or ad tool, you’ll need to add its domain or script identifier manually. CookieRay also offers a ‘Log Only’ mode if you want to observe consent behavior before enforcing blocking — useful when migrating from a passive banner setup.
How to Enable Strict Blocking
- Go to CookieRay → Settings in your WordPress admin.
- Find the Script Blocking section.
- Set the blocking mode to Strict.
- Save your settings.
- Open your site in an incognito browser window, decline all cookies, and check the Network tab in DevTools — analytics and marketing scripts should not appear as loaded requests.
Testing Script Blocking Correctly
Always test in an incognito or private window, since your regular browser session may already have a stored consent decision. In Chrome DevTools (F12), open the Network tab and filter by ‘JS’. After declining all cookies, you should see no requests to google-analytics.com, connect.facebook.net, or other tracking domains. If they appear, check whether your caching plugin is interfering — aggressive HTML caching can bypass CookieRay’s script interception.
Setting Up Google Consent Mode v2 in CookieRay
With script blocking set up, your next step is enabling Google Consent Mode v2. This ensures that when a visitor declines cookies, the correct denial signals are sent to Google’s data layer — allowing conversion modeling to partially compensate for data gaps without violating privacy.
Enabling GCM v2 in CookieRay Settings
- Navigate to CookieRay → Settings.
- Find the Google Consent Mode v2 section.
- Toggle the GCM v2 switch to On.
- Choose your preferred consent mode: Basic or Advanced.
- Save settings.
Once enabled, CookieRay outputs the required gtag consent commands in the <head> of every page, before any Google tags load. This is the ‘default denied’ state required by GDPR for visitors in the EEA.
How CookieRay Outputs GCM v2 Signals
When a visitor loads your page, CookieRay injects the following pattern into the browser’s data layer before any other scripts run:
gtag(‘consent’, ‘default’, { analytics_storage: ‘denied’, ad_storage: ‘denied’, ad_user_data: ‘denied’, ad_personalization: ‘denied’ });
When the visitor accepts all cookies, CookieRay updates the consent state:
gtag(‘consent’, ‘update’, { analytics_storage: ‘granted’, ad_storage: ‘granted’, ad_user_data: ‘granted’, ad_personalization: ‘granted’ });
If the visitor selects only analytics cookies, only analytics_storage is set to ‘granted’. This granular consent mapping is what sets a full cookie consent WordPress plugin apart from a simple banner.
Verifying Google Consent Mode v2 Is Working
After enabling GCM v2, verify it’s working with these steps:
- Open your site in an incognito window.
- Open Chrome DevTools → Console.
- Type ‘dataLayer’ and press Enter.
- Before interacting with the banner, all four consent parameters should show as ‘denied’.
- Accept all cookies and re-run the command — all four should now show as ‘granted’.
You can also use Google’s Tag Assistant or GTM’s Preview mode to validate that consent signals are being received correctly before your tags fire.
Running the Cookie Scanner and Building Your Inventory
Knowing which cookies are actually running on your site is a legal requirement under GDPR — your privacy policy and cookie declaration must accurately describe every cookie you set. CookieRay’s built-in scanner automates this discovery process, crawling your public URLs and surfacing every cookie it finds.
How the CookieRay Cookie Scanner Works
The scanner uses WordPress’s built-in HTTP API to fetch your site’s public-facing URLs and sitemap (up to 50 pages). It does not send any data to external servers. Discovered cookies are merged into your cookie inventory and sorted by category — Necessary, Analytics, Marketing, and Functional. The scanner is admin-triggered, meaning it only runs when you manually start it or (in Pro) set a schedule.
Running Your First Cookie Scan
- Go to CookieRay → Cookie Scanner.
- Click Run Scan.
- Wait for the scanner to crawl your site (time varies with site size).
- Review the discovered cookies in the inventory panel.
- Categorize any uncategorized cookies — assign each one to Necessary, Analytics, Marketing, or Functional.
Categorizing Your Cookie Inventory
Proper categorization is essential. Necessary cookies (session tokens, CSRF tokens, the consent cookie itself) do not require opt-in consent. All other categories — analytics, marketing, functional — require explicit consent before their scripts fire. Common categorizations:
- _ga, _gid — Google Analytics (Analytics category)
- _fbp, _fbc — Meta Pixel (Marketing category)
- _hjid, _hjSessionUser — Hotjar (Analytics category)
- _gcl_au — Google Ads conversion (Marketing category)
- wordpress_logged_in, wp-settings — WordPress session (Necessary category)
Once categorized, CookieRay displays an accurate cookie declaration on your site that can be embedded on your Privacy Policy page using the plugin’s shortcode. Update the scan regularly — any time you add a new plugin or tracking tool, new cookies may appear.
Reviewing Your Compliance Score Dashboard
CookieRay’s Setup Dashboard shows a weighted compliance score from 0 to 100. This score updates as you complete each configuration step and acts as a guided checklist to ensure nothing is missed. Think of it as your compliance compass — not a statutory certification, but a practical indicator of how thoroughly you’ve set up the plugin.
What the Compliance Score Measures
- Script blocking mode is active (strict or log-only)
- Google Consent Mode v2 is enabled
- Cookies have been scanned and categorized
- A Privacy Policy link is configured in the banner
- Cookie scan has been run recently (not stale)
- Banner is active and visible on the frontend
- Consent logs are being recorded
Each factor carries a different weight. Script blocking and GCM v2 are the heaviest contributors. A score of 80+ means your core configuration is solid. 100 means all dashboard checklist items are complete.
Common Reasons for a Low Score
- Script blocking is set to ‘Log Only’ instead of ‘Strict’
- Google Consent Mode v2 is disabled
- No cookies have been scanned yet
- Privacy Policy URL is not set in banner settings
- Cookie scan data is more than 30 days old
Exporting and Managing Consent Logs
GDPR requires that you can demonstrate consent — meaning you need a record of who consented, when, to what, and using which version of your banner. CookieRay stores a full audit trail of every consent event in your WordPress database. Nothing is sent externally.
What Each Consent Log Record Contains
- Hashed visitor fingerprint (no raw IP address stored)
- Consent status — accepted, declined, or partial
- Granted consent categories — e.g., ‘analytics, necessary’
- Page URL where consent was given
- Banner version at time of consent
- Timestamp
Exporting Consent Logs
You can export your consent log as a CSV for spreadsheet analysis or as individual PDF receipts for legal audit purposes. To export:
- Go to CookieRay → Consent Logs.
- Use the search and filter tools to find specific records if needed.
- Click Export CSV or Export PDF.
- Store exported records in a secure location — your legal team may need them in case of a regulatory inquiry.
CookieRay also lets you set a retention window for consent logs. Storing consent records indefinitely is not necessary and may itself conflict with data minimization principles under GDPR. A retention period of 12–24 months is generally appropriate.
CookieRay Free vs Pro: Which Plan Do You Need?
CookieRay’s free version covers the full compliance toolkit for a single WordPress site. Most bloggers, small businesses, and developers running individual sites will find the free tier completely sufficient. The Pro plan, starting at $49/year, adds features primarily useful for agencies and multi-site operators.
CookieRay Free Plan Features
- Cookie consent banner (card and bar layouts, 9 positions)
- Strict script blocking for major tracking services
- Google Consent Mode v2
- Cookie scanner (up to 50 pages, admin-triggered)
- Consent logs with CSV export
- Setup compliance dashboard
CookieRay Pro Plan Features (from $49/year)
- Everything in Free
- Scheduled automatic cookie scans
- Geo-targeting — show or hide the banner by country
- GTM, Meta Pixel, and Adobe Analytics native integrations
- ‘Privacy Protected’ trust badge
- Premium support and priority updates
- Multi-site license (plans for 1, 5, or 25 sites)
If you’re running an agency managing 5 or more client sites, the Pro plan pays for itself in time savings from scheduled scans and priority support alone. For a single-site blogger or small business, the free version is the right starting point.
Troubleshooting Common CookieRay Issues
Banner Not Showing on the Frontend
Check that the plugin is active (Plugins → Installed Plugins), that the banner is enabled in CookieRay → Banner Settings, and that you haven’t already accepted or declined cookies in your current browser session. Always test in incognito mode. If you’re using a caching plugin, clear the cache after making banner changes.
Scripts Still Firing After Declining Cookies
This usually indicates a caching conflict. Aggressive HTML caching can serve a pre-cached version of the page where scripts are in their un-blocked state. Solution: configure your caching plugin to exclude cookies set by CookieRay from its cache keys, or disable HTML caching for the homepage. Alternatively, use Cache Exclusion rules in WP Rocket, LiteSpeed Cache, or W3 Total Cache to bypass caching for visitors without a stored consent cookie.
Google Consent Mode Signals Not Appearing in dataLayer
Ensure that CookieRay is loading before your Google Tag Manager snippet or GA4 tag. CookieRay outputs its GCM v2 defaults in the <head> with high priority, but some theme or plugin configurations may load scripts earlier. Check the page source to confirm CookieRay’s gtag consent default call appears before any Google scripts.
Cookie Scanner Returns No Results
The scanner crawls your site’s public URLs via WordPress’s HTTP API. If your site is behind a password prompt, has robots.txt restrictions that block WordPress’s user agent, or is on a localhost environment, the scanner may return empty results. For localhost testing, use a staging environment with a publicly accessible URL, or manually add cookies to your inventory.
Compliance Score Stuck Below 80
Open the Setup Dashboard and check which items show as incomplete. The most common blockers are: blocking mode not set to Strict, GCM v2 not enabled, no cookies scanned yet, and no Privacy Policy URL set. Address each flagged item in sequence and your score will climb quickly.
Frequently Asked Questions (FAQ)
Does CookieRay send any data to external servers?
No. CookieRay does not send visitor data, usage telemetry, or consent logs to any external server operated by its developers. All data — including consent logs and cookie inventories — stays in your WordPress database on your own server. The cookie scanner only fetches your own site’s public URLs using WordPress’s HTTP API.
Is CookieRay GDPR compliant?
CookieRay provides the technical infrastructure for cookie consent management — script blocking, GCM v2 signals, consent logs, and a cookie inventory. Whether your site is legally GDPR compliant depends on your overall setup: how you’ve categorized cookies, what data processors you use, what your privacy policy says, and which regions you serve. CookieRay’s Dashboard score is guidance, not a statutory compliance certification. Consult a qualified legal advisor for specific obligations.
Does CookieRay work with WooCommerce?
Yes. CookieRay works alongside WooCommerce without conflict. Be careful to categorize WooCommerce’s session cookies (woocommerce_cart_hash, woocommerce_session_*) as Necessary, as they are required for checkout functionality and should not be blocked even when a visitor declines analytics or marketing cookies.
Will CookieRay affect my Google Analytics data?
Yes — this is intentional and required by law. When a visitor declines analytics cookies, GA4 will not receive session data for that visitor. With Google Consent Mode v2 enabled, Google uses conversion modeling to estimate the behavior of users who declined, partially compensating for the data gap in your reports. The GCM v2 setup in CookieRay is designed to maximize the amount of modeled data you receive within privacy constraints.
Can I use CookieRay with Google Tag Manager?
Yes, and this is the recommended setup for most sites. Install CookieRay, enable GCM v2 in its settings, and then load GTM in your theme or via a plugin. CookieRay outputs the default consent signals before GTM loads, so all tags inside GTM will inherit the correct consent state. You do not need to add any custom consent code inside GTM itself.
How often should I run the cookie scanner?
Run the scanner every time you install a new plugin, add a new tracking tool, or make significant changes to your site’s pages or theme. For established sites, a monthly scan is a reasonable cadence. CookieRay Pro users can schedule automatic scans so this happens without manual intervention.
Is the CookieRay free version really free forever?
Yes. CookieRay is released under the GPLv2 license on WordPress.org and is permanently free. The free tier includes all core compliance features: the banner, strict script blocking, GCM v2, the cookie scanner, and consent logs with CSV export. The Pro plan adds agency and automation features but is not required for single-site compliance.
Does CookieRay work with page caching plugins?
CookieRay is designed to coexist with WP Super Cache, W3 Total Cache, WP Rocket, LiteSpeed Cache, SG Optimizer, and other popular caching plugins. The consent banner initializes from frontend scripts after page load, so it renders even on cached pages. However, aggressive HTML caching can interfere with script blocking. Test your setup in incognito mode after clearing all caches and adjust your caching plugin’s exclusion rules if scripts are loading without consent.
Conclusion
Setting up cookie consent properly in WordPress is no longer optional. GDPR, CCPA, and Google’s own advertising policies all require that you block tracking scripts before consent, pass accurate consent signals to Google’s data layer, maintain an audit trail of consent decisions, and present visitors with a clear, fair choice — not a dark pattern designed to nudge them into acceptance.
CookieRay delivers all of this in a single free WordPress plugin, without the external SaaS dependency that most competing tools require. Install it, run through the Setup Dashboard’s guided checklist, enable strict script blocking and Google Consent Mode v2, scan your cookie inventory, and review your consent logs. Done correctly, the whole setup takes under 20 minutes.
If you found this guide useful, install CookieRay free from WordPress.org today — or explore the Pro plans at wp.cookieray.com for multi-site management, scheduled scans, and geo-targeting.
