Skip to content

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.

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

    The full page

  2. 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_countdown

    Do

    acme_countdown_42
    Real 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.

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

    The full page

    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.

    The full page

  4. 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 only
    Real 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.

    The full page

  5. 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_SECONDS

    Do

    'expires' => time() + DAY_IN_SECONDS
    Real 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.

    The full page

  6. No consent cookies from PHP

    A cookie that your PHP sends with the page is set before any banner can act, and a page cache may send it to every visitor. Keep PHP cookies for what the site cannot work without, such as the cart.

    Avoid

    // PHP, sent with every page
    setcookie( 'acme_ref', $ref );

    Do

    // JavaScript, after consent
    if ( wp_has_consent( 'marketing' ) ) {
      document.cookie = 'acme_ref=' + ref + '; path=/';
    }
    Real cases from our tests
    What goes wrong Seen in our tests · Mailchimp for WooCommerce 6.3 · 16 October 2026

    Mailchimp for WooCommerce sets its cookies from PHP for 28 days (2 419 200 s, Secure, SameSite=Strict): mailchimp_campaign_id and mailchimp_email_id when a visitor arrives with ?mc_cid= or ?mc_eid=, mailchimp_user_email, mailchimp_user_previous_email and mailchimp_cart_token (HttpOnly) for cart recovery, and mailchimp_landing_site on the first page only if landing page tracking is on (off by default). A consent plugin cannot hold them; all go through the mailchimp_allowed_to_use_cookie filter.

    The full page

    What goes wrong Seen in our tests · W3 Total Cache 2.11.0 · 13 November 2026

    With Page Cache, W3 Total Cache answers cached pages from advanced-cache.php before WordPress plugins load (Disk: Basic), or straight from the web server (Disk: Enhanced). No consent plugin can change the headers of those responses: with a Referrer Group on, w3tc_referrer can be set before a choice and a refused cookie is not expired until an uncached page.

    The full page

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

    The full page

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.

  1. 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 ) );
  2. 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>
  3. 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(); }
    } );
  4. 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/plain alone, 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
    }
  5. 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_update

    Do

    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

What goes wrong Seen in our tests · Kadence theme 1.5.2, Kadence Blocks 3.8.0 · 16 October 2026

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.

The full page

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.