Programming Cookiebot Consent Management Platform (CMP)

Below is advanced technical information, mainly for developers. If you are looking for our default implementation guide on how to get started with Cookiebot CMP, it can be found here.

On this page you will find our SDK documentation to build custom implementations of banner and cookie controls. As well as the options for manual overrides of the automated mechanisms of our cookie consent banner.

For the below SDK to function, the Cookiebot CMP script needs to be implemented on your website.

Load the cookie consent script through:

https://consent.cookiebot.com/uc.js?cbid=00000000-0000-0000-0000-00000000000

Or as:

https://consent.cookiebot.com/uc.js

(with the attribute data-cbid=’00000000-0000-0000-0000-000000000000′)

Remember to replace 00000000-0000-0000-0000-000000000000 with your own domain group ID found under “Your scripts” on your Cookiebot CMP account.

The Cookiebot CMP script loads and constructs a client-side JavaScript object named ‘Cookiebot’ which exposes the following public properties, methods, events and callback functions.

Properties

NameTypeDefaultDescription
consent.necessarybooltrueTrue if current user has accepted necessary cookies. The property is read only.
consent.preferencesboolfalseTrue if current user has accepted preference cookies. The property is read only.
consent.statisticsboolfalseTrue if current user has accepted statistics cookies. The property is read only.
consent.marketingboolfalseTrue if current user has accepted marketing cookies. The property is read only.
consent.methodstringnullThe way the consent was given. Either ‘implied’ when a consent is given automatically or ‘explicit’ when given by the user. If there is no consent the value is null. If the consent method is unknown (old consents) it is considered ‘implied’. The property is read only.
consentedboolfalseTrue if the user has accepted cookies. The property is read only.
declinedboolfalseTrue if the user has declined the use of cookies. The property is read only.
hasResponseboolfalseTrue if the user has responded to the dialog with either ‘accept’ or ‘decline’. The property is read only.
doNotTrackboolfalseTrue if the user has enabled the web browser’s ‘Do not track’ (DNT) setting. If DNT is enabled Cookiebot will not set the third party cookie CookieConsentBulkTicket used for bulk consent. The property is read only.
regulations.gdprAppliesboolfalseAllows you to determine if GDPR applies based on the user’s geo-location. The property is read only.
regulations.ccpaAppliesboolfalseAllows you to determine if CCPA applies based on the user’s geo-location. The property is read only.
regulations.lgpdAppliesboolfalseAllows you to determine if LGPD applies based on the user’s geo-location. The property is read only.

Methods

NameParametersDescription
showNoneForces the cookie consent dialog to show.
hideNoneForces the cookie consent dialog to hide.
renewNoneShows the cookie consent dialog to the website user to renew or change the user’s consent state.
getScriptstring URL,
bool async,
func callback
Loads a JavaScript-file. URL: Absolute path to the JavaScript-file.
async (Optional): Determines if the script should load asynchronously.
callback (Optional): JavaScript function to execute when the script has finished loading.
runScriptsNoneEvaluates all loaded script tags of type “text/plain” with the attribute “data-cookieconsent” and executes the scripts in accordance with the user’s consent state. For use by websites that load content dynamically, e.g. in single page applications. Scripts are only executed once, so this function is safe to call several times, e.g. every time new content is loaded.
withdrawNoneWithdraw my consent for this website.
submitCustomConsentbool optinPreferences,
bool optinStatistics,
bool optinMarketing
Use this outside the context of the cookie banner, such as a button in your site’s header/footer to opt in or out – Or to add a button to your banner that enables partial consent, to for instance “Accept Preferences & Statistics”.
<a href="javascript: Cookiebot.renew()">Renew or change your cookie consent</a>

Event handling

NameDescription
CookiebotOnConsentReadyThe event is triggered when the user’s consent state is ready, either from being submitted or loaded from an existing cookie. Listen for this event if you need to retreive the user’s consent and run additional scripts as soon as possible based on consent values.
CookiebotOnLoadThe event is triggered at the same time as the window.onload event when the user’s consent has been loaded – either when the user submits consent or when the user navigates to a page where consent has already been submitted.
CookiebotOnAcceptThe event is triggered if the user accepts the use of cookies. The event is also triggered if the user has consented at an earlier visit to the website.
CookiebotOnDeclineThe event is triggered if the user declines the use of cookies by clicking the decline-button in the cookie consent dialog. The event is also triggered if the user already has declined at an earlier visit to the website.
CookiebotOnDialogInitFires when the cookie consent banner is initialized, before compiling the content of the banner.
CookiebotOnDialogDisplayFires when the cookie consent banner is displayed to the end user.
CookiebotOnTagsExecutedFires when tags marked up for prior consent (e.g. the attribute “data-cookieconsent”) have been triggered.

Example: Load marketing cookies if the user has accepted

<script type="text/javascript">

      window.addEventListener('CookiebotOnAccept', function (e) {
      if (Cookiebot.consent.marketing) 
          {
          //Execute code that sets marketing cookies
          } 
      }, false);

 </script>

Callbacks

NameDescription
CookiebotCallback_OnLoadThe asynchronous callback is triggered when the cookie banner has loaded to get the user’s consent.
CookiebotCallback_OnAcceptThe asynchronous callback is triggered when the user clicks the accept-button of the cookie consent dialog and whenever a consented user loads a page.
CookiebotCallback_OnDeclineThe asynchronous callback is triggered when the user declines the use of cookies by clicking the decline-button in the cookie consent dialog. The callback is also triggered whenever a user that has declined the use of cookies loads a page.
CookiebotCallback_OnDialogInitFires when the cookie consent banner is initialized, before compiling the content of the banner.
CookiebotCallback_OnDialogDisplayFires when the cookie consent banner is displayed to the end user.
CookiebotCallback_OnTagsExecutedFires when tags marked up for prior consent (e.g. the attribute “data-cookieconsent”) have been triggered.

Example: Load statistics cookies if the user has opted in to statistics cookies

Please note that this example is relevant only if you have not set data-blockingmode to “auto” and if you have not marked your script for control with data-cookieconsent.

<script type="text/javascript">
     function CookiebotCallback_OnAccept() {
           if (Cookiebot.consent.statistics)            
{      
enableStatisticsCookies();              
}
}
function enableStatisticsCookies() {  
          //Execute code that sets statistics cookies
        }  
</script>

Script tag data attributes

NameTypeMandatoryDescription
data-cbidstringyesThe unique ID for your Cookiebot domain group.
data-typestringnoOverrides the default dialog type with one of the following values:
“optin”, “optout”, “optinout”, “leveloptin”, “inlineoptin”, “optionaloptin”
data-levelstringnoOverrides the default consent method with one of the following values: “implied”, “strict”
data-culturestringnoTo force a specific language variant of the consent dialog, set the value of this attribute to a culture neutral ISO 639-1 language code, e.g. “EN” for English. Setting this attribute with a valid language overrides the “Auto-detect user language” setting in the Cookiebot manager.
data-frameworkstringnoEnables Cookiebot to signal consent to other consent frameworks implemented on a website in addition to the default consent framework in Cookiebot. The value of the attribute must match the shortcode of the external framework. Currently supported third party consent frameworks: Shortcode “IAB”: IAB Europe Transparency & Consent Framework.
data-blockingmodestringnoDefines if Cookiebot should automatically block all cookies until a user has consented, value: “auto”. If not, (value: “none”) cookie-setting scripts should manually be marked up as described in our manual implementation guide. If you omit this attribute, behavior will equal value: “none”.
data-consentmodestringnoAllows you to disable Google Consent Mode by passing a value of “disabled”.
<script id="Cookiebot" data-culture="EN" src="https://consent.cookiebot.com/uc.js" data-cbid="00000000-0000-0000-0000-000000000000" type="text/javascript"></script>

Server side usage

If your website is setting cookies server side, you can determine what type of cookies you are allowed to set by checking the users current consent state through standard cookie handling.

  • C#
  • PHP
  • VB
using System.Web.Script.Serialization;
 ...

HttpCookie CurrentUserConsent = Request.Cookies["CookieConsent"];

 if (CurrentUserConsent != null) 
{
       switch (CurrentUserConsent.Value) 
       {
              case "-1":
                    //The user is not within a region that requires consent - all cookies are accepted 
                    break; 

              default: //The user has given their consent

                     //Read current user consent in encoded JavaScript format 
                     JavaScriptSerializer CookieConsentSerializer = new JavaScriptSerializer();
                     dynamic CookieConsent = CookieConsentSerializer.Deserialize<object>(HttpUtility.UrlDecode(CurrentUserConsent.Value));


if (!CookieConsent["preferences"] && !CookieConsent["statistics"] && !CookieConsent["marketing"])
                     {
                         //The user has opted out of cookies, set strictly necessary cookies only
                     }
                     else
                     {

                     if (CookieConsent["preferences"]) 
                     {
                            //Current user accepts preference cookies
                     }
                     else 
                     {
                           //Current user does NOT accept preference cookies
                     }

                     if (CookieConsent["statistics"]) 
                     {
                           //Current user accepts statistics cookies
                     }
                     else
                     { 
                          //Current user does NOT accept statistics cookies
                     } 

                     if (CookieConsent["marketing"])
                     { 
                          //Current user accepts marketing cookies 
                     } 
                     else
                     { 
                          //Current user does NOT accept marketing cookies
                     } 
              }
       } 
}
 else 
{ 
      //The user has not accepted cookies - set strictly necessary cookies only 
}
if (isset($_COOKIE["CookieConsent"])) 
{ 
      switch ($_COOKIE["CookieConsent"])
      {
            case "-1":
                  //The user is not within a region that requires consent - all cookies are accepted
                  break; 

            default: //The user has given their consent 

                  //Read current user consent in encoded JavaScript format 
                  $valid_php_json = preg_replace('/\s*:\s*([a-zA-Z0-9_]+?)([}\[,])/', ':"$1"$2', preg_replace('/([{\[,])\s*([a-zA-Z0-9_]+?):/', '$1"$2":', str_replace("'", '"',stripslashes($_COOKIE["CookieConsent"])))); 
                  $CookieConsent = json_decode($valid_php_json); 



if (!filter_var($CookieConsent->preferences, FILTER_VALIDATE_BOOLEAN) 
&& !filter_var($CookieConsent->statistics, FILTER_VALIDATE_BOOLEAN) && !
filter_var($CookieConsent->marketing, FILTER_VALIDATE_BOOLEAN))
                  {
                         //The user has opted out of cookies, set strictly necessary cookies only
                  }
                  else
                  {

                  if (filter_var($CookieConsent->preferences, FILTER_VALIDATE_BOOLEAN)) 
                  { 
                        //Current user accepts preference cookies 
                  } 
                  else 
                  { 
                        //Current user does NOT accept preference cookies
                  } 

                  if (filter_var($CookieConsent->statistics, FILTER_VALIDATE_BOOLEAN))
                  { 
                        //Current user accepts statistics cookies 
                  } 
                  else 
                  { 
                        //Current user does NOT accept statistics cookies
                  }

                  if (filter_var($CookieConsent->marketing, FILTER_VALIDATE_BOOLEAN))
                  { 
                        //Current user accepts marketing cookies
                  }
                  else 
                  { 
                        //Current user does NOT accept marketing cookies
                  }
             }
       }
 } 
else 
{
      //The user has not accepted cookies - set strictly necessary cookies only 
}
Imports System.Web.Script.Serialization
 ... 

Dim CurrentUserConsent As HttpCookie = Request.Cookies("CookieConsent")

 If CurrentUserConsent IsNot Nothing Then 
      Select Case CurrentUserConsent.Value 
            
            Case "-1" 
                  REM The user is not within a region that requires consent - all cookies are accepted 
                  Exit Select 

            Case Else REM The user has given their consent 

                  REM Read current user consent in encoded JavaScript format 
                  Dim CookieConsentSerializer As New JavaScriptSerializer() 
                  Dim CookieConsent As dynamic = CookieConsentSerializer.Deserialize(Of Object)(HttpUtility.UrlDecode(CurrentUserConsent.Value)) 

                  If Not CookieConsent("preferences") And Not 
CookieConsent("statistics") And Not CookieConsent("marketing") Then
                  REM The user has opted out of cookies, set strictly necessary cookies only
                  Else

                  If CookieConsent("preferences") Then 
                       REM Current user accepts preference cookies 
                  Else 
                       REM Current user does NOT accept preference cookies 
                  End If 

                  If CookieConsent("statistics") Then 
                       REM Current user accepts statistics cookies 
                  Else 
                       REM Current user does NOT accept statistics cookies
                  End If

                  If CookieConsent("marketing") Then
                       REM Current user accepts marketing cookies 
                  Else 
                       REM Current user does NOT accept marketing cookies
                  End If 
            End If
      End Select 
Else 
      REM The user has not accepted cookies - set strictly necessary cookies only 
End If

    Stay informed

    Join our growing community of data privacy enthusiasts now. Subscribe to the Cookiebot™ newsletter and get all the latest updates right in your inbox.

    By clicking on “Subscribe” I confirm that I want to subscribe to the Cookiebot™ newsletter. I can easily cancel my Cookiebot™ newsletter subscription and revoke consent to use my data by clicking the unsubscribe link or I can write to [email protected] to make the request. Privacy policy.