DG and Privacy UX
cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Consent Solutions Knowledge Base

UCP Javascript API Part 1/3

Universal Consent Platform Javascript API

Document Status: Draft (v3)

To better support the various business requirements of our customers our Universal Consent Platform (UCP) scripts have a supported API built in. This document outlines the functionality present in that API, how to use it, and how to solve some common scenarios.

What are the Universal Consent Scripts?

The UCP scripts power all the UCP functionality we provide on your web pages. They start with the script block you can retrieve from our Privacy Application. When that script block is added to your site it will start to function.

This script block is just a loader script, pulling in the actual scripts which power our consent functionality. The following scripts are always loaded:

evidon-site-notice-tag.js: this is the script which does the bulk of the work.

country.js: this script has no api functionality. It only allows us to detect the current country the user is in so we show the correct notice experience.

settings.js: this script contains the settings for the given domain and has no api functionality.

snthemes.js: this script contains the defined themes for your notices, which provide the look and feel of the displayed notice elements. It has no API functionality.

<language code>.js: this script provides all the messaging displayed to the user. The exact name of the file depends on the users browser language settings. This has no API functionality.

In addition to the scripts listed above we have several scripts which can be loaded depending on other settings. They are:

evidon-banner.js: this script is downloaded if we need to display a consent banner to the current user. There are some supported API functions inside this script.

evidon-barrier.js: this script is downloaded if we need to display a consent barrier to the current user. There are some supported API functions inside this script.

evidon.gdpr-overlay.js: this script controls the option dialog containing the list of vendors, the gdpr access page, and the gdpr access request form.

evidon-cmp.js: this script powers the UCP support for the IAB GDPR framework, allowing some advertising vendors to gather consent from users for various purposes.

General API Usage

When our scripts load they create a global object under the window namespace called “evidon”.

window.evidon

After our scripts successfully execute there will be a “notice” object added to the window.evidon namespace.

window.evidon.notice

That is the starting point for our supported API. All API methods will be located on the window.evidon.notice object, or a sub-object (window.evidon.notice.banner for example).

If you inspect that object in something like Chrome tools you will see a bunch of methods located on the window.evidon.notice object. Some of them will start with an underscore (ex: _hookConsentEvents). Any method starting with an underscore is NOT a supported API method. Those indicate functionality we consider private or internal and should not be used by our customers.

Callback Methods

This is the list of the callback methods communicating important actions so customers can execute their own actions using javascript.

window.evidon.priorConsentCallback(categories, vendors, cookies)

This is executed whenever consent is detected. That can happen in the following circumstances:

1. When the script executes and detects the consent cookie is present. 2. When a user triggers a consent action.

3. When consent is not required for a given domain/country.

Parameters:

categories – an object containing the state of the category consent selections. This list will either contain the names of the categories and a Boolean (true/false) on whether the user has consented to that category. Or it can contain the indicator “all” with a true/false indicating the user has either consented or not consented to all categories.
Ex: categories[‘advertising’] == true or categories[‘all’] == true

vendors – an object containing the state of all vendor consents. This is similar to the categories except it goes to the individual vendor level. Again, there is an “all” indicator to cover all vendors.
Ex: vendors[‘adobe’] == true or vendors[‘all’] == true

cookies – an object containing the state of all cookie consents. The cookies are indicated using the name you provided when you added them to the system. There is also an “all” indicator to cover all cookies.
Ex: cookies[‘login cookie’] == true or cookies[‘all’] == true

The parameters may not be present on your tag as they were introduced well after the release of the Universal Consent Platform. If they are missing you can simply add them or you can log into our privacy application and retrieve the full tag from there.

window.evidon.closeCallback()

This is executed when a consent UI element (banner, barrier) is closed by the user without consent being given, and the user didn’t specifically decline.

window.evidon.consentWithdrawnCallback()

This is executed when a user withdraws consent. Since our scripts do not perform any action by default when consent is withdrawn this allows our customers to perform some kind of action (refresh the page for example). This is fired after consent has already been withdrawn so there is no mechanism for blocking the withdraw action.

window.evidon.consentDelcinedCallback()

This is executed when a user specifically declines to give consent, which is different from just closing the UI element. We have broken this out so our customers can perform different actions on a decline instead of a close.

Labels (3)