Overview
This document provides instructions for integrating the Quantcast Choice CMP (Consent Management Platform) into your AMP pages. Quantcast Choice supports IAB's TCFv2 and USP frameworks for collecting user consent and do-not-sell choices. This document assumes that you are familiar with web development and with the AMP framework.
The Quantcast Choice CMP uses the <amp-consent> component to implement our CMP on AMP-powered sites following the standard AMP implementation guidelines.
The Quantcast Choice CMP is included using an <amp-consent id="quantcast"> component, and configured via a child <script type="application/json"> JSON block. When consent is required from the user, the CMP UI is shown in an iframe. The loading or display of other AMP components such as <amp-ad> can be blocked until consent is given.
Integrating the Choice CMP in your AMP page
Requirements
The AMP integration is only supported for Choice CMP version 20 or later.
The amp-consent (and amp-geo, if used) scripts must be included in the <head> of your AMP page for the Choice CMP to properly function:
<script async custom-element="amp-consent" src="https://cdn.ampproject.org/v0/amp-consent-0.1.js"></script>
<script async custom-element="amp-geo" src="https://cdn.ampproject.org/v0/amp-geo-0.1.js"></script>
There must be only one instance of <amp-geo> and <amp-consent> present on the page.
Configuring the Choice AMP Tag
Start on our Quantcast Choice portal by configuring your site as an "AMP Site" under the "General settings" in the "Create/edit a site page".
To configure a site that has both regular HTML and AMP pages, you need to create two sites in the portal, with the "AMP site" formed by adding an "/amp" path to the URL. For example: my-site.com (regular website) and my-site.com/amp (AMP-powered site).
After you configure your AMP site in our Choice Configuration Portal, you can get the AMP tag by using the "Get AMP Tag" on the "More Options" menu of your site entry in the properties list:
That will display "Your Choice AMP Tag" modal from where you can copy the complete AMP tag (<amp-consent> tag, including the configuration JSON, and the <amp-geo> configuration, if applicable) that you can paste at the top of your <body> section of your AMP page.
Note that the entire configuration for the CMP is contained within this tag: if you update the configuration, you will need to update the tag on the AMP page. Note: Future versions of the CMP will support portal based configuration of AMP pages, eliminating this copy-paste operation.
<!-- QUANTCAST CMP -->
<amp-consent id="quantcast" layout="nodisplay">
<script type="application/json">
{
"consentInstanceId": "quantcast",
"checkConsentHref": "https://apis.quantcast.mgr.consensu.org/amp/check-consent",
"consentRequired": "remote",
"promptUISrc": "https://quantcast.mgr.consensu.org/tcfv2/amp.html",
"clientConfig": {
"coreConfig": {
"quantcastAccountId": "quantcastAccountId",
"privacyMode": ["GDPR"],
"hashCode": "3BDXDqoakCk4Q4LzQqBGVQ",
"publisherCountryCode": "US",
"publisherName": "TestMeOut",
"vendorPurposeIds": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"vendorFeaturesIds": [1, 2, 3],
"vendorPurposeLegitimateInterestIds": [2, 3, 4, 5, 6, 7, 8, 9, 10],
"vendorSpecialFeaturesIds": [1, 2],
"vendorSpecialPurposesIds": [1, 2],
"googleEnabled": false,
"lang_": "en",
"displayUi": "always",
"publisherConsentRestrictionIds": [],
"publisherLIRestrictionIds": [],
"publisherPurposeIds": [],
"publisherPurposeLegitimateInterestIds": [],
"publisherSpecialPurposesIds": [],
"publisherFeaturesIds": [],
"publisherSpecialFeaturesIds": [],
"stacks": [1, 42],
"vendorListUpdateFreq": 30
}
}
}
</script>
</amp-consent>
<!--END QUANTCAST CMP -->
image 1: basic sample tag for GDPR
Persistent consent link for GDPR
When the GDPR persistent consent link is selected, a "postPromptUI": "postPromptUI" key is included in the JSON configuration and a persistent consent link <div> and styling is included in the tag:
<!-- PRIVACY BUTTON LOWER RIGHT -->
<div id="postPromptUI">
<button role="button" on="tap:quantcast.prompt()">
<svg style="height:20px">
<g fill="none">
<g fill="#FFF">
<path
d="M16 10L15 9C15 9 15 8 15 8L16 7C16 7 16 6 16 6 16
5 15 4 14 3 14 2 13 2 13 3L12 3C12 3 11 3 11 2L11 1C11 1 10 0 10 0 9 0 7 0 6 0 6 0
5 1 5 1L5 2C5 3 4 3 4 3L3 3C3 2 2 2 2 3 1 4 0 5 0 6 0 6 0 7 0 7L1 8C1 8 1 9 1 9L0
10C0 10 0 11 0 11 0 12 1 13 2 14 2 15 3 15 3 14L4 14C4 14 5 14 5 15L5 16C5 16 6 17
6 17 7 17 9 17 10 17 10 17 11 16 11 16L11 15C11 14 12 14 12 14L13 14C13 15 14 15 14
14 15 13 16 12 16 11 16 11 16 10 16 10ZM13 13L12 13C11 13 11 13 9 14L9 16C9 16 7 16 7
16L7 14C5 14 5 13 4 13L3 13C2 13 1 12 1 11L3 10C2 9 2 8 3 7L1 6C1 5 2 4 3 4L4 4C5 4 5
3 7 3L7 1C7 1 9 1 9 1L9 3C11 3 11 4 12 4L13 4C14 4 15 5 15 6L13 7C14 8 14 9 13 10L15
11C15 12 14 13 13 13ZM8 5C6 5 5 7 5 9 5 10 6 12 8 12 10 12 11 10 11 9 11 7 10 5 8 5ZM8
11C7 11 6 10 6 9 6 7 7 6 8 6 9 6 10 7 10 9 10 10 9 11 8 11Z" />
</g>
</g>
</svg>
PRIVACY
</button>
</div>
Image 2: persistent consent button implementation
To change persistent consent styling you should target #postPromptUi button in your CSS. This example adds the persistent consent button to the lower right of your page:
#postPromptUI button {
background: #368bd6;
color: white;
padding: 5px 15px;
border: none;
outline: none;
display: flex;
align-items: center;
position: fixed;
right: 0;
bottom: 0;
border-radius: 3px 0 0 3px;
max-height: 30px;
max-width: 110px;
cursor: pointer;
}
Image 3: sample persistent choice button style definition
geo-location for CCPA or GDPR in EEA
An <amp-geo> block will be included in the Choice AMP Tag if you configure GDPR (TCFv2) consent collection to apply only to users in the EEA (European Economic Area) only, or if you have CCPA configured. Additionally, a geoOverride key will be present in the JSON configuration to properly customize the CMP based on the user's location.
For these cases, an <amp-geo> component is included that defines the region(s) where CCPA and/or GDPR are applicable:
<amp-geo layout="nodisplay">
<script type="application/json">
{
"ISOCountryGroups": {
"usca": ["preset-us-ca"] // target California only
// "us": ["us"] // target entire US
}
}
</script>
</amp-geo>
image 4: sample amp-geo implementation
The amp-geo component provides country-level geolocation.
Since AMP provides geo-location, the Choice CMP will not use its internal geo-location functionality. The CMP will assume that the user has been successfully geo-located by the amp-geo component.
This improves the AMP CMP performance by avoiding the check-consent HTTP call in areas where the it is not necessary.
CCPA (USP) functionality
The check-consent API endpoint determines that CCPA applies for users geo-located to California (or the US). If no previously-given USP string (indicating the user's Do-Not-Sell choice) has been set, the CMP will set the default USP string (as the regular web CMP does) and trigger the accept consentState. The CCPA UI will not be shown automatically (as it does when GDPR applies), but instead, the user must click on the Do Not Sell link included on-page in order to make a do-not-sell choice. If the user chooses "Do Not Sell My Information" in the UI, the consentState will be set to reject.
A link to bring up the CCPA UI needs to be included:
<!-- Privacy Disclaimer -->
<p id="disclaimer_example">
We use cookies and other data collection technologies to provide the best
experience for our customers.
You may request that your data not be shared with third parties here:
<a role=“"button”" on=“"tap:quantcast.prompt()“">
Do Not Sell My Personal Information
</a>.
</p>
<!-- Privacy Disclaimer -->
If desired, this link be hidden when CCPA is not applicable using the amp-geo-group-XX class which is automatically set by <amp-geo> as documented here.
AMP Blocking behaviors
AMP components can block their loading until consent is accepted, until any consent choice is made (if required), or if consent is required but unknown. In addition, a timeout with fallback behaviors can be configured. For more information, see this AMP documentation.
The following table indicates what Choice sends for consent required and the consent states, based on Choice configuration, location, and user behavior
Getting the TCF Consent String
RTC Vendors
Certain ad vendors support real-time configurations. If you’re using <amp-ad> and your vendor is one of these listed vendors, you can use the CONSENT_STRING and CONSENT_STATE macros to add that information to the request URL. Relevant information on how to do that here.
Non-RTC Vendor
If your vendor needs access to the consent string but doesn’t support real-time configurations, you can check the window.context.initialConsentValue key which stores the full TCString, or check the window.context.initialConsentState which stores the AMP consent state value (either 1 or 0) within your JavaScript code.
Basic Blocking behavior example
To block components, either add the data-block-on-consent attribute to the AMP component or add the amp-consent-blocking meta tag with the list of extensions to be blocked. For more details please refer to the AMP documentation.
Example: Blocking the analytics until user accepts consent
<amp-analytics data-block-on-consent type="googleanalytics"> </amp-analytics>
or
<meta name="amp-consent-blocking" content="amp-analytics,amp-ad" />
Using the Quantcast Measure Tag with AMP consent
Quantcast Measure Tag
Pages optimized with AMP HTML can be fully tracked in your existing Quantcast account by adding the appropriate amp-analytics tag into the body of your pages, near the top of the “body” tag:
<amp-analytics data-block-on-consent type="quantcast">
<script type="application/json">
{
"vars": {
"pcode": "YOUR account id/pcode GOES HERE",
"labels": ["AMPProject","optionalAdditionalLabelsHere" ]
}
}
</script>
</amp-analytics>
Note: Please ensure you set the pcode variable above to the appropriate value for your account id. The AMPProject label is required. Other labels are optional but recommended – see below.
For more information please refer to Implementing Quantcast Measure on AMP Project Pages.
Caveats / Limitations
- AMP Consent Framework
- When users consent or reject, the consentState is sent as either accept or reject (dismiss is not used by Choice). Choice treats partial consent as an accept action. The consentString contains the TCF consent string.
- The TCString is passed to AMP as consentString but support of the string itself depends on the vendor's <amp-ad> implementation.
- TCString is currently available only to amp-ad and amp-iframe components. AMP Project issue #30385 details an in-development feature to expose the postMessage API of TCFv2 to other components in AMP, which we intend to support when released.
- consentMetadata is NOT currently exposed to amp-ad, therefore vendors cannot read it even though we’re setting it. This limitation is tracked as issue #30786.
- IE11 is not supported. There are several open issues in the AMP project on this.
- UI Configuration
- Choice AMP configuration limitations
- General
- Choice AMP does not yet support WordPress.
- Feature limitations
- Non-IAB Vendors consent are not available in Choice AMP.
- Group-level or global-scope consent storage is not supported. We use the built-in AMP consent-string storage mechanism which is always site-local.
- The Google additional vendors feature is not supported for Choice AMP, and should be disabled. This is due to a 1200 character size limit (open issue) for consent storage for Google-cached AMP pages. As the consentMetadata.additionalConsent key will exceed this storage limit, this prevents consent info from being stored, and will cause consent reprompts on each page load. Google Ads can still use the TCF string and can still show personalized ads (when consent is given) even with this feature disabled.
- UI
- The Choice AMP UI always uses the summary page (displayed in the "bottom tray" position) as the first screen.
- Choice AMP does not support configuring custom CSS for AMP through the portal. Basic CMP styling can be done through the Customize UI feature within our portal, and other styling can be done through <style> CSS on the AMP page.