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

Consent Solutions Knowledge Base

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 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

 

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 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/...

Labels (1)