- Overview
- Using a Specific Version of Quantcast Choice
- Security via Integrity Hashes
- Configuration Options
- Sharing Consents Between Multiple Sites You Own or Manage
- Notes about the CMP Configuration
- Visual explanation of Configuration Options (popup)
- Using a Custom Vendorlist
- Allowing Users to Change Consents & 'Privacy Settings' Button
- Determining Consent
- Executing Code after Consent Collection
- Javascript and IMG pixel compatibility
- Base Code Example
- CSS overrides for the CMP UI
Overview
The following content outlines the configuration options and other technical details for Quantcast Choice.
Note that throughout the document there may be some restrictions on certain customization options based on requirements of the IAB Europe framework policies.
This page will be updated from time to time as new features and updates based on policy changes are added.
Tag Type Requirements
Quantcast Choice (along with all CMP solutions built on the IAB Europe Framework) requires the web operator to use JS pixels versus IMG pixels to ensure the communication of consent signals through the daisychain, or otherwise manually alter your IMG code to transmit consent properly. Without this alteration or use of JS pixels, vendors, such as Quantcast, are unable to read a Yes or No consent signal from a CMP and will therefore be unable to perform their indicated purpose/service (advertising, analytics, etc). See the end section prior to the Base Code example at the end of the guide for the necessary steps to alter your code. If you have questions around this, please reach out to support@quantcast.com .
Revalidation of consent
Based on the GDPR regulation and the IAB Europe framework policy, consent will need to be re-acquired after 13 months. Therefore the cookies that Quantcast Choice sets will expire after 13 months, which triggers a re-prompt of the consent UI to the user.
Consent will also need to be requested each time the vendor list is updated. In order to give the best user experience, Quantcast Choice provides an option to fine tune that behavior by allowing the reprompt to be delayed up to 30 days (see “ Min Days Between UI Displays ” in the Configuration Option Documentation below).
It is recommended to also be familiar with the IAB Europe Transparency and Consent Framework Policy , the IAB Europe T&C framework CMP JS API specification . For more information about the IAB Europe Framework please visit: http://advertisingconsent.eu/#about .
Using a Specific Version of Quantcast Choice
Quantcast Choice regularly receives updates for improvements and bug-fixes. Users who wish to robustly test changes to Quantcast Choice on a staging or test environment before moving to production can pin to a specific version of Quantcast Choice. Versions will be deprecated 30 days following the release of a new version. Quantcast Choice users will be notified via email when a new version is released, so that they have time to test and migrate to the latest version.
The file source generated by the Quantcast Choice Self Serve tool will always use the most recent version of Quantcast Choice, with the url:
elem.src = 'https://quantcast.mgr.consensu.org/cmp.js';
To pin to a specific version of Quantcast Choice, replace the URL in the generated Javascript tag with:
elem.src = 'https://quantcast.mgr.consensu.org/v2/cmp.js';
Note that the version (v2, in the example above) needs to be replaced with the desired version number. Version numbers are published in the Quantcast Choice release notes.
Security via Integrity Hashes
Quantcast Choice offers the option to use subresource integrity to ensure the correct version of the Quantcast Choice code is downloaded and has not been tampered with or maliciously altered.
Note: Subresource integrity should only be used if you are using a fixed version of Quantcast Choice, as the default URL receives regular updates and will result in downtime until integrity hash is manually updated by the user.
To use subresource integrity, add the following attributes to the Quantcast Choice Javascript code generated by the Quantcast Choice Self Serve tool:
Note: The hash below is valid only for V2 of Quantcast Choice. To see a list of versions and their corresponding hashes, please visit the Quantcast Choice release notes.
elem.integrity = 'sha256-yotwhobcskdgxtv6hong1rpwqa4aoe36wrhkdpk0fwa=sha256-v6akhwyqchrajmpytnc/u1+1bwmvhr8dpvglkgaaila= sha256-kbuknfvmcfemiqkmao5leu22ldrvs35xefmn5mocdre='; elem.crossorigin = 'anonymous';
Configuration Options
Text Customization and translation Options
These configuration options allow you to customise the copy throughout the CMP. Quantcast also provides translations for certain languages, which can be overridden to match your site's voice.
"Language"
The language for text in the CMP UI. Only a subset of languages are currently supported by Quantcast; please see the list below.
Expected Values:
A valid ISO 639-1 code denoting the language.
Default Value:
"en" (English)
Current Quantcast supported languages:
- "en": English
- "fr": French
- "de": German
- "it": Italian
- "es": Spanish
- "nl": Dutch (Flemish)
- "ru": Russian
- "ar": Arabic
- "fa": Persian (Farsi)
"Persistent Consent Link Label"
The text used for the "Privacy Settings" button.
Expected Values:
A non-empty string.
Default Value:
The string "Privacy Settings" or a default translation based on the configured language, if available.
"Back Label"
The text used for the "back" button.
Expected Values:
A non-empty string.
Default Value:
The string "back" or a default translation based on the configured language, if available.
"Company Label"
The text used as the header for the vendor-list table on page 3 of the CMP.
Expected Values:
A non-empty string.
Default Value:
The string "company" or a default translation based on the configured language, if available.
"Features Label"
The text used for "features" in the detailed vendor view of the vendor list on page 3 of the CMP UI. Features are methods of data use or data sourcing that overlap across multiple purposes, for example "Precise Geographic Location Data" and "Matching Data to Offline Sources".
Expected Values:
A non-empty string.
Default Value:
The string "Features" or a default translation based on the configured language, if available.
"Hide Companies Label"
The text used for "Hide Companies" in the 3rd Party Vendors list on page 2 of the CMP UI, after a user has clicked "View Companies".
Expected Values:
A non-empty string.
Default Value:
The string "Hide Companies" or a default translation based on the configured language, if available.
"Initial Screen Accept Button Text"
The text shown on the "Accept All" button on page 1 of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "I Accept" or a default translation based on the configured language, if available.
"initScreenBodyTextOption"
The variation of copy for the initial screen (page 1) of the CMP UI. For legal purposes, this text is not openly customizable.
Expected Values:
One of either: 1, 2, or 3.
Default Value:
1
The copy for each of the values is as follows:
1: "We and our partners use technology such as cookies on our site to personalise content and ads, provide social media features, and analyse our traffic. Click below to consent to the use of this technology across the web. You can change your mind and change your consent choices at anytime by returning to this site."
2: "We and our partners process your personal data using technology such as cookies in order to serve advertising, analyse our traffic and deliver customised experiences for you. You have choice in who uses your data and for what purposes and after setting your preferences may come back anytime to make changes."
3: "The quality content and information we provide to you depends on the revenue we generate from advertising. We and our partners use your personal data in order to serve personalised advertising, measure activity on the site and deliver personalised features and content to you. Click below to consent to the use of your data. You can revisit your choices at any time."
"Initial Screen Purpose Link Text"
The text for "Show Purposes" on the initial screen (page 1) of the CMP UI. This link will take users to the purpose consent screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "Show Purposes" or a default translation based on the configured language, if available.
"Initial Screen Reject Button Text"
The text shown on the "Reject All" button on page 1 of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "I Do Not Accept" or a default translation based on the configured language, if available.
"Initial Screen Title Text"
The title text that appears at the top of the initial screen (page 1) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "We value your privacy" or a default translation based on the configured language, if available.
"Off Label"
The text used for the "off" toggle state label on the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "off" or a default translation based on the configured language, if available.
"On Label"
The text used for the "on" toggle state label on the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "on" or a default translation based on the configured language, if available.
"Off On Label"
The text used for the "Off/On" table header on the vendor screen (page 3) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "Off/On" or a default translation based on the configured language, if available.
"Privacy Policy Label"
The text used for "Privacy policy" in the detailed vendor view of the vendor list on page 3 of the CMP UI.
Expected Values:
A non-empty string.
Default Value: The string "Privacy policy" or a default translation based on the configured language, if available.
"Legitimate Interest Purposes Label"
The text used for "Legitimate Interest Purposes" in the detailed vendor view of the vendor list on page 3 of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "Legitimate Interest Purposes" or a default translation based on the configured language, if available.
"Purpose Screen Body Text"
The main body text on the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
"[Company Name] and our partners use technology such as cookies on our site to personalize content and ads, provide social media features, and analyze our traffic. You can toggle on or off your consent preference based on purpose for all companies listed under each purpose to the use of this technology across the web. You can change your mind and revisit your consent choices at anytime by returning to this site."
"Purpose Screen Cancel Button"
The text for the "cancel" button on the purposes screen (page 2) of the CMP UI. This link takes users back to the initial screen (page 1) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "cancel" or a default translation based on the configured language, if available.
"Purpose Screen Enable All Button Text"
The text for the "Enable All" button on the purposes screen (page 2) of the CMP UI. The button toggles all purposes to "on".
Expected Values:
A non-empty string.
Default Value:
The string "Accept All" or a default translation based on the configured language, if available.
"Purpose Screen Header Title Text"
The title text in the purposes header on the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "Privacy Settings" or a default translation based on the configured language, if available.
"Purpose Screen Save and Exit Button Text"
The text for the "Save and Exit" button on the purposes consent screen (page 2) of the CMP UI. This button sets and saves all of the users consents.
Expected Values:
A non-empty string.
Default Value:
The string "Save & Exit" or a default translation based on the configured language, if available.
"Purpose Screen Title Text"
The title text on the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "We value your privacy" or a default translation based on the configured language, if available.
"Purpose Screen Vendor Link Text"
The vendor link text on the purposes screen (page 2) of the CMP UI. This link takes users to the vendor screen (page 3) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "See full vendor list" or a default translation based on the configured language, if available.
"Purposes Label"
The text used for "purposes in the detailed vendor view of the vendor list on page 3 of the CMP UI. Purposes are data that drives a specific business model and produces specific outcomes for consumers and businesses, for example "Personalisation" and "Measurement".
Expected Values:
A non-empty string.
Default Value:
The string "Purposes" or a default translation based on the configured language, if available.
"Required Label"
The text used in place of toggles for publisher purposes for which the publisher is claiming a legitimate interest. These purposes can not be toggled on or off, and instead display a permanent status string. This string is only displayed if a publisher also specifies the configuration option "Publisher Purpose Legitimate Interest IDs".
Expected Values:
A non-empty string.
Default Value:
The string "Required" or a default translation based on the configured language, if available.
"Third Party Vendors Label"
The text used as the header of the third-party vendors table on the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "Third Party Vendors" or a default translation based on the configured language, if available.
"Vendor Screen Accept All Button Text"
The text used for the "Accept all" button on the vendor screen (page 3) of the CMP UI. This button toggles all of the vendors to "on".
Expected Values:
A non-empty string.
Default Value:
The string "Accept all" or a default translation based on the configured language, if available.
"Vendor Screen Body Text"
The main body text displayed at the top of the vendor screen (page 3) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string below or a default translation based on the configured language, if available.
"You can set consent preferences for each individual third-party company below. Expand each company list item to see what purposes they use data for to help make your choices. In some cases, companies may disclose that they use your data without asking for your consent, based on their legitimate interests. You can click on their privacy policies for more information and to opt out."
"vendorScreenCancelButton"
The text for the "cancel" button on the vendor screen (page 3) of the CMP UI. This link takes users back to the initial screen (page 1) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "cancel" or a default translation based on the configured language, if available.
"Vendor Screen Purposes Link Text"
The text used for the "Back to purposes" button on the vendor screen (page 3) of the CMP UI. This button takes users to the purposes screen (page 2) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "Back to purposes" or a default translation based on the configured language, if available.
"Vendor Screen Reject All Button Text"
The text used for the "Reject all" button on the vendor screen (page 3) of the CMP UI. This button toggles all of the vendors to "off".
Expected Values:
A non-empty string.
Default Value:
The string "Reject all" or a default translation based on the configured language, if available.
"vendorScreenSaveAndExitButton"
The text for the "Save and Exit" button on the vendor screen (page 3) of the CMP UI. This button sets and saves all of the users consents.
Expected Values:
A non-empty string.
Default Value:
The string "Save & Exit" or a default translation based on the configured language, if available.
"Vendor Screen Title Text"
The title text that appears at the top of the vendor screen (page 3) of the CMP UI.
Expected Values:
A non-empty string.
Default Value:
The string "We value your privacy" or a default translation based on the configured language, if available.
"View Companies Label"
The text for the "View Companies" button on the purposes screen (page 2) of the CMP UI. This button displays the companies (vendors) that are requesting consent for a given purpose.
Expected Values:
A non-empty string.
Default Value:
The string "View Companies" or a default translation based on the configured language, if available.
Branding & Display Options
These configuration options allow control of the CMP's appearance, and brand assets such as custom links and logos.
"Display Persistent Consent Link"
Turns the button on or off
Expected Values:
A boolean - true or false.
Default Value:
true (button is shown)
"Persistent Consent Link Location"
Which corner of the screen the 'Privacy Settings' button is shown in.
Expected Values:
An integer, from 1 to 4. 1 representing the top-left corner, 2 the top-right, 3 the bottom-right, and 4 the bottom-left.
Default Value:
3 (the bottom-right corner)
"Custom Links Displayed on Initial Screen"
Up to 2 links with custom copy and destinations. The links must be formatted as markdown links: [text to show](URL)
Expected Values:
An array of 2 or fewer markdown links. For example:
[ "[privacy policy](https://www.site.com/privacy)", "[contact us](https://www.site.com/contact)" ]
Default Value:
[] (no links added)
"No Option"
Determines whether or not the "Reject All" button on page 1 of the CMP UI should be displayed to the user.
Expected Values:
A boolean - true or false.
Default Value:
true
"Publisher Logo"
A full (absolute) URL path to a hosted image that will be displayed on all pages of the CMP UI. The image size is capped at 170px wide and 90px tall in order to maintain the layout.
Expected Values:
A non empty string containing a full URL to a hosted image.
Default Value:
'' (no image)
"Publisher Name"
The name of the company requesting consent with the CMP, the name is used throughout the CMP's copy.
Expected Values:
A non-empty string.
Default Value:
'[Company Name]'
"Post Consent Page"
This option specifies the full (absolute) URL that a user who rejects all publisher and vendor purposes should be redirected to.
Expected Values:
A non-empty string, containing an absolute URL.
Default Value:
None.
"UI Layout"
The general layout for the CMP UI on desktop and tablet devices.
Expected Values:
One of either "banner" or "popup".
Default Value:
"popup"
Consent Options
These configuration options determine which purposes the publishing site is requesting consent for, how, how often, and from whom.
"Display UI"
Determines which users will be shown the CMP UI. Note that the frequency of prompting is set using the configuration option "Min Days Between UI Displays".
Expected Values:
One of either: "always" or "inEU".
"always": all users will be prompted for consent "inEU": only users in the EU will be prompted for consent "never": no users will be prompted for consent
Default Value:
"inEU"
"Cookie Domain"
Allows the consent settings (cookie) to be shared across domains by specifying the domain of all 1st party cookies set by the CMP.
For example if you have an e-commerce site: store.example.com and a blog site: blog.example.com, you can specify that all cookies be set on example.com; allowing both the store and the blog to share the same consents without re-prompting users.
Expected Values:
A parent of, or the actual domain where the CMP will be shown - excluding top-level domains.
Default Value:
The current domain where the CMP is being shown.
"Cookie Path"
Allows websites where separate URL paths indicate separate subsites to independently collect consent for each subsite.
For example if you host user-generated sites: example.com/user-1-blog and example.com/user-2-blog which should not share consent between sites.
Expected Values:
A parent of, or the actual path where the CMP will be shown.
Default Value:
"/" (all paths including the root will share consent)
"Non-Consent Display Frequency"
The re-prompt frequency, in days, for users who have not given any positive consents; i.e. users who rejected all purposes and vendors.
Expected Values:
A positive integer (not including 0).
Default Value:
1
"Min Days Between UI Displays"
Determines how frequently, in days, the CMP will check for additions or changes to the vendor list, and re-prompt users for consent if changes are found.
Note: Vendors who are added to the list before a user is re-prompted will not receive a consent signal until this value is exceeded.
Expected Values:
A positive integer, representing the minimum number of days before a user is re-prompted.
Default Value:
30
"Consent Scope"
How consent given by a user applies to sites other than the current site. The value "global" includes all IAB framework sites - except those with a "service" level consent scope. The value "service" restricts consent choices only to the current site, and does not honor choices made on other sites.
Expected Values:
One of the following: "global", "service", "global group", or "service group".
Default Value:
"global"
|
Consent scope |
publisher Consent (eupubconsent) |
vendor Consent (euconsent) |
What does this scope mean? |
|
global |
First-party cookie stored on publisher site domain |
Third-party cookie stored on IAB Europe central domain consensu.org |
Global consent means if a user sets consent preferences on another site using global consent, those preferences will apply to your site and the user will only see the consent window again if there are new vendors to consent to. Consent set on your site will apply to other sites using global consent. |
|
service |
First-party cookie stored on publisher site domain |
First-party cookie stored on publisher site domain |
Service consent means global consent will not apply to your site and the user will be asked to set consent preferences for your site and vendors. Preferences set on your site will not apply to other sites with either global or service consent. |
|
global group |
Third-Party Cookie stored on publisher group domain |
Third-party cookie stored on IAB Europe central domain consensu.org |
Global group consent means if a user sets consent preferences on another site using global consent, those preferences will apply to all sites within your group of sites and the user will only see the consent window again if there are new vendors to consent to. Consent set on your sites will apply to other sites using global consent. |
|
service group |
Third-Party Cookie stored on publisher group domain |
Third-Party Cookie stored on publisher group domain |
Service group consent means global consent will not apply to your group of sites and the user will be asked to set consent preferences for your group of sites and vendors. Consent will apply to all sites within your group. Preferences set on your group of sites will not apply to other sites with either global or service consent. |
"Consent Scope Group URL"
Note: using a group-level consent scope requires significant development on your part in order to implement a JSON API or a shared consent cookie destination that is accessible via iframe. Please see the Group Consent API section for more details.
This value is only needed if the consent scope is set to either "global group" or "service group". This is the Group Cookie Access API URL for group-level consent scope. If "Consent Scope Group URL" is not set, but a group-level consent scope is specified, the consent scope will fall back to either "global" (for "global group") or "service" (for "service group").
Expected Values:
A string containing a valid, reachable URL.
Default Value:
None, the consent scope will fall back to either "global" (if Consent Scope is "global group") or "service" (if Consent Scope is "service group").
"Publisher Purpose IDs"
Purposes for which the publisher is requesting consent, in addition to the purposes of vendors. If purposes are requested, they are displayed on the purpose screen (page 2) of the CMP UI. See a list of the purposes and their IDs below.
Expected Values:
An array of purpose IDs.
Default Value:
[] (no purposes)
The list of purposes and their IDs are:
ID : Purpose
- 1 : information storage and access
- 2 : personalisation
- 3 : ad selection, delivery, reporting
- 4 : content selection, delivery, reporting
- 5 : measurement
More information about the purposes can be found in the IAB Framework Policies.
"Publisher Purpose Legitimate Interest IDs"
Purposes for which the publisher is claiming a legitimate interest. The purposes will show a 'required' label instead of an off/on toggle.
Expected Values:
An array of purpose IDs.
Default Value:
[] (no purposes)
The list of purposes and their IDs are:
ID : Purpose
- 1 : information storage and access
- 2 : personalisation
- 3 : ad selection, delivery, reporting
- 4 : content selection, delivery, reporting
- 5 : measurement
More information about the purposes can be found in the IAB Framework Policies.
"Publisher Vendor List URL"
If a vendor list URL is set, that vendor list will be used instead of the Global Vendor List (GVL). To use this option, you must host the vendor list on your domain at the following URL:
http[s]://hostname/.well-known/pubvendors.json
Expected Values:
A valid URL of the above form.
Default Value:
None.
Sharing Consents Between Multiple Sites You Own or Manage
There are two options for sharing consent across multiple domains that you or your company owns or manages. Consent can be shared via an iframe by hosting our provided HTML code at a specific URL, which you pass to Quantcast Choice through a configuration option, or you can build your own custom Consent API - which requires significant development work and support.
Group Consents via iframe
There are 4 steps to sharing consent across domains via an iframe.
1) The configuration option 'Consent Scope' must be set to either 'global group' or 'service group'
2) The iframe HTML we provide below must be hosted on a URL determined by the site owner domain.
3) The URL where the HTML is hosted must be passed to Quantcast Choice via the configuration option 'Group Hosted HTML Cookie Access URL'
4) The cookie setting URL must be assigned in Quantcast Choice via the configuration option 'Consent Scope Group URL'
The iframe HTML:
<!--
For publishers whose consent scope is group level,
host this HTML at the group level cookie access URL.
-->
<html>
<head>
<script type="text/javascript">
function getCookie(name) {
var cookies = document.cookie
.split(';')
.filter(function(s) {
var cookie = s.trim();
if (cookie.indexOf(name + '=') === 0) {
return true;
};
})
.map(function(s) {
return s.trim().substring(name.length + 1);
});
return cookies;
}
var msgIsString = true;
function iframeCookieAccessMsgHandler(event) {
var msg = event.data;
msgIsString = typeof msg === "string";
var json;
if (msgIsString) {
json = event.data.indexOf("__qcCmpCookieAccessCall") !== -1 ? JSON.parse(event.data) : {};
} else {
json = event.data;
}
if (json.__qcCmpCookieAccessCall) {
var obj = json.__qcCmpCookieAccessCall;
var cookieNames = ['euconsent', 'eupubconsent', 'googlepersonalization', 'noniabvendorconsent'];
var localNames = ['_cmpRepromptOptions', '_cmpBlockedVendorsHash', '_cmpNonIabVendorsHash'];
if (cookieNames.indexOf(obj.cookieName) === -1 && localNames.indexOf(obj.cookieName) === -1) {
return;
}
var returnObj = {
"callId": json.callId,
"__qcCmpCookieAccessReturn": {
"cmd": obj.cmd
}
}
if (obj.cmd === "set") {
if (cookieNames.indexOf(obj.cookieName) !== -1) {
document.cookie =
obj.cookieName +
'=' +
obj.cookieValue +
';path=' +
obj.cookiePath +
';expires=' +
obj.expires +
';SameSite=None;secure'
} else {
localStorage.setItem(obj.cookieName, obj.cookieValue);
}
returnObj.__qcCmpCookieAccessReturn.isSuccess = true;
} else if (obj.cmd === "get") {
var consentCookies = null;
var infoObj = null;
if (cookieNames.indexOf(obj.cookieName) !== -1) {
consentCookies = getCookie(obj.cookieName);
infoObj = returnObj.__qcCmpCookieAccessReturn;
if (consentCookies.length !== 0) {
infoObj.cookies = consentCookies;
infoObj.isSuccess = true;
} else {
infoObj.isSuccess = false;
}
} else {
consentCookies = localStorage.getItem(obj.cookieName);
infoObj = returnObj.__qcCmpCookieAccessReturn;
if (consentCookies) {
infoObj.cookies = consentCookies;
infoObj.isSuccess = true;
} else {
infoObj.isSuccess = false;
}
}
Group Consents via custom Consent API
Configuring the CMP to use group-level consents requires building a JSON API that handles GET and POST requests to retrieve and store the consent values. Additionally the API should properly respond to OPTIONS requests.
The API requires appropriate CORS headers for all GET, POST, and OPTIONS requests from an allowed origin (domains in your group). Make sure the following headers are included on responses, replacing values in [] as needed:
access-control-allow-credentials: true access-control-allow-headers: true access-control-allow-methods: get, post access-control-allow-origin: http[s]://[your group domain]
Cookies to be handled by Group API
The CMP expects that the JSON API is capable to both receive and provide responses for the following cookies
|
Cookie Name |
Purpose |
|
euconsent |
TCF Vendor Consent String (this is not required for Global Group consent scope) |
|
eupubconsent |
TCF publisher's own data usages consent |
|
googlepersonalization |
Google Consent String |
|
_cmpRepromptOptions |
Hash that controls reprompt operations of the CMP |
Responding to GET requests
When the API receives a GET request, it should respond by retrieving the cookie(s) from the HTTP request header. Note that cookie headers may include more than one cookie.
The consent cookie is in the format:
[cookie name]=[cookie value]
Where [cookie value] denotes the specific value provided by the CMP for the cookie.
The API should then send a JSON response in the format:
{ “[cookie1 name]”: "[cookie1 value]",
“[cookie2 name]”: "[cookie2 value]", .... }
Note that the service group scheme requires the API parse and return both eupubconsent and euconsent cookies.
Responding to POST requests
When the API receives a POST request, it should respond by setting the cookie(s) sent in the JSON request's body.
The API should expect the JSON be in the format:
{ “[cookie1 name]”: "[cookie1 value]",
“[cookie2 name]”: "[cookie2 value]", .... }
Where [cookie value] denotes the encoded string provided by the CMP for the specific cookies.
The API should emit the following HTTP response headers, in order to set the cookie, replacing values in [] as needed:
set-cookie: [cookie name]=[cookie value]; max-age=15552000; domain=.[your group domain]; path=/
Note that the CMP will execute a POST call for each cookie for which it sets a value, and it expects the Group API to provide a cumulative response will all the cookies that have been set, both in the POST request and the GET request
Sample JSON Response
{
"euconsent": "BOqCe8GOqCe8GAKAbBENCu-AAAAshr_7__7-_9_-_f__9uj3Or_v_f__30ccL59v_B_jv-_7fi_20jV4u_1vft9yfk1-7ctD3tp505iakivXmqdeb9v_nz3_9phP78k89r7337Ew-v83o8b7BAII",
"eupubconsent": "BOqCe8GOqCe8GAKAbAENAAAAsAAAAA",
"googlepersonalization": "OqCe8GOqCe8GgA",
"_cmpRepromptOptions": "OqCe8GOqCe8GIA"
}
Notes about the CMP Configuration
- Currently, the configuration key must be exact, meaning the keys are case sensitive. Using a key ‘publisher name’ will not correctly set the name in the CMP. ‘Publisher Name’ must be used.
- If you do not plan to change the default value for a customization option, you may leave out the entire option parameter from the final JavaScript you include on your site to reduce the size of the code and eliminate any risk in a malformed configuration causing issues with the code.
Visual explanation of Configuration Options (popup)
Using a Custom Vendorlist
Publishers that want to limit the vendors who collect data from their users through their site, can set up a "whitelist" that works with Quantcast Choice to display a subset of vendors from the IAB Global Vendor List in the Choice modal.
Note, that in order to use this feature, the level of consent that a publisher chooses must be service-level (site-specific), not global. This will store a user's consent preferences and the signal passed to vendors in a first-party cookie on the publisher's domain.
To set up this feature, publishers should create a pubvendors.json file in the format outlined below and place it on their own servers at the following path:
http://www.[domain].com/.well-known/pubvendors.json . And configured via the parameter: "Publisher Vendor List URL". Note: This parameter is not included in the generated code and must be added.
“Publisher Vendor List URL”
Determines if, and the location, of a publisher-specified limited vendor list. If not specified, the full global vendor list (GVL) will be used
Expected Values: a valid URL of the form http[s]:// hostname /.well-known/pubvendors.json
Default Value: none
The format of pubvendors.json is as follows:
** note this is not valid json due to comments and is an example only **
{
// [required] version of the pubvendors.json specification
"publishervendorsversion": 1,
// [required] increment on each update of this file
"version": 1,
// [required] the version of the gvl this was created from
"globalvendorlistversion": 1,
// [required] updated for every modification
"updatedat": "2018-05-28t00:00:00z",
// [required] whitelist vendors
"vendors": [
{
// [required] id of vendor from gvl
"id": 1
},
{
"id": 2
}
]
}
In the example above only vendor 1 and 2 from the IAB global vendor list will be listed on the Quantcast Choice purposes and vendors pages. The purpsoes displayed will be limited to those related to the vendors and the publisher. All vendors not listed in the pubvendors.json will not be granted consent.
Allowing Users to Change Consents & 'Privacy Settings' Button
The GDPR and IAB Europe framework require that publishers provide a persistent link on their site that allows users to edit their consent preferences at any time. Below is an example of how that can be done with a simple link.
<a class="change-consent" onclick="window.__cmp('displayConsentUi');">change consent</a>
By default, Quantcast Choice places a persistent button in the corner of the page if the user has valid consents. The buttons color and shape can be customized by using CSS overrides if desired. There are 3 configuration options relevant to this button and its customization:
"Display Persistent Consent Link"
Turn the button on or off
Expected Values:
A boolean - true or false.
Default Value:
true (button is shown)
"Persistent Consent Link Location"
Which corner of the screen the 'Privacy Settings' button is shown in.
Expected Values:
An integer, from 1 to 4. 1 representing the top-left corner, 2 the top-right, 3 the bottom-right, and 4 the bottom-left.
Default Value:
3 (the bottom-right corner)
"Persistent Consent Link Label"
The text used for the "Privacy Settings" button.
Expected Values:
A non-empty string.
Default Value:
The string "Privacy Settings" or a default translation based on the configured language, if available.
Determining Consent
Just like vendors, some publishers will need to wait for a consent signal before setting cookies or processing user personal data for one or more of the purposes they selected if they choose consent as their legal basis for one or more of the purposes.
To do this, publishers will need to update their website code to look for the consent signal. This can be done using the getPublisherConsents command from the IAB framework JS API. More info can be found here in the IAB Europe Transparency and Consent Framework JS API Specification.
Executing Code after Consent Collection
In order to perform an operation when the UI is closed (indicating the user has made a new choice of consents), the __cmp operation to register a callback (specific to the Quantcast Choice CMP, not part of the IAB JS API standard) is as follows:
__cmp('setConsentUiCallback', callback)
The callback will be invoked (with no arguments) the next time the UI is closed which indicates the user has made a new consent choice. To invoke the callback every time the UI is shown, this operation will need to be made before each time the UI is brought up with
__cmp('displayConsentUi')
Javascript and IMG pixel compatibility
If your website uses IMG pixels, you will need to alter your code to pass through proper consent signals. Without either a Javascript pixel or altered IMG pixel, you will not be able to use Quantcast Choice. For web operators currently using Quantcast IMG pixels, below is the code to use to make sure the IMG tag fires properly when consent is granted and to align with GDPR requirements. This accounts for the necessary change of adding the GDPR=0/1 and the consent string to the Quantcast pixel. NOTE: Remember to customize with any additional arguments you are passing today.
var pcode='p-xxxxx'; // this should be replaced by the quantcast p-code for the publisher or marketer
// set to true if you want the pixel to fire when no CMP is found (or returns error)
var firePixelIfCmpNotFound = false;
if(typeof(window.__cmp) !== "function") {
var f = window, cmpFrame;
while(!cmpFrame) {
try {if(f.frames["__cmpLocator"]) cmpFrame = f;} catch(e) {}
if(f === window.top) break;
f = f.parent;
}
var cmpCallbacks = {}
if(!cmpFrame) console.error("CMP not found");
window.__cmp = function(cmd, arg, callback) {
if(!cmpFrame) {
callback({msg:"CMP not found"}, false);
return;
}
var callId = Math.random() + "";
var msg = {__cmpCall: {command: cmd, parameter: arg, callId: callId}};
cmpCallbacks[callId] = callback;
cmpFrame.postMessage(msg, '*');
}
window.addEventListener("message", function(event) {
var dt=event.data;
var json = typeof dt === "string" ? (dt.indexOf("__cmpReturn") != -1 ? JSON.parse(dt) : {}) : dt;
if(json.__cmpReturn) {
var i = json.__cmpReturn;
cmpCallbacks[i.callId](i.returnValue, i.success);
delete cmpCallbacks[i.callId];
}
}, false);
}
window.__cmp('getConsentData', 1, function(consentData, isSuccess1) {
window.__cmp('getVendorConsents', [11], function(consents, isSuccess2) {
if(!firePixelIfCmpNotFound && !isSuccess2) return;
if(!consents.gdprApplies || (consents.purposeConsents[1] && consents.vendorConsents[11])) {
var img=new Image(1,1);
img.src='https://pixel.quantserve.com/pixel/'+pcode+'.gif?'+'gdpr='+(consents.gdprApplies?'1&gdpr_consent='+consentData.consentData:0);
img.style='display:none';
function addImg() {
if(document.body) document.body.appendChild(img);
else setTimeout(addImg, 5);
}
addImg();
}
});
});
Base Code Example
<!-- quantcast choice. consent manager tag -->
<script type="text/javascript", async=true>
var __cmp = (function() {
return typeof(__cmp) == "function" ? __cmp : function(c) {
var b = arguments;
if (!b.length) {
return __cmp.a;
} else if (c == '__cmp')
return false;
else {
if (typeof __cmp.a === 'undefined') {
__cmp.a = [];
}
__cmp.a.push([].slice.apply(b));
}
}
})();
var elem = document.createelement('script');
elem.src = "https://quantcast.mgr.consensu.org/cmp.js";
elem.async = true;
elem.type = "text/javascript";
var scpt = document.getelementsbytagname('script')[0];
scpt.parentnode.insertbefore(elem, scpt);
window.__cmp('init', {
' display ui ': 'ineu',
' min days between ui displays ': 30,
' publisher name ': '[company name]',
' publisher purpose ids ': [1, 2, 3, 4],
' publisher logo ': '[full path url to logo image]',
' initial screen title text ': 'we value your privacy',
' initial screen body text ': '[company name] and our partners use technology such as cookies on our site to personalize content and ads, provide social media features, and analyze our traffic. click below to consent to the use of this technology by [company name] and these 3rd parties across the web. you can change your mind and revisit your consent choices at anytime by returning to this site.',
' initial screen reject button text ': 'i do not accept',
' initial screen accept button text ': 'i accept',
' initial screen purpose link text ': 'show purposes',
' purpose screen header title text ': 'privacy settings',
' purpose screen title text ': 'we value your privacy',
' purpose screen body text ': '[company name] and our partners use technology such as cookies on our site to personalize content and ads, provide social media features, and analyze our traffic. you can toggle on or off your consent preference based on purpose for all companies listed under each purpose to the use of this technology across the web. you can change your mind and revisit your consent choices at anytime by returning to this site.',
' purpose screen enable all button text ': 'enable all purposes',
' purpose screen vendor link text ': 'see full vendor list',
' purpose screen cancel button text ': 'cancel',
' purpose screen save and exit button text ': 'save & exit',
' vendor screen title text ': 'we value your privacy',
' vendor screen body text ': '[company name] and our partners use technology such as cookies on our site to personalize content and ads, provide social media features, and analyze our traffic. you can toggle on or off your consent preference for each company to the use of this technology across the web. you can change your mind and revisit your consent choices at anytime by returning to this site.',
' vendor screen reject all button text ': 'reject all',
' vendor screen accept all button text ': 'accept all',
' vendor screen purposes link text ': 'back to purposes',
' vendor screen cancel button text ': 'cancel',
' vendor screen save and exit button text ': 'save & exit'
});
</script>
<!-- end quantcast choice. consent manager tag -->
CSS overrides for the CMP UI
Include any CSS override code in inline <style>...</style> tags with the Quantcast Choice JavaScript source.
"Customizing the 'Privacy Settings' Button"
.qc-cmp-persistent-link {
background-color: #00ff99 !important;
color: #ffffff !important;
/*
note: both the height and max-height need to be changed
to adjust the height
*/
max-height: 50px !important;
height: 40px !important;
width: 100px !important;
padding: 10px !important;
}
“Button Color”
.qc-cmp-button,
.qc-cmp-button.qc-cmp-secondary-button:hover {
background-color: #00ff99 !important;
border-color: #00ff99 !important;
}
.qc-cmp-button:hover,
.qc-cmp-button.qc-cmp-secondary-button {
background-color: transparent !important;
border-color: #00ff99 !important;
}
“Button Font Color”
.qc-cmp-button,
.qc-cmp-button.qc-cmp-secondary-button:hover {
color: #ffffff !important;
}
.qc-cmp-button:hover,
.qc-cmp-button.qc-cmp-secondary-button {
color: #00ff99 !important;
}
“Link Color”
.qc-cmp-alt-action,
.qc-cmp-link {
color: #00ff99 !important;
}
.qc-cmp-alt-action:hover,
.qc-cmp-link:hover {
color: #021188 !important;
}
“Text Color”
.qc-cmp-main-messaging,
.qc-cmp-messaging,
.qc-cmp-sub-title,
.qc-cmp-privacy-settings-title,
.qc-cmp-purpose-list,
.qc-cmp-tab,
.qc-cmp-title,
.qc-cmp-vendor-list,
.qc-cmp-vendor-list-title {
color: #00ff99 !important;
}
“Text Font Family”
.qc-cmp-alt-action,
.qc-cmp-button,
.qc-cmp-main-messaging,
.qc-cmp-messaging,
.qc-cmp-sub-title,
.qc-cmp-link,
.qc-cmp-privacy-settings-title,
.qc-cmp-purpose-list,
.qc-cmp-tab,
.qc-cmp-title,
.qc-cmp-vendor-list {
font-family: cursive !important;
}
“Base Text Font Size”
.qc-cmp-alt-action,
.qc-cmp-button,
.qc-cmp-main-messaging,
.qc-cmp-messaging,
.qc-cmp-purpose-list,
.qc-cmp-tab,
.qc-cmp-vendor-list {
font-size: 10px !important;
}
“Tab Hover Color"
.qc-cmp-tab:hover {
background-color: #00ff99 !important;
}
“Toggle On Color”
.qc-cmp-small-toggle.qc-cmp-toggle-on,
.qc-cmp-toggle.qc-cmp-toggle-on {
background-color: #00ff00 !important;
border-color: #00ff00 !important;
}
“Toggle Off Color”
.qc-cmp-small-toggle,
.qc-cmp-toggle {
background-color: #ff0000 !important;
border-color: #ff0000 !important;
}
“Background Color”
.qc-cmp-ui {
background-color: #00ffff !important;
}
Comments
0 comments
Article is closed for comments.