Technical Implementation Guide

JavaScript Tag Integration (Web)

Get started quickly by adding our CMP JavaScript file to the top of the document head of your site, before any other script tags that may need to access the GDPR:

<script src="https://consent.cmp.oath.com/cmp3p.js"></script>

For most publishers, this will work fine. If you are interested in other options that do not require synchronous loading of the script see Additional Options For Loading cmp3p.js

Initialization

For the sake of integration, the CMP can be initialized with as little scripting as below.

<script>
var config = {
organizationId: 12345
}
window.__cmp('init', config);
</script>

Note: organizationId ‘12345’ should only be used for demo purposes.

 

If testing outside of the EU, add the following to your config to force GDPR scope.

gdprAppliesGlobally: true

 

When the GDPR is initialized, the following happens:

  1. If “gdprAppliesGlobally” is true, the GDPR treats the user as within GDPR scope regardless of the user’s IP-based geographic location (“IP-geo”).
  2. If “gdprAppliesGlobally” is false, the GDPR will use the IP-geo location to determine if the user falls within GDPR scope.
    1. Verizon Media matches against EEA countries and territories to determine GDPR scope.
    2. Verizon Media’s GDPR uses a combination of commonly used third-party vendors for geo resolution.
  3. If the user is within GDPR scope, the CMP checks if the user has already consented.
    1. If consent preferences already exist, the GDPR exposes the preferences to any script on the page (calling JavaScript API) without interrupting the user’s experience.
    2. If consent preferences do not already exist, the CMP displays the consent UI based on the provided configurations.

The gdprAppliesGlobally configuration property allows publishers to leverage user-level or company/site-level context available outside of the scope of the GDPR to determine the user’s jurisdiction. For example, if the user has a registered profile with your product or service where a country of residence is declared, you may use this information to inform the CMP that the user should be treated as under GDPR scope. Similarly, if your company, or the particular product in context, is servicing an EEA market, you can inform the CMP that the user should be treated as within the scope of GDPR.

See the Preview and Configuration Guide > General section for more information about how the gdprAppliesGlobally configuration property can be used.

Configuration Options

Configuration options are passed to the CMP via the init command. Below is a complete example of the configuration properties that can be set.

<script>
var config = {
organizationId: 12345,
gdprAppliesGlobally: true,
cookieDomain: 'example.com',
featureIds: [1, 2],
brandLogoUrl: ‘’,
language: 'en',
text: {
brandHeading: '',
disclosureGeneralHeading: '',
disclosureGeneral: '',
disclosurePublisherHeading: '',
disclosurePublisher: '',
disclosurePartnerHeading: '',
disclosurePartner: '',
disclosureFeatureHeading: ‘’,
purposeListHeading: '',
partnerListHeading: '',
confirmDisagree: '',
actionLearnMore: ‘’,
actionAgree: '',
actionDisagree: ‘’,
actionManageOptions: '',
ctionSelectAll: '',
actionDeselectAll: '',
actionContinue: ''
},
layout: {
modal: false,
bannerPosition: "bottom",
showDisagreeButton: false,
showDetailsScreen: true
},
styles: {
primaryColor: "#2D6AB1",
primaryTextColor: "#ffffff",
secondaryColor: "#ffffff",
secondaryTextColor: "#2D6AB1",
fontFamily: "Helvetica",
textColor: "#000000",
textLightColor: "#cccccc",
linkColor: "#2D6AB1",
backgroundColor: "#ffffff",
headingColor: "#000000",
headingTextColor: "#ffffff",
toggleOnColor: "#19B854",
toggleOffColor: "#e5e5e5",
bannerColor: "#1bb578",
bannerTextColor: "#ffffff"
}
}
window.__cmp('init', config);
</script>

Note: organizationId ‘12345’ should only be used for demo purposes.

 

Customizable Properties

organizationId - (Number, required) Verizon Media Publisher / Advertiser ID. Used for metrics reporting and troubleshooting.

gdprAppliesGlobally - (Boolean, optional) Indicates that the CMP should treat all users as being under EU jurisdiction. Default is false.

cookieDomain - (String, optional) Specifies a domain to write cookies so users’ consent preferences are shared across subdomains.

Note: the specified domain must be the current domain or an ancestor domain of the current domain hosting CMP JS.

featureIds - (Array[Number], optional) List of IAB feature ID’s which the publisher supports. Default is an empty list.

brandLogoUrl - (String, optional) URL for a brand logo to appear to the left of the brand heading.

language - (String, required) Two-letter lowercase ISO 639-2 language code.

text - (Object, required) Configurable text values

brandHeading - (String, optional) Title displayed at the top of all screens in the modal consent flow. Commonly used to display your company name or brand heading. No default.

disclosureGeneralHeading - (String, optional) Bold heading on the Landing screen used to introduce the disclosureGeneral text. Default is Before you continue to our site... .

disclosureGeneral - (String, required) Disclosure on the Landing screen used to describe how and for which purposes users' data is processed and with whom data is being shared. In the layered approach, this disclosure is meant to be all-encompassing and provides an opportunity to clearly describe data processing in layman's terms as opposed to Legalese. If the user clicks the Agree button, all solicited consents are set to on, including all available purposes and all vendors specified by the pubvendors.json file, or else the GVL. No default.

disclosurePublisherHeading - (String, optional) Bold heading on the Details screen, when enabled, used to introduce the disclosurePublisher text. Default is How data brings you better ad experiences.

disclosurePublisher - (String, required) Disclosure on the Details screen, when enabled, used to describe in more detail how and for which purposes users' data is processed, and provides an opportunity to explain the value proposition for the user or provide specific examples for illustration. No default.

disclosurePartnerHeading - (String, optional) Bold heading on the Details screen, when enabled, used to introduce the disclosurePartner text. Default is Our Partners.

disclosurePartner - (String, required) Disclosure on the Details screen, when enabled, used to describe in more detail why and with whom users' data is shared, and provides an opportunity to explain the value proposition for the user or provide specific examples for illustration.

disclosureFeatureHeading - (String, optional) Text heading for IAB TCF features you wish to use and disclose to the user on the Manage Options screen under purposes selection. Default is We also use your data for the following features.

purposeListHeading - (String, required) Language on the Manage Options screen to introduce the IAB TCF purposes list consent screen and explain critical details about the experience, user controls, or other information presented on the screen.

partnerListHeading - (String, required) Language on the Manage Options screen to introduce the IAB TCF vendors list consent screen and explain critical details about the experience, user controls, or other information presented on the screen.

confirmDisagree - (String, optional) Confirmation message displayed when the user deselects all purposes or partners on the Manage Options screen and attempts to continue. This message provides a “last call to action” to explain the value proposition and nudge the user to consider granting their consent. No default.

actionLearnMore - (String, optional) Hyperlink exposed on the Landing screen takes the user to the Details screen which displays detailed descriptions about how their data is used and about partners their data is shared with. Default is Learn more about how we and our partners use your data.

actionAgree - (String, required) Text displayed for the Agree button on the Landing screen and Details screen, if enabled. When a user clicks the Agree button, all solicited consents are set to on, including all available purposes and all vendors specified by the pubvendors.json file, or else the GVL. Default is Agree.

actionDisagree - (String, required) Text displayed for the Disagree button on the Landing screen and Details screen, if enabled. When a user clicks the Disagree button, all solicited consents are set to off, including all available purposes and all vendors specified by the pubvendors.json file, or else the GVL. Default is Disagree.

actionManageOptions - (String, required) Text displayed for the Manage Options button on the Landing screen and Details screen, if enabled. User clicks the Manage Options button to open the screen and manage their privacy choices. Default is Manage Options.

actionSelectAll - (String, required) Text display for the Select All button on the Manage Options screen, for both purposes and partners. When a user clicks the Select All button, all toggles within the screen are set to on. Default is Select All.

actionDeselectAll - (String, required) Text display for the Deselect All button on the Manage Options screen, for both purposes and partners. When a user clicks the Deselect All button, all toggles within the screen are set to. Default is Deselect All.

actionContinue - (String, required) Text display for the Continue button in the Manage Options screen, for both purposes and partners. When a user clicks the Continue button, all currently selected toggles are saved and the user is taken to the next step in the flow. Default is Continue.

layout - (Object, optional) - Configurable layout options

Modal - (Boolean, required) Specifies whether to prompt for consent using a modal dialog or a non-modal banner. When the UI is displayed as a modal, users cannot dismiss the consent UI, thereby blocking them from proceeding to content until they have made explicit consent choices. Default is true.

bannerPosition - (String, optional) Specifies whether the banner shows at the top or bottom of the page. This option is only relevant when modal is set to false.

showDisagreeButton - (Boolean, required) Specifies whether to show a Disagree button on the consent Landing screen or not. This button offers a one-click withholding of all consents. Default is true.

showDetailsScreen - (Boolean, required) Specifies whether to show a Learn More link within the Landing screen or not. The link takes the user to a middle layer screen that allows you to provide a more detailed description of the activities and processing described on the first screen with specific references and examples. Default is true.

styles - (Object, optional) Configurable style options

primaryColor - (Hex) Primary button color.

primaryTextColor - (Hex) Primary button text color.

secondaryColor - (Hex) Secondary button color.

secondaryTextColor - (Hex) Secondary button text color.

fontFamily - (String) CSS web safe font family for text fields.

textColor - (Hex) Text color for text fields.

textLightColor - (Hex) Light text color for text fields. Used in parts of the Manage Options screen to provide contrast for certain text fields.

linkColor - (Hex) Text color for hyperlinks.

backgroundColor - (Hex) Main background color for screens in the consent flow.

headingColor - (Hex) Background color for brand heading situated at the top of all screens in the consent flow.

headingTextColor - (Hex) Text color for bold headings throughout screens in the consent flow.

toggleOnColor - (Hex) Color used when a toggle is switched to the on position.

toggleOffColor - (Hex) Color used when a toggle is switched to the off position.

bannerColor - (Hex) Background color for banner overlay view. This option is only relevant when modal is set to false.

bannerTextColor - (Hex) Text color for text fields in banner overlay view. This option is only relevant when modal is set to false.

Localization

Publishers who localize their websites will also want to localize their consent UI. Verizon Media’s CMP supports the following 24 languages supported by the IAB TCF.

 

Three sources of text used in the CMP consent UI support localization.

  1. IAB TCF GVL - Provides standardized names and definitions for features and purposes.
  2. Publisher - Provides configurable text for legal copy and some other labels in the UI. See the Configuration Options section of this article for more detail.
  3. CMP UI - Provides out-of-the-box text for UI components:
    1. Non-configuration terms - Terms in the UI that currently cannot be customized; Verizon Media provides translations for these.
    2. Configuration term defaults - Terms in the UI that can be customized but have default values; Verizon Media provides default translations for these when values are not specified on initialization.

The language configuration option determines which language the CMP uses for the GVL provided text as well as the CMP UI provided text. The text configuration option contains publisher-provided text for the specified language. Some text terms have default translations that appear in the UI if values are not specified during initialization. Sites offered in any of the 24 supported languages (once finalized and translated for all text configuration options) should store a copy of the configuration for each language. Use the corresponding two-letter ISO 639-2 language code to specify the language configuration, along with translated text, based on the user’s selected language.

Consent Storage

Verizon Media’s CMP stores users’ consent in first-party cookies. These cookies expire after 13 months, at which time the user will be re-prompted for consent.

CMP JS API

Retrieving users’ consent preferences

Verizon Media’s CMP implements the IAB TCF specification for the CMP JS API for providing users’ consent choices to other scripts on the page. More details about the standardized API commands.

Publisher CMP commands

In addition to the standard commands, Verizon Media provides some additional commands for publishers.

init - This command triggers the initialization logic, which includes determining if the user should be prompted for consent. A response is sent to any script that requests consent from the CMP once initialization is completed. The initialization process is completed only after the init call is made and the user has selected and saved their consent preferences (if prompted). For an example of the init call see Initialization.

renderConsents - To comply with the GDPR and IAB TCF policies, users must have an opportunity to modify or revoke their consent choices. The CMP JS supports this with the renderConsents command. To re-prompt a user, call the command shown below. When called, the CMP displays the modal consent UI on the Manage Options screen. Existing consent choices are pre-populated in the UI where users can modify their choices.

window.__cmp('renderConsents', callback);

The callback argument is optional. If provided, 2 arguments will be passed to the callback function after the user has updated their consent preferences. The callback function signature is shown below, where consentString is the base64 encoded IAB TCF consent string and success is a Boolean specifying whether the consent capture flow was completed successfully.

function callback(consentString, success) {}

Specify your vendor list

Verizon Media’s CMP supports the pubvendors.json TCF spec which is used to edit the partner list displayed to users and allows for an on/off toggle within the consent UI.

Place a JSON file at the “.well-known” path on your site to inform the CMP which vendors you want displayed in the consent UI. The JSON file contains some vendor list metadata and a list of global vendor ID’s that the CMP will use to display individual vendor information and processing declarations in the consent UI. The file must be formatted according to the TCF pubvendors.json technical specifications. An example is provided below. Use our vendor management tool to compile and generate a pubvendors.json file.

{
"publisherVendorsVersion": 1,
"version": 1,
"globalVendorListVersion": 1,
"updatedAt": "2018-05-14T00:00:00Z",
"vendors": [
{
"id": 1
},
{
"id": 2
},
{
"id": 3
}
]
}

If the CMP cannot locate a pubvendors.json file in the “.well-known” path, the latest Global Vendor List is loaded by the UI.

publisherVendorsVersion - (Number, required)The version of the pubvendors.json spec (currently 1).

version - (Number, required) The version of this pubvendors.json file, incremented on each update.

globalVendorListVersion - (Number, required) The version of the GVL this was created from

updatedAt - (String, required) The ISO 8601 formatted datetime this file was updated.

vendors - (Array, required) A list of vendor objects with only the “id” property. Required where vendor “id” maps to the global vendor list.

Additional Options For Loading cmp3p.js

As mentioned earlier, synchronous loading of the CMP script is the simplest implementation option. However, because the file must be loaded synchronously, it may have a small impact on page load time, particularly when not cached by the browser.

<script src="https://consent.cmp.oath.com/cmp3p.js"></script>

When loading the CMP script asynchronously, some code must be loaded on the page before other scripts (that would need to access the CMP) are loaded. This code is separated out into a cmpStub.min.js file.

Note: The cmp3p.js file also includes this stub code, and is only executed if the stub tag is not also on the page.

This enables a few options for integrating Verizon Media’s CMP into pages. In each of these options, the synchronous script must be placed in the page header prior to any other script that may need to access the CMP.

Option 1 - Synchronous stub tag, asynchronous cmp3p.js tag

<script src="https://consent.cmp.oath.com/cmpStub.min.js"></script>
<script src="https://consent.cmp.oath.com/cmp3p.js" async></script>

Pros - This option allows for the synchronous loading of the smaller stub tag, while asynchronously loading cmp3p.js.

Cons - There is additional network overhead with importing 2 script files, which may outweigh the benefit of loading a smaller file synchronously.

Option 2 - Embed code from https://consent.cmp.oath.com/cmpStub.min.js in the page at build time or when serving the page (server side), and load cmp3p.js asynchronously

<script> /* code embedded by web server */ </script>
<script src="https://consent.cmp.oath.com/cmp3p.js" async></script>

Pros - No synchronous script import is required. The stub code is already embedded in the page header.

Cons - Requires additional work by publishers to embed this script in their page. If embedded at build time (as opposed to when the page is served), then there is potential for being out of date with the latest stub code.