Method 1 — Upload via WordPress Admin

Upgrading from any older version

Method 2 — FTP / Manual

Step 1 — Set your banner text

Go to CookiEzu → Settings → Content tab. Update the Banner Title and Banner Message to reflect your site's brand and what you actually do with cookies.

Step 2 — Add your Privacy Policy link

Still on the Content tab, paste your Privacy Policy page URL into the Privacy Policy URL field. This is required under GDPR — visitors must be able to read your full policy from the banner.

Step 3 — Choose your layout with live preview

Go to the Design tab. On the right side of the screen you'll see a sticky Live Preview panel — a scaled browser mockup that updates in real time as you change any setting. Pick your Layout (Bar, Box, or Modal), Position, and Theme. The preview reflects your changes instantly without saving.

Step 4 — Enable the categories you use

Go to the Categories tab. Only enable the categories that match cookies your site actually loads. If you don't use Facebook Pixel, don't show a Marketing toggle.

Step 5 — Enable consent recording

Go to the Advanced tab and tick Record Consent. This builds your GDPR audit trail in CookiEzu → Consent Log — and now automatically captures visitor country (2-letter code only) for the analytics dashboard.

Step 6 — Save and test

Click Save Settings. Then open your website in a private/incognito window to see the banner as a first-time visitor would. Try accepting all, then clearing the cookiezu_consent cookie and trying the Customize flow too.

Changes in v1.3.0

Changes in v1.2.1 — Metrics & UX Polish

Changes in v1.2.0 — Polish & Accessibility

Previous Releases

Layouts

Positions

Re-open Button

After consent is given, a small 🍪 floating button appears so visitors can update preferences at any time — a GDPR requirement. Its position (bottom-left or bottom-right) is configurable in Advanced → Re-open Button Position (new in v1.2.0).

Cookie Details Table

Enable Show Cookie Table in Categories settings to display the specific cookies, their provider, and expiry inside each category. This provides the detailed disclosure required by stricter GDPR interpretations.

Custom Colour Settings

When you select the Custom theme, three colour pickers appear:

Border Radius

The Border Radius setting (0–50px) applies to buttons and the Box/Modal layout container. Set to 0 for sharp corners, or 50 for fully rounded pill-shaped buttons. The Live Preview updates this in real time.

How It Works

The Design tab is now a two-column layout. On the left: your settings (Layout, Position, Theme, colours, border radius). On the right: a sticky preview panel showing a scaled browser window mockup containing a fake page and your live banner. No page reload, no saving — every change is reflected immediately.

What the Preview Shows

Responsive Behaviour

On screens narrower than 1100px, the two-column design collapses to a single column with the settings on top and the preview below. The preview panel is still sticky on wider viewports to keep it visible as you scroll through the settings.

When Record Consent is enabled in Advanced settings, CookiEzu logs every consent event to wp_cookiezu_consent_log.

What Gets Recorded

Consent Expiry

The Consent Expiry setting (Advanced tab) controls how long the visitor's browser cookie lasts. Default is 365 days. After expiry the banner re-appears and a new record is created. GDPR recommends re-obtaining consent at least annually.

What's in the Dashboard

Country Detection

Country codes are resolved at the time consent is saved using a three-tier detection chain:

Configuring Accessibility Features

All accessibility features are on by default. Some can be toggled in CookiEzu → Settings → Advanced → Keyboard Settings:

What It Does

When Test Mode is enabled in Advanced settings, the banner always shows for logged-in WordPress administrators — even if they already have a valid consent cookie. This lets you preview design changes, test category toggles, and verify the Customize flow without clearing browser cookies each time.

Important Notes

How to Set the Banner Language

Go to CookiEzu → Settings → Content → Language & Localisation. Select from the dropdown:

Arabic RTL — What Happens Automatically

When Arabic is selected, a cookiezu-rtl class and dir="rtl" attribute are added to the banner root element by PHP — before the browser renders it. The following are applied by CSS with no JavaScript logic required:

Language Files

Translations live in the languages/ folder as simple PHP arrays:

Missing keys fall back to English automatically. To contribute a new language, copy en.php, translate the values, and submit a pull request on GitHub.

How It Works

The Policy Version field (in Advanced settings, default: 1) is stored in each visitor's consent cookie as policyVersion and recorded in the consent log. On every page load, CookiEzu compares the cookie's stored version with the current setting. If they don't match, the old cookie is cleared and the banner is shown again.

When to Bump the Version

Consent Log

Each consent record stores the policy_version value at the time of consent. This gives you a full audit trail — you can see exactly which version of the policy each visitor consented to. The column was added in v1.3.0 via automatic DB migration; records from before the upgrade default to 1.

Applicable Laws

What CookiEzu Handles vs. What It Cannot

Smart Admin Compliance Notices

CookiEzu checks your consent log for BN and GCC country codes. If visitors from those regions are detected and the Data Processing Location field is empty, yellow admin notices appear automatically on CookiEzu pages in the WordPress admin — linking directly to the settings tab that needs attention.

How It Works

When you enter a GA4 Measurement ID, CookiEzu injects the gtag.js script and sets up Consent Mode v2. By default all consent signals are denied. When a visitor accepts analytics cookies, CookiEzu updates the signals to granted and GA4 begins full tracking.

Setup

Setup

dataLayer Event Structure

JavaScript
{
  event: "cookiezu_consent_updated",
  cookiezu: {
    necessary:  true,
    analytics:  true,   // or false
    marketing:  false,
    functional: true,
    version:    "1.2.1",
    date:       "2026-02-28T10:22:00.000Z"
  }
}

Access these in GTM as {{dlv - cookiezu.analytics}} etc. to conditionally fire tags.

The Consent Event

Every time a visitor saves their preferences, CookiEzu fires a custom DOM event called cookiezuConsentUpdated.

JavaScript
document.addEventListener('cookiezuConsentUpdated', function(e) {
  const consent = e.detail;

  // consent.necessary  → always true
  // consent.analytics  → true or false
  // consent.marketing  → true or false
  // consent.functional → true or false

  if (consent.analytics) {
    loadHotjar(); // load any analytics tool
  }
  if (consent.marketing) {
    loadFBPixel(); // load Facebook Pixel
  }
  if (consent.functional) {
    loadIntercom(); // load chat widget
  }
});

Reading Consent Without the Event

JavaScript
function getCookieZuConsent() {
  const match = document.cookie.match(/cookiezu_consent=([^;]*)/);
  if (!match) return null;
  try { return JSON.parse(decodeURIComponent(match[1])); }
  catch(e) { return null; }
}

const consent = getCookieZuConsent();
if (consent?.analytics) {
  // already consented — load scripts immediately
}

GDPR Checklist

Southeast Asian PDPA laws share the same core principle as GDPR — you must obtain informed consent before collecting and processing personal data, including via cookies and tracking scripts.

Country Coverage

Paste your CSS into CookiEzu → Settings → Advanced → Custom CSS. It is output in a <style> tag in your page footer, after the plugin's main stylesheet, so it takes full precedence.

CSS Variables Reference

CSS Variables
:root {
  /* Colours (all overrideable) */
  --cz-cookie:         #C17B2F;   /* buttons, toggles, links */
  --cz-cookie-pale:    #FDF3E3;   /* light checked bg — auto-overridden in dark mode */
  --cz-text:           #1A1208;   /* all text */
  --cz-text-muted:     rgba(26,18,8,0.55);
  --cz-bg:             #FEFCF8;   /* banner background */
  --cz-surface:        #FBF7F0;   /* unchecked category card */
  --cz-border:         rgba(26,18,8,0.10);

  /* Shape */
  --cz-radius:         10px;
  --cz-radius-lg:      16px;
}

Example — Dark Mode Override

CSS
/* Deepen the dark background further */
.cookiezu-theme-dark {
  --cz-bg:      #0D0904;
  --cz-surface: #150F08;
}

Example — Custom Font

CSS
.cookiezu-banner {
  font-family: 'Georgia', serif;
}

Example — Override layout per page

PHP
add_filter( 'cookiezu_options', function( $options ) {
  // Use modal on checkout, bar everywhere else
  if ( is_checkout() ) {
    $options['layout']   = 'modal';
    $options['position'] = 'bottom';
  }
  return $options;
} );

Dark mode text unreadable on category cards

Banner doesn't appear at all

Most common cause: you already have a consent cookie. Open DevTools → Application → Cookies, find cookiezu_consent, delete it, and refresh. Always test in an incognito window. Alternatively, turn on Test Mode in Advanced to force the banner to show for admins without clearing cookies.

Country shows "—" in the log

The country_code column was added in v1.3.0. If records show "—" for country, these were created before the upgrade. All new consents after upgrading will have the country code populated. You can also check if your server is behind Cloudflare (fastest method) or confirm that outbound HTTP requests to geoplugin.net are not blocked by your firewall.

Live preview doesn't update

The live preview relies on jQuery being loaded on the admin page (it always is in WordPress admin). If the preview doesn't update, open DevTools Console and look for JavaScript errors. A common cause is a third-party admin plugin that breaks the global jQuery object. Try disabling other plugins temporarily.

After upgrading, old behaviour persists

A caching plugin is serving the old JS/CSS. Clear WP Super Cache, W3 Total Cache, LiteSpeed Cache, Cloudflare cache, and any server-level cache your host provides (Kinsta, WP Engine, Flywheel all have these). Then hard-refresh with Ctrl+Shift+R.

Consent log is empty

Make sure Record Consent is enabled in Advanced. Also run console.log(cookiezuSettings.ajaxUrl) in the browser console to verify the AJAX URL is correct.

Will CookiEzu slow my site down?

No. The front-end JavaScript is under 4KB with zero dependencies. The CSS is ~6KB. Both load in the footer and have no impact on Core Web Vitals or page speed.

Does country tracking slow consent recording?

For Cloudflare users: no — the country comes from a header with zero latency. For everyone else, the geoplugin.net lookup has a 3-second timeout and results are cached per IP for 24 hours (WordPress transients), so repeat visitors from the same IP have instant resolution. If the lookup fails or times out, an empty string is stored gracefully — consent recording never fails because of country detection.

Is the live preview exactly what visitors see?

The preview is a proportional approximation. Layout, theme, colours, and shapes are accurate. Exact pixel-level spacing and font rendering will differ slightly because the preview is scaled down inside an admin panel. Always verify in incognito on your real site before going live.

Can I use CookiEzu with WooCommerce?

Yes. WooCommerce's session and cart cookies are Necessary and don't require consent. Show Marketing only if you run WooCommerce Ads or remarketing. The plugin is fully compatible with WooCommerce.

Is this plugin free forever?

Yes. CookiEzu is GPL v2 licensed. Use it on unlimited sites, modify it, redistribute it. No paid tiers, no usage limits, no subscriptions.

Does CookiEzu block scripts automatically?

Not yet. v1.3.0 fires the cookiezuConsentUpdated JS event which you use to load scripts conditionally. Automatic script blocking (rewriting type="text/javascript" → type="text/plain") is planned for v2.

How do I report a bug?

Open an issue at github.com/flyzal/CookiEzu/issues. Include your WP version, PHP version, active theme, layout, and exact reproduction steps.

✅ Completed — v1.0 through v1.3.0

Version 2.0 — Smarter Consent

Version 3.0 — Power Features

Current v1.3.0 Integrations

1. Not Legal Advice

Nothing in this documentation, on the CookiEzu website, or within the plugin's code constitutes legal advice, legal opinion, or a legal recommendation. The information provided is for general technical guidance only. For advice specific to your business, jurisdiction, and data practices, consult a qualified legal professional or a certified Data Protection Officer (DPO).

2. Software Provided "As Is" — GPL v2 Warranty Disclaimer

CookiEzu is distributed under the GNU General Public License v2 (GPL v2). As stated in Sections 11 and 12 of that license:

GPL v2 — Sections 11 & 12
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED
BY APPLICABLE LAW. THE PROGRAM IS PROVIDED "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL ANY
COPYRIGHT HOLDER BE LIABLE FOR DAMAGES, INCLUDING ANY GENERAL,
SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THE PROGRAM.

3. No Liability for Fines or Legal Actions

The author of CookiEzu shall not be held liable for any fines, penalties, legal proceedings, regulatory enforcement actions, or damages of any kind — including but not limited to GDPR fines (up to €20M or 4% of global turnover), CCPA penalties, PDPA enforcement, or civil claims — arising from the use or misconfiguration of this plugin.

4. Compliance Is Your Responsibility

How Contributions Work

CookiEzu uses the standard open source fork-and-pull model. Anyone can fork, improve, and submit a pull request — no invitation needed.

The Fork-and-Pull Workflow

What We Welcome

Support the Project