Web CMP v2 Events¶

The Browser UI provides different events that inform about consent changes or app initialization. These events can be used for Tag Manager and custom implementations.

Consent Events¶

Usercentrics provides Data Layer and Window events that specifically target consent changes.

consent_status¶

consent_status is defined in the following way:

{
    "action": "onInitialPageLoad",
    "event": "consent_status",
    "type": "explicit",
    "Service One": true,
    "Usercentrics Consent Management Platform": true,
    "Service Two": false,
    "ucCategory": {
      "essential": true,
      "functional": false,
      "marketing": null,
    },
    (...)
}

• action is the parameter that will tell you where the consent_status event was triggered. These are the current possible values for the parameter action:
  • onInitialPageLoad
    • This event gets triggered on page load
  • onAcceptAllServices
    • This event gets triggered once you click “Accept All”
  • onDenyAllServices
    • This event gets triggered once you click “Deny All”
  • onUpdateServices
    • This event gets triggered once you edit a specific set of services or a single service and hit “Save Services”.
  • onSessionRestored
    • This event may trigger in one of these three situations:
      • When you replace current consents by using a given controllerID,
      • When you use Cross Domain Consent Sharing, and
      • Via WebView User Session Continuity
• event contains the name of the event
• type contains the type of the event, which could be:
  • implicit → When the user didn't interact with the banner, and
  • explicit → When the user has given any type of consent
• Consent status: the event also shows all the current services and categories that are available in your settingsID and a current consent status:
  • Services: there is a service: consent_state pair for each service, e.g. Usercentrics Consent Management Platform: true
  • Categories (BETA): ucCategory is another property in the array which contains identifier of all categories from your settingsID and their consent status. A category has the consent state:
    • true if all services belonging to this category have the state true
    • false if all services belonging to this category have the state false
    • null if services belonging to this category have mixed consent states: e.g. Marketing: null if 1 service is false while other services in this category are true

      ⚠️ Warning: Categories are still in Beta version. CMP uses category slugs to identify the categories even when a user is on different language. To identify the existing category slug, one can open console on preview page of the CMP and paste following command in console UC_UI.getSettingsLabels().categories.

Usage with Google Tag Manager / Data Layer¶

Prerequisites¶

In order to follow this documentation, we assume you have: - A Google Tag Manager account. - Created a Google Tag Manager container on you website. - Inserted the Google Tag Manager script into your website. - Inserted your Usercentrics script into your website.

To configure your Google Tag Manger to listen to events pushed into the Data Layer follow these steps:

Create Variables¶

You have to create consent default status variables for each of your non-IAB vendor script tags so that they are not triggered without consent.

1. Navigate to "Variables" in the side menu of the Google Tag Manager and then click on "New".

2. Add a new variable of type "Data Layer Variable".

3. In the top left, name the variable "XXX Variable".

a. “XXX” → Please insert here the name of Data Processing Service e.g Google Analytics

1. Under "Data Layer Variable Name", insert the name of Data Processing Service e.g “Google Analytics”.

a. The name has to match exactly (hyphenation, and capitalisation) the Service name you added in your Admin Interface under Service Settings

1. Tick "Set Default Value" and set the default value to false.

2. Save "Google Analytics Variable".

3. Repeat for all non-IAB vendor scripts

Add Trigger¶

There are several ways on how to implement triggers in a Tag Management System. Usercentrics recommends the following option, however, depending on your setup, other structures might be more reasonable.

1. Navigate to "Triggers" in the side-menu and click on "New".

2. Add a new trigger of type "Custom Event".

3. In the top left, name the trigger "XXX Trigger".

a. “XXX” → Please insert here the name of Data Processing Service e.g “Google Analytics Trigger”

1. Tick "Use regex matching" next to the "Event Name" input field

2. Under "Event Name", insert "(consent_status.*)".

a. please be ensure to spell consent_status exactly like this.

1. Tick "Some Custom Events".

2. In the drop-down menus, set the following condition: "Google Analytics Variable" contains true.

a. Explanation: The variable contains the user's consent information (variable=true - user opted in || variable=false - user opted out) for a specific technology. Hence, the trigger should only be fired (and tag therefore activated), if the variable=true

1. Save "Google Analytics Trigger".

2. Add the trigger to "Google Analytics Tag".

3. Repeat this for each non-IAB vendor script in your Tag Manager

Repeat this for each non-IAB vendor¶

• Create a default status variable

• Create a new trigger on the event consent_status for the vendor script tag

• Add the trigger condition for the respective tag with the condition: "XXX Variable" contains true.

a. “XXX” → Please insert here the name of Data Processing Service e.g Google Analytics

• Add the trigger to the tag

Usage as Window Event¶

It is also possible to listen to events that we dispatch as Window Event. The window event name can be configured in the admin interface under Implementation -> Data Layer and Events -> Window Event. In the following example we assume you created a Window Event with the name "ucEvent". This is an example code for an event listener:

• Example: listen to event and check consent status of a service:

window.addEventListener("ucEvent", function (e) {    
    if( e.detail && e.detail.event == "consent_status") {
        // check for consent status of service "Google Ads Remarketing"
        if(e.detail['Google Ads Remarketing'] === true) {
          console.log('Google Ads Remarketing has consent');
        }
        else {
          console.log('Google Ads Remarketing has no consent');
        }
    }
});

App initialization (Browser UI)¶

To ensure the CMP is already initialized before performing app interactions, you can use one of the following options.

Event¶

You can add an event listener of app initialization before loading our CMP script Example:

 window.addEventListener('UC_UI_INITIALIZED', function(event) {
  // initialized
});

Window Method¶

Once the app is initialized, the window variable isInitialized is set to true. Example:

UC_UI.isInitialized(): bool

Example usage¶

In this example, we show you how to display Second Layer once the app is initialized.

if (window.UC_UI && window.UC_UI.isInitialized()) {
  UC_UI.showSecondLayer()
} else {
  window.addEventListener('UC_UI_INITIALIZED', function(e) {
    UC_UI.showSecondLayer()
  });
}

App navigation (Browser UI)¶

Usercentrics provides a window event to target the user navigation on the CMP layers.

Anchors custom events¶

This event gets triggered if you save #onUc(.*)Click for an anchor URL in the admin on the Content area.

Those are the anchor links: - privacy policy - cookie policy - imprint

Example usage¶

Example of an URL: https://mywebsite.de/privacy-policy.html#onUcMyPrivacyLinkEventNamingClick

A user click on the privacy policy link would trigger a "onUcMyPrivacyLinkEventNamingClick" custom event.

 window.addEventListener('onUcMyPrivacyLinkEventNamingClick', function(event) {
  console.log('Click on the privacy link.');
});

Privacy Policy and Imprint Custom Events¶

We provide two custom events for the Imprint and Privacy Policy URL fields in the Admin Interface: - #onUcPrivacyClick for the Privacy Policy URL field - #onUcImprintClick for the Imprint URL field.

You can add these anchors in Content > First Layer. With these custom events, you can define a Window Event Listener to do a action that you want, for example, you can create an event to redirect to your privacy policy page.

window.addEventListener("onUcImprintClick", function(e){
  console.log("Insert here your logic for Imprint")
})

window.addEventListener("onUcPrivacyClick", function(e) {
  console.log("Insert here your logic for Privacy Policy")
})

UC_UI_VIEW_CHANGED¶

This event gets triggered when: - the user opens a layer - the user switches from layer one to layer two - the user switches from layer two to layer one - the user closes all layers

The event also holds additional data with more details about the user behaviour. It is possible to know the current layer displayed for the user and the previous layer.

Possible values for the current view and previous are: - "FIRST_LAYER", - "NONE", - "PRIVACY_BUTTON", - "SECOND_LAYER",

UC_UI_CMP_EVENT¶

This event is triggered by the most important actions through the Consent Management Platform, enabling you to listen to user interactions and compare the different variants when using AB testing. Those actions are:

Example usage¶

You can add an event listener to detect view changes Example:

 window.addEventListener('UC_UI_VIEW_CHANGED', function(event) {
  console.log('Current view is: ' + event.detail.view);
  console.log('Previous view is: ' + event.detail.previousView);
});