Consent Studio API for JavaScript

With the Consent Studio JavaScript API, you can leverage our consent banner logic for your own applications.

Getting Started

The Consent Studio consent banner instance is stored in window.consentStudio (or: consentStudio).

The API for JS can be accessed through window.consentStudio.api.

Our API is categorized as follows:

• The consent banner (consentBanner)

• The consent state (consentState)

The consent banner

Show the consent banner

/** Show the Consent Studio consent banner */
window.consentStudio.api.consentBanner.show();

Hide the consent banner

/** Hide the Consent Studio consent banner */
window.consentStudio.api.consentBanner.hide();

The consent state

The consent state represents the user’s preferences regarding the use of cookies and other data processing. You can use the following methods to interact with the consent state.

Reading the consent state

Check if consent has been recorded

Returns true if the visitor has already made a consent choice (so the consent cookie exists), and false if they haven't seen or interacted with the banner yet. Useful for deciding whether to show your own secondary prompt, trigger the banner, or wait.

/**
 * @returns {bool}
 */
window.consentStudio.api.consentState.isSet();

List all the consented categories

Retrieves all the categories the visitor has granted consent for. Returns null when no consent cookie is set yet (use isSet() to distinguish "no consent yet" from "explicit reject all").

/**
 * @returns {array<string>|null}
 */
window.consentStudio.api.consentState.get();

Check if the user has given functional consent

This method checks whether the visitor has consented to functional data processing.

/**
 * @returns {bool}
 */
window.consentStudio.api.consentState.hasFunctional();

Check if the user has given analytics consent

This method checks whether the user has consented to analytics data processing.

/** 
 * @returns {bool}
 */
window.consentStudio.api.consentState.hasAnalytics();

Check if the user has given marketing consent

This method checks whether the user has consented to marketing data processing.

/**
 * @returns {bool}
 */
window.consentStudio.api.consentState.hasMarketing();

Writing the consent state

Options

Every write method accepts an optional options object:

// Default — hides the banner after the update:
{ hideBanner: true }

// Keep the banner visible (e.g. inside a custom preferences UI):
{ hideBanner: false }

Set the full consent state

Overwrites the consent state with exactly the object passed in. Any category you omit defaults to false (denied), so this method is ideal when you want to set the complete state in a single call (for example, from a custom consent UI where the user toggles each category).

/**
 * @param {{functional?: bool, analytics?: bool, marketing?: bool}} state
 * @param {{hideBanner?: bool}} [options]
 */
window.consentStudio.api.consentState.set(
    { functional: true, analytics: true, marketing: false },
    { hideBanner: true }
);

Accept all categories

Grants consent for every category (functional, analytics, and marketing). Equivalent to the visitor clicking "Accept all" in the banner.

/**
 * @param {{hideBanner?: bool}} [options]
 */
window.consentStudio.api.consentState.acceptAll();

Deny all non-essential categories

Denies analytics and marketing, keeping only functional (which is strictly-necessary and always required). Equivalent to the visitor clicking "Reject all" in the default supplied consent banner.

/**
 * @param {{hideBanner?: bool}} [options]
 */
window.consentStudio.api.consentState.denyAll();

Grant consent for a single category

Grants consent for one category without touching the other categories. Useful when a specific integration (e.g. a video player) asks the visitor for consent inline and you only want to update that one category.

/**
 * @param {{hideBanner?: bool}} [options]
 */
window.consentStudio.api.consentState.grantFunctional();
window.consentStudio.api.consentState.grantAnalytics();
window.consentStudio.api.consentState.grantMarketing();

Deny consent for a single category

Revokes consent for one category without touching the other categories. Useful for "opt out of analytics" links or similar granular controls.

/** * @param {{hideBanner?: bool}} [options] */ window.consentStudio.api.consentState.denyFunctional(); window.consentStudio.api.consentState.denyAnalytics(); window.consentStudio.api.consentState.denyMarketing();

Localisation

Getting the visitor’s country code

Returns the visitor's country code as determined server-side by GeoIP. The CMP configuration is served per-country (for geotargeting), and the resolved country is exposed here so your scripts and integrations can branch on it.

Return values:

• A lowercase ISO 3166-1 alpha-2 code (e.g. "nl", "us") when the country is known

• "_default" when the site does not use geotargeting

• "unknown" when GeoIP could not resolve the visitor's IP

• null when the configuration has not yet loaded

/** * @returns {string|null} */ window.consentStudio.getCountry();