JavaScript SDK - CookieChimp Docs

When the CookieChimp script loads, it exposes a global CookieChimp object (also available as window.CookieChimp). Everything on this page is read from — or called on — that object. Use it to:

Read data — what the visitor consented to, which banner was served to them (country, region, consent mode), and the Cloudflare known-bot signal from script delivery.
Listen for events — react the moment consent is given, changed, or the modal is shown or hidden.
Control the banner — show, hide, accept, reject, or reset consent programmatically.

The CookieChimp object and its properties are populated once the script has initialised. If you read them too early — for example, at the very top of the page — they may be undefined. Read them inside an event handler such as CookieChimpReady or cc:onConsented, or after a check for window.CookieChimp.

CookieChimp exposes properties on the CookieChimp object that tell you about the visitor’s location and the banner that was served to them. They’re useful when you want to customise behaviour or tags based on country, region, or consent mode — without duplicating banners.

`CookieChimp.visitorCountry`

The ISO 3166-1 alpha-2 country code of the visitor (e.g. "US", "GB", "CN", "DE").

CookieChimp.visitorCountry; // 'US'

`CookieChimp.visitorRegion`

The region/subdivision code of the visitor (e.g. "NY" for New York, "CA" for California). Useful when compliance rules differ by region within a country — for example, US state privacy laws.

CookieChimp.visitorRegion; // 'NY'

`CookieChimp.visitorNeedsConsent`

true if a consent banner was shown to the visitor (either an opt-in or opt-out banner), false if the visitor's location does not require one.

CookieChimp.visitorNeedsConsent; // true

`CookieChimp.isBotVisitor`

true if CookieChimp identifies the visitor as a bot: a verified bot reported by Cloudflare, a known crawler user agent, or an automated browser. false otherwise.

CookieChimp.isBotVisitor; // false

`CookieChimp.getConfig()['mode']`

Returns the consent mode that was applied to the visitor based on your geolocation rules:

"opt-in" — the visitor was shown an opt-in banner (e.g. EU/EEA visitors under GDPR).
"opt-out" — the visitor was shown an opt-out banner (e.g. US visitors under CCPA-style regulations).

CookieChimp.getConfig().mode; // 'opt-in'

These properties are populated once the CookieChimp script has initialised. If you read them before initialisation — for example, at the very top of the page — they may be undefined. Read them inside a callback or event handler such as CookieChimpReady, cc:onModalReady, or cc:onConsented, or after a check for window.CookieChimp.

`CookieChimp.cloudflareKnownBot`

The Cloudflare known-bot signal for the widget script request. Its value is the string "true" for a known crawler or "false" otherwise. Compare it explicitly with "true": both strings are truthy in JavaScript. A "false" value does not confirm that the visitor is human. This signal describes script delivery and may be cached by the browser. It is not a live classification for every page view or consent request, and it does not indicate the visitor’s consent status. Use getUserPreferences to read consent choices. CookieChimp billing counts all users, including bots. This signal and any bot filtering in analytics do not exclude users from billable usage. See the billing FAQ.

`getConfig()`

Returns the resolved configuration for the banner that was served to the current visitor. The most commonly read field is mode:

CookieChimp.getConfig(); // { mode: 'opt-in', ... }

// the consent mode applied to this visitor
CookieChimp.getConfig().mode; // 'opt-in' or 'opt-out'

Field	Type	Description
`mode`	`string`	The consent mode applied to the visitor based on your geolocation rules — `'opt-in'` (e.g. GDPR) or `'opt-out'` (e.g. CCPA-style).

For end-to-end recipes that use these properties — hiding a button for visitors from one country, firing analytics tags by consent mode, or per-domain branding — see Advanced Banner Overrides.

`getUserPreferences`

Returns the visitor’s accepted/rejected categories and services. This is the primary way to read what the user consented to. Type: function(): object

function(): {
    acceptType: string,
    acceptedCategories: string[],
    rejectedCategories: string[],
    acceptedServices: { [category: string]: string[] },
    rejectedServices: { [category: string]: string[] }
}

Field	Type	Description
`acceptType`	`string`	The type of consent given — `'all'`, `'custom'`, `'necessary'`, or `''` if none yet.
`acceptedCategories`	`string[]`	Names of the categories the visitor accepted.
`rejectedCategories`	`string[]`	Names of the categories the visitor rejected.
`acceptedServices`	`{ [category]: string[] }`	Accepted services, keyed by the category they belong to.
`rejectedServices`	`{ [category]: string[] }`	Rejected services, keyed by the category they belong to.

// the full preferences object
CookieChimp.getUserPreferences();

// type of consent given ('', 'all', 'necessary' or 'custom')
CookieChimp.getUserPreferences().acceptType;

// accepted categories (array of accepted category names)
CookieChimp.getUserPreferences().acceptedCategories;

// rejected categories (array of rejected category names)
CookieChimp.getUserPreferences().rejectedCategories;

// accepted services (object of accepted services, keyed by category)
CookieChimp.getUserPreferences().acceptedServices;

// rejected services (object of rejected services, keyed by category)
CookieChimp.getUserPreferences().rejectedServices;

var preferences = CookieChimp.getUserPreferences();

if (preferences.acceptType === "all") {
  console.log("Everything has been accepted!");
}

if (preferences.acceptedCategories.includes("analytics")) {
  console.log("The analytics category was accepted!");
}

`acceptedCategory`

Returns true if the specified category was accepted by the user, otherwise false.

if (CookieChimp.acceptedCategory("analytics")) {
  // "analytics" category was accepted
} else {
  // not accepted
}

`acceptedService`

Returns true if the specified service was accepted by the user, otherwise false.

if (CookieChimp.acceptedService("Google Analytics", "analytics")) {
  // "Google Analytics" service was accepted
} else {
  // not accepted
}

`validConsent`

Returns true if consent is valid. Consent is NOT valid when at least one of following situations occurs:

consent is missing (e.g. user has not yet made a choice)
CookieChimp’s cookie does not exist/has expired
CookieChimp’s cookie is structurally not valid (e.g. empty)

if (CookieChimp.validConsent()) {
  // consent is valid
} else {
  // consent is not valid
}

`getCookie`

Returns the raw consent object stored in CookieChimp’s cookie — the same object passed as event.detail.cookie in the consent events. Pass a field name to read a single field. For checking what the visitor accepted, prefer getUserPreferences, acceptedCategory, and acceptedService. getCookie is useful when you need consent metadata, such as the consent ID or timestamps.

// the full consent object
CookieChimp.getCookie();

// a single field
CookieChimp.getCookie("consentId"); // unique ID of this visitor's consent
CookieChimp.getCookie("consentTimestamp"); // when consent was first given (ISO 8601)
CookieChimp.getCookie("lastConsentTimestamp"); // when consent was last updated (ISO 8601)
CookieChimp.getCookie("categories"); // accepted category names
CookieChimp.getCookie("services"); // accepted services, keyed by category

`validCookie`

Returns true if a cookie with the given name exists on the page and has a non-empty value. It’s handy for checking whether a third-party cookie has already been set.

if (CookieChimp.validCookie("_ga")) {
  // the Google Analytics cookie exists
}

Listening for events

Every event is a standard DOM event dispatched on window. Subscribe with window.addEventListener and read the data from event.detail. CookieChimp dispatches four families of events:

Category	Events	When they fire
Lifecycle events	`CookieChimpReady`	When CookieChimp has finished initialising on the page.
Consent events	`cc:onFirstConsent`, `cc:onConsented`, `cc:onUpdate`	When the visitor accepts, rejects, or changes preferences.
Modal events	`cc:beforeModalShow`, `cc:onModalShow`, `cc:onModalHide`, `cc:onModalReady`	At each stage of the banner / preferences modal lifecycle.
Consent string events	`cc:consentStringUpdated`	When `window.cookieChimpConsentString` is (re)built — used by the Adobe Launch integration.

Lifecycle events

`CookieChimpReady`

Dispatched on window once CookieChimp has finished initialising on the page: the visitor’s stored consent has been loaded, the banner has been set up (and will open if the visitor still needs to make a choice), and every method on this page is available on the CookieChimp object. It fires on every page load for every visitor — including visitors in a location where no banner is shown, and visitors whose Global Privacy Control signal is honoured. Use it for code that needs the SDK but doesn’t depend on a consent change — for example reading the visitor’s preferences on every page load, or wiring your own UI to CookieChimp.showPreferences().

window.addEventListener("CookieChimpReady", function () {
  var preferences = CookieChimp.getUserPreferences();

  if (preferences.acceptedCategories.includes("analytics")) {
    // analytics was accepted on this or a previous visit
  }
});

CookieChimpReady is a plain Event, so it carries no event.detail — read whatever you need from the CookieChimp object inside the listener.

Register the listener before the CookieChimp script tag, or in a script that loads before it, so you can’t miss the event. In single-page apps it fires again each time CookieChimp re-runs after a client-side navigation (see pageview), so make sure your handler is safe to run more than once.

If the code that needs CookieChimp may run after the event has already fired — for example, an app bundle that loads after the CookieChimp script — check whether the SDK methods are there before waiting for it. They’re only attached once initialisation has finished, so their presence means you can call them straight away:

function onCookieChimpReady(callback) {
  if (window.CookieChimp && typeof window.CookieChimp.getUserPreferences === "function") {
    callback();
  } else {
    window.addEventListener("CookieChimpReady", callback, { once: true });
  }
}

onCookieChimpReady(function () {
  // CookieChimp is ready
});

These fire whenever the visitor’s consent state changes. For example, when the visitor gives consent for the first time, reloads a page on which consent is already stored, or changes their preferences from the privacy trigger.

`cc:onFirstConsent`

Triggered the first time the user expresses their choice of consent (accept/reject).

window.addEventListener("cc:onFirstConsent", function (event) {
  var detail = event.detail;
  // detail.cookie — the saved consent object (see getUserPreferences for parsed preferences)

  // do something
});

`cc:onConsented`

Triggered the very first time the user expresses their choice of consent — just like onFirstConsent — but also on every subsequent page load.

window.addEventListener("cc:onConsented", function (event) {
  var detail = event.detail;
  // detail.cookie — the saved consent object

  // do something
});

`cc:onUpdate`

Triggered when the user modifies their preferences, and only if consent has already been provided.

window.addEventListener("cc:onUpdate", function (event) {
  var detail = event.detail;
  /**
   * detail.cookie             — the saved consent object
   * detail.changedCategories  — array of category names that changed
   * detail.changedServices    — object of services that changed, keyed by category
   */

  // do something
});

The data carried by each consent event:

Property	Available on	Description
`detail.cookie`	all consent events	The saved consent object. Use `getUserPreferences()` for parsed preferences.
`detail.changedCategories`	`cc:onUpdate`	Array of category names whose acceptance changed.
`detail.changedServices`	`cc:onUpdate`	Object of services whose acceptance changed, keyed by category.

These cover the lifecycle of the consent banner and preferences modal — from being attached to the DOM to being shown and hidden.

`cc:beforeModalShow`

Dispatched right before the consent modal is shown. This event is cancelable — call event.preventDefault() to prevent the banner from appearing. You can then show it later programmatically via CookieChimp.show(true).

window.addEventListener("cc:beforeModalShow", function (event) {
  var detail = event.detail;
  // detail.modalName

  // Example: prevent the banner from showing automatically
  event.preventDefault();

  // ... and show it later when you're ready
  // CookieChimp.show(true);
});

This is useful when you want to delay the consent banner — for example, to wait until a user has completed onboarding, or to show it only after a certain interaction.

`cc:onModalShow`

The consent modal is visible.

window.addEventListener("cc:onModalShow", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});

`cc:onModalHide`

The consent modal is hidden.

window.addEventListener("cc:onModalHide", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});

`cc:onModalReady`

The consent modal is created and appended to the DOM. This is the safest place to read visitor & banner data, because those properties are guaranteed to be populated by the time it fires.

window.addEventListener("cc:onModalReady", function (event) {
  var detail = event.detail;
  // detail.modalName

  // do something
});

The data carried by each modal event:

Property	Description
`detail.modalName`	The name of the modal that triggered the event (e.g. the consent or preferences modal).

CookieChimp also publishes the visitor’s choices as a flat, comma-separated string on window.cookieChimpConsentString. The Adobe Launch integration is built on this property and the matching event below — it pairs well with any setup that prefers a single value over the structured getUserPreferences() object.

Google Tag Manager uses its own consent signal — a cookiechimp_consent_update push on dataLayer, not this DOM event. See the Google Tag Manager guide for the GTM-specific setup.

`window.cookieChimpConsentString`

A comma-separated list of every category and service the visitor has accepted, for example:

window.cookieChimpConsentString;
// => 'essential,analytics,marketing,Google Analytics,Hotjar,Facebook Pixel'

The string is rebuilt every time the visitor’s consent changes, so reading it inside a cc:consentStringUpdated listener (below) always reflects the latest state.

`cc:consentStringUpdated`

Triggered once consent has been granted and again every time the visitor changes their preferences, after window.cookieChimpConsentString has been rebuilt. The new string is also available as event.detail.consentString. The event is dispatched on document and bubbles up to window, so a listener on either receives it.

window.addEventListener("cc:consentStringUpdated", function () {
  // window.cookieChimpConsentString is up to date here
  var consent = window.cookieChimpConsentString || "";

  if (consent.split(",").indexOf("Google Analytics") !== -1) {
    // "Google Analytics" was accepted — fire the tag
  }
});

Tag managers usually need both pieces — read window.cookieChimpConsentString on page load to handle visitors who already consented on a previous visit, and listen for cc:consentStringUpdated to handle real-time changes. See the Adobe Launch guide for a complete recipe.

`show`

Shows the consent banner. If consent was previously expressed, the consent modal will not be generated; you’ll have to pass the argument true to generate it on the fly.

CookieChimp.show();

// show modal (if it doesn't exist, create it)
CookieChimp.show(true);

`hide`

Hides the consent banner.

CookieChimp.hide();

`showPreferences`

Shows the preferences modal.

CookieChimp.showPreferences();

`hidePreferences`

Hides the preferences modal.

CookieChimp.hidePreferences();

`acceptCategory`

Programmatically accept or reject a cookie category.

// accept all categories
CookieChimp.acceptCategory("all");

// reject all (accept only categories marked as readOnly/necessary)
CookieChimp.acceptCategory([]);

// accept currently selected categories inside the preferences modal
CookieChimp.acceptCategory();

// accept only the "analytics" category
CookieChimp.acceptCategory("analytics");

// accept only these 2 categories
CookieChimp.acceptCategory(["analytics", "marketing"]);

// accept all categories except the "analytics" category
CookieChimp.acceptCategory("all", ["analytics"]);

// accept all categories except these 2
CookieChimp.acceptCategory("all", ["analytics", "marketing"]);

`acceptService`

Accepts or rejects services.

// accept all services in the 'analytics' category
CookieChimp.acceptService("all", "analytics");

// reject all services
CookieChimp.acceptService([], "analytics");

// accept only specified service and reject all the others
CookieChimp.acceptService("Google Analytics", "analytics");

// accept only these 2 services and reject all the others
CookieChimp.acceptService(["service1", "service2"], "analytics");

`reset`

Resets CookieConsent by dropping all internal pointers and config. You can pass the argument true to delete CookieChimp’s cookie which holds the user’s consent & preferences. The user will be prompted again to express their consent.

Once this method is called, CookieChimp won’t be functional on the page. The webpage needs to be fully reloaded to re-initialise CookieChimp.

CookieChimp.reset(true);

// Reload the page
window.location.reload();

Single-page apps

`pageview`

Re-runs CookieChimp for the current page: the banner and privacy trigger are rendered again if needed, and CookieChimpReady is dispatched again when it’s done.

CookieChimp.pageview();

By default, CookieChimp watches for URL changes and calls this for you on every client-side navigation, so most single-page apps never need it. Call it yourself when your app replaces the page content without changing the URL. See the Single Page Apps guide for framework-specific setup.

Helpers

`loadScript`

Loads a script by adding a <script> tag to <head>, unless a script with the same src is already on the page. Pass an optional object as the second argument to set attributes on the tag. Returns a Promise that resolves to true once the script has loaded (or if it was already on the page), or false if it failed to load. Combine it with the consent checks above to load a third-party script only after the visitor accepts it:

function loadExampleWidgetIfAccepted() {
  if (CookieChimp.acceptedService("Example Widget", "analytics")) {
    CookieChimp.loadScript("https://cdn.example.com/widget.js", {
      "data-site-id": "12345",
    }).then(function (loaded) {
      if (!loaded) console.warn("Example Widget failed to load");
    });
  }
}

// consent already stored, even if this code runs after CookieChimp has loaded
onCookieChimpReady(loadExampleWidgetIfAccepted);
// the visitor's first choice
window.addEventListener("cc:onConsented", loadExampleWidgetIfAccepted);
// the visitor enables it later from the preferences modal
window.addEventListener("cc:onUpdate", loadExampleWidgetIfAccepted);

This uses the onCookieChimpReady helper from above. Calling loadExampleWidgetIfAccepted more than once is safe: loadScript skips a src that’s already on the page.

For most scripts you don’t need any JavaScript — add the script attributes to the tag and CookieChimp runs it once the matching category or service is accepted.

Next steps

Advanced Banner Overrides — full end-to-end recipes built on the properties and events above.
Custom Update Consent Button — wire showPreferences to your own button.
Custom CSS — the full list of CSS variables you can override.

​Reading visitor and banner data

​CookieChimp.visitorCountry

​CookieChimp.visitorRegion

​CookieChimp.visitorNeedsConsent

​CookieChimp.isBotVisitor

​CookieChimp.getConfig()['mode']

​CookieChimp.cloudflareKnownBot

​getConfig()

​Reading the visitor’s consent

​getUserPreferences

​acceptedCategory

​acceptedService

​validConsent

​getCookie

​validCookie

​Listening for events

​Lifecycle events

​CookieChimpReady

​Consent events

​cc:onFirstConsent

​cc:onConsented

​cc:onUpdate

​Modal events

​cc:beforeModalShow

​cc:onModalShow

​cc:onModalHide

​cc:onModalReady

​Consent string events

​window.cookieChimpConsentString

​cc:consentStringUpdated

​Controlling the banner

​show

​hide

​showPreferences

​hidePreferences

​acceptCategory

​acceptService

​reset

​Single-page apps

​pageview

​Helpers

​loadScript

​Next steps

Reading visitor and banner data

`CookieChimp.visitorCountry`

`CookieChimp.visitorRegion`

`CookieChimp.visitorNeedsConsent`

`CookieChimp.isBotVisitor`

`CookieChimp.getConfig()['mode']`

`CookieChimp.cloudflareKnownBot`

`getConfig()`

Reading the visitor’s consent

`getUserPreferences`

`acceptedCategory`

`acceptedService`

`validConsent`

`getCookie`

`validCookie`

Listening for events

Lifecycle events

`CookieChimpReady`

Consent events

`cc:onFirstConsent`

`cc:onConsented`

`cc:onUpdate`

Modal events

`cc:beforeModalShow`

`cc:onModalShow`

`cc:onModalHide`

`cc:onModalReady`

Consent string events

`window.cookieChimpConsentString`

`cc:consentStringUpdated`

Controlling the banner

`show`

`hide`

`showPreferences`

`hidePreferences`

`acceptCategory`

`acceptService`

`reset`

Single-page apps

`pageview`

Helpers

`loadScript`

Next steps