Cookie Banner Public API documentation

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.

javascript
const CF = CookieFirst;
// or
const CF = window.CookieFirst;

1. Cookie panel

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

1.1 Open the panel. 

Opens the Cookie Panel if not currently 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 default
CookieFirst.openPanel();
// open the specified tab (possible values are "settings", "cookies", "policy"):
CookieFirst.openPanel("cookies");

1.2. Close the panel. 

Closes the Cookie Panel if it's open. Will throw an Error in Stealth Mode.

javascript
CookieFirst.closePanel();

2. Visitors consent

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

Listen to events

const callbackFn = (event) => {
  var consent = event.detail || CookieFirst.consent;
};
// listen for Cookie First initialization event
window.addEventListener("cf_consent", callbackFn);

2.1 Get info about visitor's consent

javascript
const consent = 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
consent === 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.

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

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

javascript
CookieFirst.acceptCategory("functional");

2.5 acceptAllCategories()

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

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

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

javascript
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. (functional, advertising, performance)

javascript
CookieFirst.declineCategory("functional");

3. Integration settings

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

Example using data attribute:

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

Example using url attribute:

<script 
src="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:

<script 
src="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

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

Example listener:

window.addEventListener("cf_consent", function(event) {
var newlyGivenConsent = event.detail;
}):

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

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
  }
}):

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
}):

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 format
cookies: [], // 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()