The Consent Platform (UCP) JavaScript API Documentation

Overview

This document outlines the functionality present in the Universal Consent Platform (UCP) API, how to use it, and how to solve 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 you add the script block 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 script does the bulk of the work.
• country.js: This script allows you to detect the current country the user is in so we show the correct notice experience. It has no API functionality.
• settings.js: This script contains the consent settings for the given domain. It 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. It has no API functionality.

In addition to the scripts listed above, we have several scripts that you can load depending on the settings you’ve configured within UCP. They are:

• evidon-banner.js: This script is downloaded 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 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 Options 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

Script load

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

window.evidon

 

Script execution

After our scripts successfully execute a “notice” object is added to the window.evidon namespace:

window.evidon.notice

That is the starting point for our supported API. All API methods are located on the window.evidon.notice object, or a sub-object:

window.evidon.notice.banner

 

If you inspect the object in Chrome tools you will see a number of methods located on the window.evidon.notice object. Some will start with an underscore (eg. _hookConsentEvents).

Note: Any method starting with an underscore is NOT a supported API method. These are internal and should not be used by customers.

Callback Methods

You can execute your own JavaScript actions using the following list of callback methods:

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.

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.

 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.

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 add them or log in to our platform and retrieve the full tag from there.

window.evidon.closeCallback()

This is executed when a consent UI element (eg. 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 like refresh the page. This is fired after consent has 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 closing the UI element. We have broken this out so our customers can perform different actions on decline and close.

Supported API Functionality

window.evidon namespace

There are a few properties located at the root window.evidon portion of the API. The following are supported values that can be located in that object.

Properties

Property	Description	Permissions
notice	The notice object.	Read-Only
id	This is your company identifier.	Read-Only
userid	Use this property to assign an identifier for the current active user. For example, if you have an internal user-id value for the user, you can place it here and we will store that information with our reporting information.	Editable
banner	Reference to the active banner object if available. This will only be set if a banner needs to be displayed to gather consent.	Read-Only
barrier	Reference to the active barrier object if available. This will only be set if a barrier needs to be displayed to gather consent.	Read-Only
gdprL2	Reference to our privacy Options Dialog object, which is used to display the more advanced consent gathering mechanisms (such as GDPR support, IAB support, etc.). This will only be set if the Options Dialog is activated.	Read-Only
cmp	Reference to our “cmp” object which powers the IAB __cmp API. T	Read-Only
preferencesDialog	This is the latest version of our privacy Options Dialog and is used to display more advanced consent information.	Read-Only
Location	This contains the country information pulled from our geo-location script. It will only have a value if the country.js script arrives before our main script API is available. It should not be used as a reliable mechanism to determine the active country location.	Read-Only
Themes	Contains the object holding the theme information used to power the UI displays.	Read-Only
consentTemplates	This is a list of the different consent combinations defined for the current domain settings.	Read-Only
link	Reference to the object that controls our consent link access.	Read-Only
button	Reference to the object that controls our consent button access.	Read-Only
events	This is an internal event queue.	Read-Only
enableGoogleConsentSupport	Use this property to enable/disable support for the Google Consent API. This is an optional property. The Consent API will be enabled by default if you do not add it to your script. If you wouldlike to support the Google Consent API, we recommend adding the support into your main script block so will be set before the consent api calls are made.

 

window.evidon.notice namespace

Properties

Use the following properties from the window.evidon.notice object to provide access to information that might be valuable to other scripts running on the page, but should be considered READ-ONLY. Any properties that can be modified at runtime will have a supported API method to allow that. For example, you can use the setLocation() method to change the country on the notice.

Property	Description
country	The currently active country object.
languageCode	The active language code.
languageRoot	The active root language. This is used to pull the correct set of translation values.
activeTranslations	The object holding the currently active set of translations.
settings	The settings object holding all the possible settings for the current domain.
domain	The active domain
activeSettings	The object holding the currently active settings for the notice.
consentTypeId	The identifier indicating the type of consent is active for this notice: 1: no consent 2: banner consent 3: barrier consent
privacyAccessTypeId	The identifier indicating the type of privacy tool access mechanism to show: 1: link 2: button
consentIsGiven	Flag indicating whether the active user has provided consent.
regulationId	Indicates the active regulation identifier. Possible values are: 0: No regulation 1: CCPA 2: GDPR
regulationConsentTypeId	Indicates the active consent type. Possible values are: 0: No consent required 1: Opt-in consent 2: Opt-out consent

 

Methods

The following list of methods are supported under the window.evidon.notice namespace.

appendScript(url, callback)

• url: the url to add to the script “src” attribute.
• callback: an optional function to call once the script has finished loading.

Call this API method to append a script to the current document.

consentGiven()

Calling this method instructs our script to drop the consent cookie and execute any consent callback/tag manager functionality. Use this call if you are going to provide a consent mechanism not currently supported by our scripts (your own consent button for example).

getConsentUrl()

Returns the url to the consent tool for this notice. You can use this method to get the raw url, but we suggest using the “showConsentTool” method to actually display the consent tool.

showConsentTool()

Instructs our consent tool to display based on the currently defined rules (overlay vs. new window for example). Use this method if you are going to build your own access to our consent tool.

isMobile()

A helper method that returns true if we are running on a mobile device and false for a desktop. If you need to match any mobile vs. desktop logic from your scripts to ours we recommend using this method to check for mobile device execution.

showNotice()

Call this to display the consent notice. This is the primary method called to run the logic and make the checks necessary to display notice elements based on the environment settings (country, language, etc.).

setLocation(locationObj)

locationObj: the json object containing the details for the location you want to use. The format of the object is:

{'code':'us','id':1,'defaultLangauge':'en-us'}

Call this method to set the notice location (country) and to override the country settings if necessary.

The following table contains the identifiers for all the countries we currently support.

1	us	United States	65	jo	Jordan
3	de	Germany	66	ir	Iran
4	es	Spain	67	ua	Ukraine
5	fr	France	68	vn	Viet Nam
6	gb	United Kingdom	69	ws	Samoa
7	it	Italy	70	am	Armenia
8	nl	Netherlands	71	ph	Philippines
9	ca	Canada	72	al	Albania
10	cn	China	73	ai	Anguilla
11	il	Israel	74	ag	Antigua & Barbuda
12	mx	Mexico	75	aw	Aruba
13	ru	Russia	76	bs	Bahamas
15	dk	Denmark	77	bb	Barbados
16	ie	Ireland	78	bz	Belize
17	no	Norway	79	bm	Bermuda
18	pl	Poland	80	bo	Bolivia
19	at	Austria	81	ba	Bosnia & Herzegovina
20	be	Belgium	82	vg	British Virgin Islands
21	ch	Switzerland	83	ky	Cayman Islands
22	sv	Sweden	84	cl	Chile
23	sk	Slovakia	85	co	Colombia
24	hu	Hungary	86	cg	Congo (Brazzavilla)
25	fi	Finland	87	cr	Costa Rica
26	pt	Portugal	88	cd	Democratic Republic of the Congo
27	cz	Czech Republic	89	dm	Dominica
28	lu	Luxembourg	90	do	Dominican Republic
29	gr	Greece	91	ec	Ecuador
30	bg	Bulgaria	92	sv	El Salvador
31	ro	Romania	93	ga	Gabon
32	ee	Estonia	94	gh	Ghana
33	lv	Latvia	95	gd	Grenada
34	lt	Lithuania	96	gt	Guatemala
35	si	Slovenia	97	gy	Guyana
36	mt	Malta	98	ht	Haiti
37	cy	Cyprus	99	hn	Honduras
38	is	Iceland	100	jm	Jamaica
39	tr	Turkey	101	md	Moldova
40	eg	Egypt	102	ma	Morroco
41	sa	Saudi Arabia	103	an	Netherlands Antilles
42	br	Brazil	104	ni	Nicaragua
43	ar	Argentina	105	pa	Panama
44	tw	Taiwan	106	py	Paraguay
45	kr	South Korea	107	pe	Peru
46	jp	Japan	108	pr	Puerto Rico
47	au	Australia	109	kn	Saint Kitts & Nevis
48	nz	New Zealand	110	sn	Senegal
49	za	South Africa	111	lc	Saint Lucia
50	dz	Algeria	112	vc	Saint Vincent & Grenadines
51	ly	Libya	113	sr	Suriname
52	sd	Sudan	114	tt	Trinidad & Tobago
53	ng	Nigeria	115	tn	Tunisia
54	ae	United Arab Emirates	116	tc	Turks & Caicos Islands
55	id	Indonesia	117	uy	Uruguay
56	my	Malaysia	118	vi	Virgin Islands
57	th	Thailand	119	ve	Venezuela
58	pk	Pakistan	120	ge	Georgia
59	in	India	121	az	Azerbaijan
60	sg	Singapore	122	la	Laos
61	hr	Croatia	123	kh	Cambodia
62	mk	Macedonia	124	np	Nepal
63	rs	Serbia	125	lk	Sri Lanka
64	hk	Hong Kong	126	mm	Myanmar
			127	bn	Brunei

 

activateTranslations(code)

code: language code to make the active translation set

Use this method to force a specific language that is different from the browser settings. A use case would be a site that uses a dropdown to switch languages and you want to force the consent messaging to match your site instead of the browser settings.

getBannerStyle()

Use this method to pull the styles for the banner object.

getBarrierStyle()

Use this method to pull the styles for the barrier object.

getButtonStyle()

Use this method to pull the styles for the consent tool button object.

getLinkStyle()

Use this method to pull the styles for the consent tool link object.

getL2Style()

Use this method to pull the styles used for the privacy Options Dialog.

getTranslations()

Use this method to return the active set of translations.

formatTranslation(text)

text: the translation text to apply formatting to

This method executes a string replace on the passed in string to replace other string markers with dynamic values. Currently this method replaces the following:

• {company} – current company division name
• {consentToolUrl} – the url to the cookie consent tool for the active notice/country combination
• {privacyPolicy} – any privacy policy url assigned to the active notice/country combination

dropSuppressionCookie(days)

days: an integer value indicating the number of days to set the cookie for. Leave this as null or 0 to drop a session cookie.

Use this method to drop a cookie to “suppress” the display of the consent UI elements (banner/barrier). This enables compliance with Prior Consent (GDPR,LGPD) instructions to allow a user to access site content without providing consent.

setUserIdentifier(id)

id: a string value which stores the user identifier for the current user.

Use this method to assign a user identifier that can be stored with the reporting information for the active user. This should be an internal identifier that will allow you to identify specific users for actions such as consent. It can also help improve reporting from the UCP by using a unique identifier instead of the default correlation key, which is not guaranteed to represent a unique user.

Note: You can also set the user identifier using the window.evidon.userid property. Since the window.evidon.userid property can be set available before the notice API is available using that property instead of this API method can help prevent timing issues where the User ID is not set before the reporting calls fire, causing the identifier to be excluded from the call. However, both are supported and this call will override the id value if it is set on the window.evidon.userid.

withdrawConsent()

Use this method to withdraw consent for the active user. When called, this method removes the consent cookie and then calls the consentWithdrawnCallback event to execute any code located in that callback.

getConsentData()

This call pulls the list of consented items, categories, and vendors, from the local storage. It wraps the logic of whether this information is stored in the consent cookie or local storage.

The format of the data returned will be similar to the following:

 

{
  "consent_date":"2020-07-31T20:11:01.970Z",
  "categories":{
    "3":{
      "evidon vendors":true,
      "advertiser":false
    }
  },
  "vendors":{
    "3":{
      "80":false,
      "241":true
    }
  },
  "cookies":{
    "3":{}
  },
  "consent_type":1
}

 

The “3” in the structure is the country identifier for the set of categories, vendors, and cookies. All of the information is stored at a country level, allowing different sets of vendors/categories per country.

The consent_type indicates the type of consent requested from the user:

• 0 – no consent required
• 1 – opt-in consent (like the GDPR)
• 2 – opt-out consent (like the CCPA)

getDataRequestUrl()

This call returns the url for the Evidon data request form.

Note: We do not recommend using this form in your own solutions as there are some low-level messaging interactions that happen to allow the form to function properly.

getDoNotSellRequestUrl()

This call returns the url for the Evidon data request form configured for a Do Not Sell request.

Note: We do not recommend using this form in your own solutions as there are some low-level messaging interactions that happen to allow the form to function properly.

getPrivacyPolicyLink()

Returns privacy policy links configured for the active notice/country which was entered in the notice settings when it was configured.

getCookiePolicyLink()

Returns cookie policy links configured for the active notice/country which was entered in the notice settings when it was configured.

showOptions()

Triggers the display of our Options Dialog panel. This is the panel where users can elect to exercise choices on vendors and categories as well as access IAB information if set up. This call wraps the logic for which version of the Options Dialog panel to display.

showOptionPanel (deprecated)

Displays our legacy Options Dialog.

Note: This call is deprecated and we recommend using showOptions instead.

showPreferencesDialog (deprecated)

Displays the current default version of our Options Dialog.

Note: This call is deprecated and we recommend using showOptions instead.

_getConsentedCategories()

Returns the list of categories which have been consented to.

See example of the returned category object:

 

{
“evidon vendors”: true,
“advertiser”: true,
“analytics provider”: true
}

 

The first value is the string identifier for the category. The second value will be true or false. True indicates the vendors in that category have been consented to run.

_getConsentedCookies()

Returns the list of cookies which have been consented to.

_getConsentedVendors()

Returns the list of vendors which have been consented to.

See the example of the returned vendor object:

{
80: true,
81: true,
241: true
}

The first value is the vendor identifier. The second value will be true or false. True indicates the vendor has been consented to and their tags can run.

isGDPR()

Checks to see if the GDPR regulation applies to the active notice/country combination.

isCCPA()

Checks to see if the CCPA regulation applies to the active notice/country combination.

isOptedOut()

Checks to see if the active user has elected to exercise their right to opt-out of data collection for the CCPA.

window.evidon.banner namespace

The following list of methods are supported under the window.evidon.banner namespace.

IEVersion()

A helper method called to return the current version of IE the scripts are running on. There are conditional code blocks which execute differently on earlier version of IE..

closeBanner(eventObj)

eventObj: a standard event object received from JavaScript click events.

The click handler from the banner accept button and close icon. It can be called from your code if you want to simulate a click event, but we recommend you use the window.evidon.notice.consentGiven() API instead.

acceptButtonClicked(eventObj)

eventObj: a standard event object received from JavaScript click events.

The callback executed when a user clicks the Accept button. Call this method to simulate the Accept button click.

optionButtonClicked(eventObj)

eventObj: a standard event object received from JavaScript click events.

This is the callback executed when a user clicks the Options button on the banner. Call this method to simulate the Options button click.

closeIconClicked(eventObj)

eventObj: a standard event object received from JavaScript click events.

The callback executed when a user clicks the Close icon on the banner. Call this method to simuluate the Close icon click.

endsWith(source,value)

• source: source string to check
• value: value to look at the end of the source string for

A helper method that returns a Boolean true if the source string ends with the passed in value.

isOnBanner(element)

element: An element object

A helper method that returns true if the given element object is actually located on our banner display. Use this method to prevent executing a consent event if someone clicks at some random place on the banner. It is unlikely you will need to use this method for anything.

closeConsentBanner()

Instructs the banner to close. This method does not execute any consent functionality. It should only be used if you want to hide the banner without a user consenting for some reason.

getBannerStyle()

Returns the style used to format the banner on the page. This is a helper method which makes sure some specific values (z-index for example) are present in the styles being applied to the banner.

createAcceptButton()

A helper method that creates a formatted Accept button.

createOptionButton()

A helper method to create the Option button displayed on the banner.

createCloseIcon()

A helper method to create the Close icon displayed on the banner.

createBanner()

A method called when the script loads to create the banner structure.

setTextValues(translations)

translations: an object containing the string values for the various banner elements.

Call this method to apply translations to the banner. Typically, this is called from our main notice script if the language is changed. It is highly recommended you use our user interface to make translation changes, but if you need to force these to be different you can use this method.

createNotice()

Call this methoed to create the consent notice and show it on the page. This is called as soon as the script loads so it is unlikely you will need to use it, but if you have to force the banner to display, this method will do that.

destroyNotice()

Instructs the notice to close and remove itself from the DOM. Calling this method does not trigger any type of consent actions or drop the consent cookie. You can use this method if you need to remove the banner from the current page.

scaleForMobile()

A helper method called to apply a zoom on the banner if displayed on a mobile device.

window.evidon.barrier namespace

The following list of methods are supported under the window.evidon.barrier namespace:

createBarrierNotice()

Runs the barrier creation routine.

destroyNotice()

Closes the notice and removes it from the DOM.

showCookieConsentTool()

If the Options Dialog is enabled, this will run the enabled functionality of the Options Dialog. If not, this will show the consent tool in the barrier in an iframe.

window.evidon.gdprL2 namespace

The following list of methods are supported under the window.evidon.gdprL2 namespace:

Note: This object is only available in the window.evidon object after the script has been loaded, which occurs the first time the overlay is triggered to display.

showOverlay()

Execute this method to show the GDPR overlay.

closeOverlay()

Execute this method to hide the GDPR overlay. This call closes the GDPR overlay and removes it from the DOM.

window.evidon.cmp namespace

This is the object that powers the UCP support of the IAB GDPR framework (CMP stands for Consent Management Provider). Currently we do not support using this API directly. Instead, use the window.cmp object which is defined in the IAB EU specifications. (Specification located at: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/...)

The evidon implemention of the __cmp support provides full support for that specification.

window.evidon.cmp2 namespace

The IAB has upgraded GDPR platform to version 2, which is not compatible with version 1.

To support v2 and v1 simultaneously we created a v2 CMP library for our scripts. We do not recommend using any of the functionality in this namespace directly. All the functionality is meant to be internal.

The IAB does define an API for their framework support, geared primarily towards pulling their consent string which is passed along to their advertisers to inform downstream actors of permissions available to them.

The documentation for the IAB v2 framework can be found here:

https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/...