Cookie Banner Public API documentation

Updated September 11, 2024 12:33

Intro

All Public API methods are available on the CookieFirst object in the global namespace. It can also be accessed as a property of the window object. Make sure to only use the object after it's initialized. You can do that by listening to our initialization event, as shown here.

constCF = CookieFirst;
// or
constCF = window.CookieFirst;

1. Cookie Preference Center

There are 2 methods allowing developers to open and close the Cookie Preference Center programmatically:

1.1. Open the Preference Center

Opens the Cookie Preference Center if not currently open.

It accepts as a parameter a name of the tab which should be made active when the Preference Center open.

Will throw an Error in Stealth Mode.

Will throw an Error if the passed tab name is not one of active tabs for this domain

// open the Settings tab by defaultCookieFirst.openPanel();
// open the specified tab (possible values are "settings", "cookies", "policy"):CookieFirst.openPanel("cookies");

1.2. Close the Preference Center

Closes the Cookie Preference Center if it's open.

Will throw an Error in Stealth Mode.

CookieFirst.closePanel();

2. Visitor's Consent

These methods and properties allow developers to retrieve visitor's current consent for a domain and programmatically trigger various actions which modify it.

NOTE

After the initial consent, all actions which change it will trigger a page reload, unless the new consent is equal to the current one.

Only modify visitor's consent as a response to their actions (like clicking a button).

2.1. Get info about visitor's consent

You can get info about the accepted categories with CookieFirst.consent or about accepted services with CookieFirst.acceptedServices.

const acceptedCategories = CookieFirst.consent;

// if consent is available, it will be an object of this structure:
{
  necessary: true, // necessary category can't be disabled
  performance: true|false,
  functional: true|false,
  advertising: true|false,
}

// otherwise it will be empty
acceptedCategories === null; // true
const acceptedServices = CookieFirst.acceptedServices;

// if consent is available, acceptedServices will be an object of  this structure:
{
  unique_script_id: true|false,
  other_script_id: true|false,
}
// An object where keys are the unique scripts identifiers configured in Third party scripts section of our admin panel and values are true or false depending of acceptance status of each service// otherwise it will be null
acceptedServices === null; // true

2.2. `withdrawConsent()`

Consent withdraw function will clear the visitor's consent and log such change in our consent log. After this action is performed, website will reload to allow visitor's to have a fresh start on a domain. Banner will be shown again and no methods changing consent will be available until visitor consents again.

CookieFirst.withdrawConsent();

2.3. `updateConsent()`

This function allows developers to update visitor's consent and set it to a given value. It accepts a consent object as a parameter.

const newConsent = {...CookieFirst.consent};
newConsent.functional = true;
CookieFirst.updateConsent(newConsent);

2.4. `acceptCategory()`

This function allows you to perform basically the same action as above, but with one line of code.

CookieFirst.acceptCategory("functional");

2.5. `acceptAllCategories()`

This function allows you to consent to all available categories of cookies.

CookieFirst.acceptAllCategories();

2.6. `acceptPreselectedCategories()`

This function allows you to accept only the categories, which have been previously pre-selected in the domain settings screen in CookieFirst admin panel.

CookieFirst.acceptPreselectedCategories();

2.7. `declineAllCategories()`

This function allows you to accept only the necessary category and decline all other categories, with one line of code. Although it may seem similar to the withdrawConsent() function, it doesn't erase the consent completely and doesn't show the cookie banner. It updates the consent to have only the necessary cookies enabled.

CookieFirst.declineAllCategories();

2.8. `declineCategory()`

This function allows you to decline only one cookie category and preserve the rest of the consent as it was previously saved.

CookieFirst.declineCategory("functional");

2.9. `acceptService()`

This function allows you to accept specified services by their unique identifier. If consent policy option is set to "category-based" and not "service-based", the function will accept all categories of which this service is part.

CookieFirst.acceptService("service_id");// orCookieFirst.acceptService(["service_id_1","service_id_2"]);

2.10. `declineService()`

This function allows you to decline one or multiple services and preserve the rest of the consent as it was previously saved. If consent policy option is set to "category-based" and not "service-based", the function will decline all categories of which this service is part.

CookieFirst.declineService("service_id");// orCookieFirst.declineService(["service_id_1","service_id_2"]);

3. Integration settings

There are a few settings which you can use to control the banner's behaviour on your site. They are enabled using data attributes or url attributes in your banner embed code.

NOTE Those settings only apply when using banner using the banner.js embed code. When using domain-specific consent.js embed code, you can manage them in the basic settings section our admin panel.

Example using data attribute:

<scriptsrc="https://consent.cookiefirst.com/banner.js"data-cookiefirst-key="YOUR_API_KEY"data-stealth-mode="true"
></script>

Example using url attribute:

<scriptsrc="https://consent.cookiefirst.com/banner.js?stealth-mode=true"data-cookiefirst-key="YOUR_API_KEY"
></script>

In fact, the API key can also be used as url attribute, like so:

<scriptsrc="https://consent.cookiefirst.com/banner.js?cookiefirst-key=YOUR_API_KEY" 
></script>

When using multiple url attributes at once, make sure to add & character before each attribute name, for example:

src="[...]/banner.js?cookiefirst-key=YOUR_API_KEY&stealth-mode=true"

3.1. Stealth Mode

When in Stealth Mode, CookieFirst Banner doesn't render any consent-management interface. The only rendered content is the cookie declaration on a page supporting it. In Stealth Mode it's also impossible to programmatically control the cookie banner because you can't control something which doesn't exist.

Usage as data attribute: data-stealth-mode="true" or data-stealth-mode="false"

Usage as url attribute: stealth-mode=true or stealth-mode=false

3.2. Silent Mode

When in Silent Mode, CookieFirst Banner doesn't log any info to the browser console.

Usage as data attribute: data-silent-mode="true" or data-silent-mode="false"

Usage as url attribute: silent-mode=true or silent-mode=false

3.3 Language

When no language attribute is passed to our banner, it will check the user's browser to determine if their preferred language is one of the languages configured for your banner. If it's not, it will fall back to the first language on the list. However, you might want to bypass this check to for example sync the banner language with your website's language switch. To do this, you can use the language attribute.

Usage as data attribute: data-language="en" or data-language="en"

Usage as url attribute: language=en or language=en

You can also switch the banner language through API:

CookieFirst.changeLanguage('en');

Note: for languages we are using 2-letter ISO-639-1 codes. For example: en and not en-GB

4. Events

CookieFirst banner sends various events it it's lifecycle, which can be listened to on the global window object.

4.1 `cf_init`

This event is sent when our banner is fully initialized and the JS API object is available. After this event is fired, it is safe to use the window.CookieFirst object.

Example listener:

window.addEventListener("cf_init", function() {
  // use the window.CookieFirst object here
}):

4.2 `cf_consent` and `cf_services_consent`

This event is fired whenever user gives or changes their consent (including withdrawal). Use it if you want to perform some actions when consent is given. It's especially useful when listening for the first consent, because when consent is updated or withdrawn, our banner will reload the page to ensure the only the accepted third party code is executed according to user's preferences.

cf_consent will contain categories acceptance data and cf_services_consent acceptance data of individual services.

Example listener:

window.addEventListener("cf_consent", function(event) {
  var acceptedCategories = event.detail || {};
}):
window.addEventListener("cf_services_consent", function(event) {
  var acceptedServices = event.detail || {};
}):

4.3 `cf_consent_loaded` and `cf_services_consent_loaded`

This event is fired as soon as the user's previous consent becomes available as part of the banner initialization process. Use it if you want to perform actions based on user's previous consent.

Similar to previous point, cf_consent_loaded will contain categories acceptance data and cf_services_consent_loaded acceptance data of individual services.

Example listener:

window.addEventListener("cf_consent_loaded", function(event) {
  var previouslySavedConsent = event.detail;
  if(!previouslySavedConsent) {
    // consent hasn't been given yet
  } else {
    // previous consent is available
  }
}):
window.addEventListener("cf_services_consent_loaded", function(event) {
  var previouslySavedConsent = event.detail;
  if(!previouslySavedConsent) {
    // consent hasn't been given yet
  } else {
    // previous consent is available
  }
}):

4.4 `cf_layer_ready`

This event is fired as soon as any of the consent layers is fully rendered. The event contains the rendered element under event.detail

Example listener:

window.addEventListener("cf_layer_ready", function(event) {
  var element = event.detail;
  console.log(element); // will show the rendered layer element in console
}):

4.5 Events examples

Here you'll find some examples of how to use our events to achieve common scenarios:

5. `fetchLatestScan()`

The JS API allows you to get the list of cookies found on your website together with the latest scan date. To do this, use the Cookiefirst.fetchLatestScan() method. It will return a promise which resolves to the following response:

{
  updated_at: "2020-10-29T13:30:23+00:00", // latest scan date and time in ISO 8601 formatcookies: [], // an array of cookies found on your site together with any custom cookies you may have added as well as our own cookies needed for banner to work
}

6. `renderEmbeds()`

The JS API allows you to force the rendering of embedded contents (like the cookie policy or cookie table). This in integrations where the container div for the embeds is not available at the moment our banner loads. This might be the case if you dynamically add it to the DOM via single page app view navigation or just by simple JS code. After the div is added to the DOM, run Cookiefirst.renderEmbeds() to place the embedded content inside of it.

Cookie Banner Public API documentation

Intro

1. Cookie Preference Center

1.1. Open the Preference Center

1.2. Close the Preference Center

2. Visitor's Consent

2.1. Get info about visitor's consent

2.2. `withdrawConsent()`

2.3. `updateConsent()`

2.4. `acceptCategory()`

2.5. `acceptAllCategories()`

2.6. `acceptPreselectedCategories()`

2.7. `declineAllCategories()`

2.8. `declineCategory()`

2.9. `acceptService()`

2.10. `declineService()`

3. Integration settings

3.1. Stealth Mode

3.2. Silent Mode

3.3 Language

4. Events

4.1 `cf_init`

4.2 `cf_consent` and `cf_services_consent`

4.3 `cf_consent_loaded` and `cf_services_consent_loaded`

4.4 `cf_layer_ready`

4.5 Events examples

5. `fetchLatestScan()`

6. `renderEmbeds()`

Articles in this section

Sign up today and start your trial!

Intro

1. Cookie Preference Center

1.1. Open the Preference Center

1.2. Close the Preference Center

2. Visitor's Consent

2.1. Get info about visitor's consent

2.2. withdrawConsent()

2.3. updateConsent()

2.4. acceptCategory()

2.5. acceptAllCategories()

2.6. acceptPreselectedCategories()

2.7. declineAllCategories()

2.8. declineCategory()

2.9. acceptService()

2.10. declineService()

3. Integration settings

3.1. Stealth Mode

3.2. Silent Mode

3.3 Language

4. Events

4.1 cf_init

4.2 cf_consent and cf_services_consent

4.3 cf_consent_loaded and cf_services_consent_loaded

4.4 cf_layer_ready

4.5 Events examples

5. fetchLatestScan()

6. renderEmbeds()

Articles in this section

Sign up today and start your trial!

2.2. `withdrawConsent()`

2.3. `updateConsent()`

2.4. `acceptCategory()`

2.5. `acceptAllCategories()`

2.6. `acceptPreselectedCategories()`

2.7. `declineAllCategories()`

2.8. `declineCategory()`

2.9. `acceptService()`

2.10. `declineService()`

4.1 `cf_init`

4.2 `cf_consent` and `cf_services_consent`

4.3 `cf_consent_loaded` and `cf_services_consent_loaded`

4.4 `cf_layer_ready`

5. `fetchLatestScan()`

6. `renderEmbeds()`