Help Guides > Features Documentation > Events > CookieYes Events on Cookie Banner Load

CookieYes Events on Cookie Banner Load

Last updated on June 2, 2025

On this page

Overview

The CookieYes banner load event allows users to execute custom actions when the consent banner is loaded on a webpage. This document outlines how to use the cookieyes_banner_load event and the data it provides.

Note:

Incompatible for CookieYes WordPress plugin without Web App Connection.

The event listeners mentioned in this documentation are incompatible with the CookieYes WordPress plugin when not connected to the web app. However, they seamlessly function with both the web app and the WordPress plugin when it is connected to the web app.

Event Listener

To utilize the CookieYes banner load event, add an event listener to the document object for the cookieyes_banner_load event. When the event is fired, the event listener triggers a callback function, providing the event data as an argument.

Basic Usage

To implement the event listener into your website, add the following code snippet to your webpage. Check the JSON value in eventData and customize the code to execute the specific action you want.

document.addEventListener("cookieyes_banner_load", function (eventData) {
    //  Check the value in the JSON eventData and perform the desired action.
})

Event Data Structure

The JSON object eventData includes the user's consent choices for different cookie categories, consent ID, the active consent law, the language code of the displayed banner, and whether the user has interacted with the cookie consent banner in the below format.

detail: {
    "activeLaw": "String",           // e.g., "gdpr", "ccpa", etc.
    "categories": {
        "necessary": "Boolean",
        "functional": "Boolean",
        "analytics": "Boolean",
        "performance": "Boolean",
        "advertisement": "Boolean"
    },
    "isUserActionCompleted": "Boolean", // true or false
    "consentID": "String",           // Unique identifier for the consent
    "languageCode": "en"             // e.g., "en" for English
}

The key properties are:

PropertyTypeDescription
activeLawstringThe legal framework under which the consent is active.
categoriesobjectUser consent status for different categories.
isUserActionCompletedbooleanIndicates whether the user interacted with the banner.
consentIDstringUnique identifier for the user's consent.
languageCodestringISO-639-1 code of the displayed banner language.

Example Usage

Here's an example of how to use the event listener to perform a specific action when the active law is "gdpr":

<script>
 document.addEventListener("cookieyes_banner_load", function (eventData) {
    const data = eventData.detail;
   if (data.activeLaw === "gdpr") {
     // perform the desired action.
   }
  });
</script>

The JSON object eventData contains the following information:

detail: {
  "activeLaw": "gdpr",
  "categories": {
    "necessary": true,
    "functional": false,
    "analytics": false,
    "performance": false,
    "advertisement": false
  },
  "isUserActionCompleted": true,
  "consentID": "bFl2eFJBN05VS21WNWk5enpRNTNEZ3hxR0dDc3VmcFM",
  "languageCode": "en"
}

Best Practices

  • Handle potential errors: When working with event data, it's crucial to anticipate and manage scenarios where errors might occur due to unexpected data formats or processing issues. Your code should be prepared to handle these scenarios without crashing or behaving unpredictably.
  • Respect User Consent: Consider the user's consent status when performing actions based on this event.  Before initializing any scripts, loading content or performing actions that might involve user data, you should check the relevant consent status.
  • Add the handler early in the page: To ensure your handler is in place in time to catch the event, place the event listener for cookieyes_banner_load as early as possible in your page's loading sequence. This guarantees the handler is ready when the event fires, which often occurs very early in the page load process. 
  • Use a combination of banner load and interaction events: Implement cookieyes_consent_update listener within the handler of cookieyes_banner_load to cover all scenarios. This approach ensures you capture both the initial consent state and any subsequent user interactions with the banner, providing a comprehensive consent management strategy.

Was this article helpful?

Have more questions?

Reach out to us and we'll answer them.

Contact us