For plugin and theme developers
Name your cookies and storage keys right, from day one
Consent tools sort every cookie and storage key by its name. A name that is too generic, or already used by another tool, ends up in the wrong category, or blocked with something else. Check yours here before you ship it.
Try:
- 3,643 names known from 867 tools, plugins and themes
- Free, no sign-up
- Updated with every Cookie Rocks release
Example popup_closed
Too generic
Nothing in it says it is yours. A consent tool cannot recognise it, and another plugin may use the same name.
Better: my_plugin_popup_closed
Eight best practices
Each one takes a minute when you write the code. Each one saves the people who install your plugin an afternoon of work, and a consent banner that gets it wrong.
Give every name a prefix of your own
Start every cookie and storage key with your slug. A consent tool can then hold all your names with one pattern,
acme_*, including the ones you add next year.Avoid
setcookie( 'popup_closed', '1' ); localStorage.setItem( 'recent', ids );Do
setcookie( 'acme_popup_closed', '1' ); localStorage.setItem( 'acme_recent', ids );Real cases from our tests
What goes wrong Seen in our tests · Kadence theme 1.5.2, Kadence Blocks 3.8.0 · 16 October 2026 Kadence Blocks' evergreen countdown sets a first-party cookie named <site name slug>-<campaign id> for 30 days on the first page to keep each visitor's deadline. The theme's grid or list toggle sets <site name slug>-shopLayout for 30 days only after a click. Neither the theme nor Kadence Blocks has WP Consent API or gtag('consent') code. Form captchas (reCAPTCHA, Turnstile, hCaptcha) are required to submit.
Put the changing part last
When a name needs an ID, a widget or a campaign, add it at the end. A name that starts with a number or the site’s name cannot be matched from one site to the next.
Avoid
my-shop-42 42_countdownDo
acme_countdown_42Real cases from our tests
What goes wrong Seen in our tests · JetElements 2.7.12.1 · 17 November 2026 A Countdown Timer set to Evergreen keeps its own deadline for each visitor in local storage (jet_evergreen_countdown_due_date_<widget> and _interval_<widget>) from the first page that shows it, with no expiry.
Write nothing before it is needed
Set a cookie when the visitor does what it remembers. A cookie written after a click is easy to explain. One written on every first visit has to wait for consent, unless the site cannot work without it.
Avoid
// on every page, just in case setcookie( 'acme_visited', '1' );Do
// when the visitor closes the pop-up close.addEventListener( 'click', () => { document.cookie = 'acme_popup_closed=1; max-age=86400; path=/'; } );Real cases from our tests
What goes wrong Seen in our tests · Premium Addons for Elementor 4.11.119 · 13 November 2026 When a page has an element with the Return Visitor display condition, Premium Addons sets PaVisitorData (1 year) and PaNewVisitor (1 day) on the first page for every visitor, to show different content to people who come back. Our legal watch classes this tracking as marketing: consent first.
Some get it right, some do not Seen in our tests · WoodMart, Soledad, XStore 8.5.7.1, 8.5.4, 9.6.2 · 12 November 2026 The age-check pop-ups remember the visitor's answer in a cookie: woodmart_age_verify for 30 days (WoodMart), penci_age_verify for 30 days (Soledad), age_verify_popup_shows for 1 day (XStore). WoodMart sets its cookie only after a click on “I am 18 or Older”; after “I am Under 18” nothing is set and the pop-up comes back on the next page (XTemos, 13/11/2026). Our legal watch classes them as necessary, but advises keeping the answer for the visit at most: a longer life should be avoided.
Often, store nothing at all
Browser storage counts like a cookie under the ePrivacy rule: moving a value there changes nothing for consent. State that only matters on the current page can live in a variable.
Avoid
localStorage.setItem( 'acme_tab', 'reviews' );Do
let acmeTab = 'reviews'; // for this page onlyReal cases from our tests
Done right Seen in our tests · W3 Total Cache 2.10.7 · 16 October 2026 W3 Total Cache sets no cookie for ordinary anonymous visitors by default. Its cookies are w3tc_logged_out (session, at logout), w3tc_logged_<role hash> (logged-in users of an excluded role), w3tc_preview (admin preview) and, only when a referrer group is enabled, w3tc_referrer (session, set on the first page from another site). It adds no third-party host to visitor pages by default; its Google Analytics usage tracking runs in the admin only and is off unless the administrator agrees. It does not use WP Consent API and sets no Consent Mode default.
Ask before you track: WP Consent API
Do not guess whether the visitor agreed. WP Consent API gives every consent plugin the same answer to read, in PHP and in JavaScript, and tells you when it changes.
Avoid
acmeLoadPixel(); // and hope a banner blocks itDo
function acmeStart() { if ( typeof wp_has_consent === 'function' && ! wp_has_consent( 'marketing' ) ) { return; } acmeLoadPixel(); } acmeStart(); document.addEventListener( 'wp_listen_for_consent_change', acmeStart );Real cases from our tests
Being fixed Seen in our tests · Premium Addons for Elementor · 15 November 2026 The Premium Addons developer says that the Returning Visitor display condition, which sets the PaVisitorData cookie for a year from the first page, will follow WP Consent API in the next version of the plugin. Not released yet: we will test it when that version is out.
Keep it short, and say how long
Choose the shortest life that does the job, and write it in your documentation. A value in local storage has no expiry: it stays for years.
The visitor’s yes may end first, and browsers cut long dates anyway: How long cookies last, and for the code, Cookie lifetimes: good practice.
Avoid
'expires' => time() + 10 * YEAR_IN_SECONDSDo
'expires' => time() + DAY_IN_SECONDSReal cases from our tests
Some get it right, some do not Seen in our tests · WoodMart, Soledad, XStore 8.5.7.1, 8.5.4, 9.6.2 · 12 November 2026 The age-check pop-ups remember the visitor's answer in a cookie: woodmart_age_verify for 30 days (WoodMart), penci_age_verify for 30 days (Soledad), age_verify_popup_shows for 1 day (XStore). WoodMart sets its cookie only after a click on “I am 18 or Older”; after “I am Under 18” nothing is set and the pop-up comes back on the next page (XTemos, 13/11/2026). Our legal watch classes them as necessary, but advises keeping the answer for the visit at most: a longer life should be avoided.
Never bring a deleted identifier back
When the visitor refuses or deletes their cookies, the identifier is gone. Restoring it from a copy goes against that choice, and consent tools treat it as tracking.
Avoid
if ( ! getCookie( 'acme_uid' ) ) { setCookie( 'acme_uid', localStorage.getItem( 'acme_uid_copy' ) ); }Do
if ( ! getCookie( 'acme_uid' ) && wp_has_consent( 'statistics' ) ) { setCookie( 'acme_uid', crypto.randomUUID() ); // a new one }Real cases from our tests
What goes wrong Seen in our tests · 14 October 2026 Criteo keeps its ad identifier cto_bundle in localStorage as well as in a cookie. After the cookie is deleted, the old identifier is sent again to Criteo (and, on one site, to about fifteen ad bidders), then the cookie comes back with a new value. Deleting only cookies does not stop the visitor from being recognised.
When your code runs: not too early, not too late, not from PHP
A consent tool can only hold what it sees, when it sees it. Too early, your code runs before the visitor is asked. Too late, or loaded by another script, it slips past. From PHP, it reaches the visitor before any banner, and a cached page sends it to everyone. What Cookie Rocks does with your scripts.
Be in the page, where a consent tool can see you
Consent tools hold the scripts they recognise in the HTML of the page, before it reaches the browser. A script added later by another script is only held if the script that adds it is held too.
Avoid
// an inline loader nobody recognises const s = document.createElement( 'script' ); s.src = 'https://cdn.acme.example/track.js'; document.head.append( s );Do
wp_enqueue_script( 'acme-tracker', plugins_url( 'js/acme-tracker.js', __FILE__ ), array(), '1.4', array( 'strategy' => 'defer', 'in_footer' => true ) );Not too early: nothing that writes while the page loads
Inline code that writes a cookie or a storage key while the page is read runs before the visitor is asked. If it must stay inline, mark it with its category: consent tools that read this syntax release it after the yes.
Avoid
<script> document.cookie = 'acme_seen=1; path=/'; </script>Do
<script type="text/plain" data-category="statistics"> document.cookie = 'acme_seen=1; max-age=86400; path=/'; </script>Decide in the browser, not in PHP
Pages are cached: the same HTML goes to every visitor, and PHP does not run again. A choice read in PHP follows the first visitor, not the next one. Read it in JavaScript, and listen for changes.
Avoid
// PHP: the cached page keeps this answer if ( wp_has_consent( 'statistics' ) ) { wp_enqueue_script( 'acme-stats' ); }Do
// JavaScript, with WP Consent API if ( wp_has_consent( 'statistics' ) ) { acmeStart(); } document.addEventListener( 'wp_listen_for_consent_change', ( e ) => { if ( e.detail.statistics === 'allow' ) { acmeStart(); } } );Optimisers: keep held scripts held
Plugins that combine or delay JavaScript can turn a held script back into a live one, or merge it into a file that always runs. Leave scripts of type
text/plainalone, and keep consent scripts out of combining and delaying.Avoid
// every script, held or not $tag = str_replace( 'text/plain', 'text/javascript', $tag );Do
if ( str_contains( $tag, 'type="text/plain"' ) ) { return $tag; // held by a consent tool: leave it }Tag managers: check the consent, not only the event
A consent event also fires after a refusal. A tag that fires on the event alone runs whatever the answer. Use the built-in consent checks, or add a condition on the value.
Avoid
Trigger: Custom Event cr_consent_updateDo
Consent check: ad_storage or Trigger: cr_consent_update where cr_consent.marketing equals true
Choices to make on day one
Cheap to get right at the start. Expensive to change once thousands of sites depend on your defaults.
Fonts
Instead of: Google Fonts loaded from Google’s servers
Do: Ship the font files, or make “load fonts locally” the default. Each request to another server sends the visitor’s IP address. Web fonts and the law
Videos and maps
Instead of: An iframe in the page
Do: A placeholder with a play or view button, and the iframe only after the click
Libraries
Instead of: A script from a public CDN
Do: The file in your plugin, or the copy WordPress already ships, such as jQuery
Captchas
Instead of: The captcha script on every page
Do: The script on the form only, loaded when the visitor starts to fill it in
Statistics
Instead of: A tracker that starts on page load
Do: Start it only with consent, read through WP Consent API
Remembered settings
Instead of: A cookie for every option
Do: The server, a CSS media query such as
prefers-color-scheme, or memory for the current page
The Kadence theme loads fonts.googleapis.com (with a preconnect to fonts.gstatic.com) as soon as a Google font is chosen; Load Google Fonts Locally (Customizer > General > Performance) is off by default. Kadence Blocks prints its Google Fonts as direct link tags in wp_head (priority 85) and wp_footer without a style handle, follows the theme's setting, and without the theme has its own local setting, also off by default.
Test against the next Cookie Rocks
Your users will update. Check your plugin or theme against the next version before it ships: on a test site, add one line to wp-config.php, and WordPress offers the beta versions of Cookie Rocks Pro, and of the Audit installed from cookierocks.com.
define( 'COOKIE_ROCKS_CHANNEL', 'beta' );
Test sites only: a beta can still change before the stable version. Remove the line to go back to stable versions, and tell our support about anything that breaks. Details: the beta channel.
Write your readme section in a minute
List every name, its kind, how long it lasts and what it is for. Consent tools, site owners and their lawyers all read this section. Fill in the rows, then copy the result into your readme.
Then tell us. Cookie Rocks files each new name with its category in the next version, so it is held correctly on every site that uses your plugin: send us your names. To work with Cookie Rocks directly, see the PHP filters and JavaScript events.
WordPress has its own privacy tools for plugins: suggest text for the site’s privacy policy with wp_add_privacy_policy_content(), and add the data your plugin keeps to the personal data export and erasure tools. See Privacy in the Plugin Handbook.
