Migrate from CookieYes / Cookiebot / OneTrust

Per-vendor checklists for switching to Cookyay. Each checklist walks you through removing the old CMP, remapping categories, running the scanner, and updating your CSP — in the right order.

Check the TCF wall first. If your site serves Google personalized ads to EEA/UK visitors (AdSense, Ad Manager, AdMob), you need a Google-certified CMP — Cookyay is not one and will not become one. See compare.html — TCF wall before proceeding. If you use only Google Analytics or Google Ads conversion tracking (no ad serving), Cookyay's Consent Mode v2 support is sufficient.

Universal gotchas — read before switching any vendor

Returning visitors will be re-prompted. Your old CMP stored consent under its own cookie name (cookieyes-consent, CookieConsent, or an OneTrust GUID cookie). Cookyay stores consent in cookyay_consent. Existing visitors have no cookyay_consent cookie, so Cookyay will show them the banner again — even if they previously accepted all cookies. This is legally correct (you are changing the tool that processes their consent) but may spike your consent-rate metrics temporarily. To make the re-prompt intentional rather than accidental, bump your policyVersion when you go live.
policyVersion controls future re-prompts. Cookyay stores policyVersion in the visitor's consent record and re-shows the banner whenever the stored version differs from the one in your config. Set policyVersion to today's date (e.g. '2026-06-14') when you migrate. The next time you change your cookie policy, bump the date — all returning visitors will be re-prompted automatically.
Cookyay bootstrap must be first in <head>. The inline bootstrap snippet fires Google Consent Mode v2 defaults (all denied) and arms the script-intercept proxy before any other script runs. Any tracker placed before the bootstrap in your HTML will escape interception — the browser has already dispatched its request. If your CMS or tag manager injects scripts at the very top of <head> unconditionally, declarative blocking (rather than autoBlock) is the safer approach for those scripts.
Remove <noscript> pixel fallbacks. Many vendor-provided snippets (Meta Pixel, Google Ads) include a <noscript><img src="..."></noscript> fallback. These bypass script blocking entirely — the browser loads the pixel even with JavaScript disabled and even before consent. Remove all such tags from your HTML when you migrate.
Not legal advice. These checklists describe the technical steps for migrating your consent UX. Whether your specific deployment is compliant depends on your jurisdiction, your site's data flows, and how you configure the library. Consult qualified legal counsel.

CookieYes → Cookyay

CookieYes is the most common paid CMP among small-site developers. Its category taxonomy maps cleanly onto Cookyay's four categories.

Category mapping

CookieYes category Cookyay category Notes
Necessary necessary Always-on; no consent needed. CookieYes calls these "Strictly Necessary".
Functional functional Preferences, live chat (e.g. Intercom), embedded maps. CookieYes may also call these "Preference" cookies.
Analytics / Statistics analytics GA4 (_ga, _gid), Hotjar, Mixpanel, PostHog.
Marketing / Advertisement marketing Meta Pixel (_fbp), Google Ads (_gcl_au), LinkedIn Insight.

Migration checklist

Before you start: Export your current cookie list from the CookieYes dashboard (Settings → Cookies → Export as CSV). You will use this to populate Cookyay's services arrays. Alternatively, run the scanner against your site — it discovers cookies automatically and outputs a ready-to-use config.

  1. Remove the CookieYes script tag.

    Delete the <script src="...cookieyes.com..."> tag from every page (or from your CMS/tag manager template). Also remove any cookieyes--prefixed cookie declaration snippets or JavaScript callbacks that reference the CookieYes API (getCkyConsent, revisitCkyConsent, etc.).

  2. Remove <noscript> pixel fallbacks.

    Search your HTML templates for <noscript> tags containing <img src> pixel URLs (Meta Pixel, Google Ads conversion, etc.). Delete them — they bypass consent entirely.

  3. Declare your cookies in Cookyay config.

    Use your CookieYes CSV export to build the categories block. Map each CookieYes category to its Cookyay equivalent (see table above). For each service, list the cookies it sets under cookies. 

    Cookyay.init({
  policyVersion: '2026-06-14', // today's date — bump on future policy changes
  categories: {
    necessary: {},
    functional: {
      services: [
        { name: 'Intercom', cookies: ['intercom-id-*', 'intercom-session-*'] },
      ],
    },
    analytics: {
      services: [
        { name: 'Google Analytics 4', cookies: ['_ga', '_gid', '_ga_*'] },
        { name: 'Hotjar', cookies: ['_hjSessionUser_*', '_hjSession_*'] },
      ],
    },
    marketing: {
      services: [
        { name: 'Meta Pixel', cookies: ['_fbp', '_fbc'] },
        { name: 'Google Ads', cookies: ['_gcl_au', '_gcl_aw'] },
      ],
    },
  },
})
  4. Run the scanner to catch anything your CookieYes export missed.

    See The scanner: the one automatable step below.

  5. Place the Cookyay bootstrap first in <head>.

    Add the inline bootstrap snippet as the very first <script> in <head> — before your GTM/GA4 tags. Then add the deferred UI bundle. See the Quickstart for the copy-paste snippet. Set debug: true in your config during development — this surfaces load-order mistakes and misconfigured categories in the browser console.

  6. Update your CSP connect-src (if applicable).

    See CSP update below.

  7. Go live and verify.

    Deploy with debug: true, open the browser DevTools console, and confirm you see Cookyay's init log. Open the preferences modal, grant categories, and verify that the scripts you blocked with type="text/plain" (or via autoBlock: true) now execute. See Verifying your migration.

Consent cookie name change. CookieYes stored consent in cookieyes-consent. Cookyay uses cookyay_consent. All returning visitors will be re-prompted — this is expected and correct. Bump your policyVersion to the migration date so the re-prompt is intentional and future bumps work correctly.

Cookiebot → Cookyay

Cookiebot (by Cybot) uses a four-category model that maps directly to Cookyay's. Its cookie audit CSV export is the most structured of the three vendors covered here.

Category mapping

Cookiebot category Cookyay category Notes
Necessary necessary Session cookies, CSRF tokens. Always-on in Cookyay.
Preferences functional Language selection, UI state. Cookiebot calls these "Preferences"; Cookyay's equivalent is functional.
Statistics analytics GA4, Hotjar, Matomo, Mixpanel, Plausible (if cookie-based).
Marketing marketing Meta Pixel, Google Ads, LinkedIn Insight, Twitter Ads. Maps directly to Cookyay's marketing.

Migration checklist

Before you start: In the Cookiebot dashboard, go to Report → Download cookie report (CSV). The CSV has columns: Name, Provider, Purpose, Expiry, Type, Category. You will use the Category column to distribute cookies into Cookyay's services arrays.

  1. Remove the Cookiebot script tag and DNS prefetch.

    Delete <script id="Cookiebot" src="https://consent.cookiebot.com/uc.js"> from your <head>. Also remove any associated <link rel="dns-prefetch" href="//consent.cookiebot.com">. Remove callbacks referencing Cookiebot.consent, CookiebotCallback_* event handlers, and the CookieConsent global object.

  2. Remove <noscript> pixel fallbacks.

    Search for <noscript><img> tags from vendor snippets. Delete them.

  3. Convert your Cookiebot cookie report CSV into Cookyay config.

    Group the CSV rows by Category, then build a services array for each Cookyay category. Each service should name the provider and list the cookies it sets. The mapping is: Necessary → necessary, Preferences → functional, Statistics → analytics, Marketing → marketing.

    You can also run the scanner against your site to auto-generate the config — the scanner identifies known services (GA4, Meta Pixel, Hotjar, etc.) and emits a ready-to-use cookyay.config.json in under a minute.

  4. Handle Cookiebot's script-blocking pattern.

    Cookiebot uses a data-cookieconsent attribute on <script> tags to mark them for blocking. Cookyay uses a different pattern: set type="text/plain" and add a data-category attribute. You must convert any Cookiebot-blocked scripts to Cookyay's pattern: 

    <!-- Before (Cookiebot) -->
<script type="text/javascript" data-cookieconsent="statistics"
  src="https://example.com/analytics.js"></script>

<!-- After (Cookyay) -->
<script type="text/plain" data-category="analytics"
  data-src="https://example.com/analytics.js"></script>

    Alternatively, enable autoBlock: true in your Cookyay config to intercept known third-party scripts, iframes, fetch, sendBeacon, and XHR requests at runtime — no HTML changes needed for the services in the curated database (~60 known services including GA4, Meta Pixel, Hotjar, and more).

  5. Place the Cookyay bootstrap first in <head>.

    The inline bootstrap snippet must be first — before any analytics or GTM tags. Add the deferred UI bundle after it. See Quickstart.

  6. Update your CSP (if applicable).

    See CSP update below.

  7. Go live and verify.

    See Verifying your migration.

Consent cookie name change. Cookiebot stored consent in CookieConsent (a JSON cookie). Cookyay uses cookyay_consent. All returning visitors will be re-prompted on their first visit after the migration — expected and correct.

OneTrust → Cookyay

OneTrust is the most complex of the three vendors covered here. It uses a richer, hierarchical taxonomy with "purposes" and "stacks" on top of categories. The migration requires more manual mapping, but the end state is simpler — Cookyay's four-category model covers the essentials, and the scanner fills in the gaps.

OneTrust enterprise features have no Cookyay equivalent. If you rely on OneTrust's TCF v2.3 consent string, multi-regulation rule sets, consent analytics, A/B testing, or its hosted audit log, Cookyay cannot replace those. This migration guide is for sites that use OneTrust primarily as a cookie banner and script-blocker — not as a full TCF/IAB consent platform. See compare.html for the full list of Cookyay's honest limits.

Category mapping

OneTrust uses "purposes" and custom category groups. The mapping below covers the most common OneTrust default category names. Your OneTrust configuration may use custom names — check your OneTrust dashboard under Cookie Categories and map each to the closest Cookyay equivalent.

OneTrust category (common defaults) Cookyay category Notes
Strictly Necessary Cookies necessary Always-on. Cannot be opted out of in either tool.
Functional Cookies / Performance Cookies (some OneTrust templates) functional Language/region preferences, live chat, saved form state. "Performance" in some OneTrust configs means site-performance analytics (e.g. Core Web Vitals tooling) — those map to analytics instead.
Performance Cookies / Analytics Cookies analytics GA4, Hotjar, Heap, Amplitude, Mixpanel, Segment (analytics events). When OneTrust uses "Performance" for analytics (common on pre-GDPR configs), map it to analytics.
Targeting Cookies / Advertising Cookies / Social Media Cookies marketing Meta Pixel, Google Ads, LinkedIn Insight, Twitter/X Ads, TikTok Pixel. OneTrust often groups social sharing pixels here too.

Migration checklist

Before you start: In the OneTrust dashboard, export your cookie list (go to Cookies → Export). The export includes cookie name, domain, category, and purpose. Use this list — combined with the scanner output — to build your Cookyay categories config.

  1. Remove the OneTrust script tags and DNS prefetch entries.

    Delete the OneTrust CDN script tag (cdn.cookielaw.org/consent/<domain-id>/OtAutoBlock.js and cdn.cookielaw.org/scripttemplates/otSDKStub.js). Also remove OneTrust's auto-blocker script (OtAutoBlock.js) if present, and any OneTrustActiveGroups, OptanonWrapper, or OneTrust.OnConsentChanged callback bindings in your code.

  2. Remove OneTrust's data-category / group-ID attributes.

    OneTrust's auto-blocker marks scripts with group IDs like data-category="C0002" or wraps them in conditional blocks referencing OneTrustActiveGroups. Replace these with Cookyay's blocking pattern: 

    <!-- Before (OneTrust auto-block) -->
<script type="text/plain" class="optanon-category-C0003"
  src="https://example.com/analytics.js"></script>

<!-- After (Cookyay) -->
<script type="text/plain" data-category="analytics"
  data-src="https://example.com/analytics.js"></script>

    OneTrust group IDs map to Cookyay categories as follows: C0001 (Strictly Necessary) → omit blocking (always runs), C0002 (Performance/Analytics) → analytics, C0003 (Functional) → functional, C0004 (Targeting) → marketing, C0005 (Social Media) → marketing. Custom groups: check your OneTrust dashboard and map manually.

  3. Remove <noscript> pixel fallbacks.

    Search for and delete all <noscript><img> pixel tags.

  4. Declare your cookies in Cookyay config.

    Using your OneTrust export and the category mapping above, build the Cookyay categories block. Run the scanner to catch cookies the export might have missed (Hotjar session cookies, marketing pixels, etc.).

  5. Place the Cookyay bootstrap first in <head>.

    The bootstrap must be the very first <script> in <head>. See Quickstart.

  6. Update your CSP (if applicable).

    See CSP update below.

  7. Go live and verify.

    See Verifying your migration.

Consent cookie name change. OneTrust stores consent across several cookies — typically a GUID cookie like OptanonAlertBoxClosed and OptanonConsent. Cookyay uses cookyay_consent. All returning visitors will be re-prompted on their first visit after the migration.
No automated config importer. OneTrust's configuration export formats (hierarchical JSON tied to their proprietary category taxonomy) are undocumented, per-tier, and differ between account types. A parser would be brittle from day one. The checklist + scanner approach above is the reliable path — the scanner auto-detects what's actually on your pages, which is more accurate than any static export.

The scanner: the one automatable step

The @cookyay/scanner CLI crawls your site locally using a headless browser, detects cookies and third-party requests, classifies ~60 known services (GA4, Meta Pixel, Hotjar, Intercom, Stripe, Sentry, PostHog, and more), and emits a ready-to-use cookyay.config.json. This is the one migration step that can be automated — the config import itself is not feasible (vendor formats are undocumented and brittle), but the scanner fills in the same information from first principles.

Run the scanner against your site 
# First run downloads Chromium (~150 MB) — subsequent runs are fast
npx @cookyay/scanner scan https://yoursite.com --config-out cookyay.config.json

The scanner runs on your machine — nothing leaves your network. It can scan localhost and pages behind authentication (pass --cookies session.json with a Playwright cookie file). The emitted cookyay.config.json includes a categories block with services grouped by detected category and a suggestedBlocking array of paste-ready HTML snippets for declarative blocking.

Using the scanner output

The scanner outputs a JSON file. Copy the categories block into your Cookyay.init() config. The suggestedBlocking array gives you <script type="text/plain"> snippets to paste into your HTML for declarative blocking of detected services.

Review and adjust: the scanner classifies cookies and requests by matching against its curated database. It annotates each detection with a confidence level ("high" = two independent signals agree; "medium" = one signal). Review low-confidence entries before shipping — a session cookie from your own server may be misclassified if it shares a name pattern with a known tracker.

Scanner vs autoBlock: both approaches are valid and complementary. Declarative blocking (paste the scanner's suggested snippets into HTML) requires a one-time HTML edit per tracked service but is the most explicit approach. autoBlock: true intercepts known third-party requests at runtime without HTML changes — enable it in config and the same signature database that powers the scanner handles interception at runtime. You can use both: declarative for services outside the curated database, autoBlock: true for the rest.

CSP update

If your site uses a Content-Security-Policy header (or <meta http-equiv="Content-Security-Policy">), you need to update it after migrating.

Remove old vendor origins

Remove the old CMP's CDN domains from your CSP script-src and connect-src directives:

Add Cookyay's origins

Cookyay loads its UI bundle from the URL you choose (your own server or a CDN). If you serve from jsDelivr:

If you enable the optional consent webhook (consent.webhook: 'https://your-endpoint'):

The inline bootstrap requires 'unsafe-inline' or a hash

Cookyay's bootstrap is a synchronous inline <script> tag — it cannot be an external file (it must block rendering to fire Consent Mode defaults before GTM loads). If your CSP restricts script-src:

Verifying your migration

After deploying, run through this checklist in the browser to confirm the migration is working correctly. Use a fresh browser profile (no prior consent cookie) and one with a returning-visitor cookie from the old CMP.

DevTools checks (with debug: true in config)

  1. Bootstrap ran first: open the Console and look for a Cookyay log line confirming the bootstrap executed. If the banner never shows and there is no Cookyay log, the bootstrap or UI bundle failed to load.
  2. Consent Mode defaults fired: in the Network tab, check that your GTM or GA4 request fires after the Cookyay banner resolves (or after you click Accept), not before.
  3. Blocked scripts stayed blocked pre-consent: in the Network tab, filter for requests to known tracker domains (Meta Pixel, GA4 etc.). Before clicking Accept, those requests should not appear.
  4. Scripts fire after consent: click Accept All, then confirm the blocked services' requests appear in the Network tab.
  5. Returning visitor re-prompted (expected): with the old CMP's consent cookie present but no cookyay_consent cookie, the banner should show on first load. This is expected — the consent cookie name changed.
  6. No <noscript> pixel requests: confirm that no pixel or beacon URLs fire before the user consents (these should have been removed in step 2 of the checklist).

Optional: run the scanner post-migration

Re-run npx @cookyay/scanner scan https://yoursite.com after going live to verify the scanner sees the correct set of services and all high-confidence detections are already declared in your config.

After verification: disable debug: true

Once you are confident the migration is working, remove debug: true (or set it to false) from your production config. Debug mode emits verbose console output that is useful during development but noisy in production.