Overview
This document provides you with the information of Quantcast’s CMP AMP integration (supporting the TCFv2 framework). This CMP AMP integration is only supported for Choice CMP v2 update 20 or newer (the tag will ensure that the correct version will be loaded).
This document assumes that you are familiar with web development and with the AMP framework.
Introduction
Quantcast Choice CMP (the CMP) is using the amp-consent component to support our CMP on fully powered AMP sites and we are following the standard AMP implementation guidelines. Thus as a developer integrating with our CMP on your AMP page, you can follow the familiar integration steps for AMP.
The Quantcast Choice CMP amp-consent config will be registered as <amp-consent id="quantcast" type=”quantcast”>. The CMP UX is rendered within an iFrame and it is communicating with the AMP site using postMessage. The CMP communicates both UI state changes and User consent response to the parent site.
ClientConfig
The AMP parent site exposes the same object that it does for the API request via window.name to the CMP. It also supports another key called clientConfig that contains all the publisher given configuration used by the CMP.
UI Configuration Limitations
- CMP always use the summary page (bottom tray) as the first screen
- We currently don’t support custom CSS. Basic styling can be done through the Customize UI feature within our portal.
Other Limitations
- When users consent/reject, the CMP iframe needs to send a consent-response message back to the parent AMP site. In this message, the consent is going to be sent as either an accept or reject action, partial consent is treated as an accept action. The consent string will contain the actual TCF compatible consent (see next item).
- The TCString is generated and passed into the AMP components but support of the string itself depends on IAB vendors and their amp-ad implementation. A vendor can get the full TCString (using your amp-ad implementation). The string cannot be accessed directly on your AMP site.
- TCString is only available for amp-ad and amp-iframe components as of now. This will be a limitation for publishers that need to read the TCString from other components or from their site. The AMP group intends to implement issue #30385 where they are going to expose the __tcfapi creating a proxy between amp-consent and the TCF postMessage API. Once available we will add that support in our CMP.
- consentMetadata is NOT currently exposed to amp-ad, therefore vendors cannot read it even though we’re setting it. The AMP group tracks this issue as #30786.
- Non-IAB Vendors consent is NOT AVAILABLE as of now.
- IE11 is not supported. There are several open issues in the AMP repo on this.
- Two separate site configurations are required for mixed AMP / non-AMP sites (see below).
- We don’t support WordPress and AMP together yet either.
- There is a 1200 character size limit for the consentMetadata key. When you use the Google additionalConsent string, which is stored in the consentMetadata key that limit will be overrun and the consent info will be ignored. We therefore recommend to not enable the Google additional vendors feature on AMP enabled pages. (There is an open issue against the AMP project to increase the consent storage size.)
Integrating our CMP within your AMP page
CMP Tag & Config
Your implementation will look something like this. You start in our Choice portal by configuring your site as an AMP powered web page under the general setting in the create/edit a site page. If you want to configure a site-domain to work as a regular web site and as an AMP powered site, you need to create another site adding a path to the URL, for example: my-site.com (regular website) and my-site.com/amp (amp powered site).
After you configure your AMP supported web page in our Choice Configuration Portal, you can download the AMP tag (see image 1 example) from within the portal by using the Get AMP Tag on the menu of your site entry in the properties list.
That menu item will launch the get AMP tag modal where you can copy the complete AMP tag (AMP code and Choice clientConfig) that you can copy at the top of your <body> section of your web page code.
<div id="container">
<!-- 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": true,
"lang_": "en",
"displayUi": "always",
"publisherConsentRestrictionIds": [],
"publisherLIRestrictionIds": [],
"publisherPurposeIds": [],
"publisherPurposeLegitimateInterestIds": [],
"publisherSpecialPurposesIds": [],
"publisherFeaturesIds": [],
"publisherSpecialFeaturesIds": [],
"stacks": [1, 42],
"vendorListUpdateFreq": 30
}
}
}
</script>
</amp-consent>
<!--END QUANTCAST CMP -->
</div>
Image 1: basic sample tag GDPR w/o Persistent Consent Link
Once you copied the tag into your web page code, you will also need to include the amp-consent and amp-geo scripts in the header of your page for it to properly work:
<script async custom-element="amp-consent" src="https://cdn.ampproject.org/v0/amp-consent-0.1.js"></script>
Note: Please make sure there is only one instance of <amp-geo> or <amp-consent> present on the page.
Persistent consent link
To add a persistent consent link, you need to add the following code to your amp-consent tag we created above. (Using the Choice portal you can specify whether you want to include the persistent link in your tag):
<amp-consent id="quantcast" layout="nodisplay">
<script type="application/json">
{
"postPromptUI": "postPromptUI", // add this line
Image 2: add “postPromptUI”: “postPromptUI”, to your amp-consent 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 3: 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 4: sample persistent choice button style definition
Now that we explained how to integrate the TCF tag for GDPR we are going to explain how to do this for CCPA next.
-
CCPA Implementation
Amp Geo
For CCPA support, publishers need to implement an amp-geo component on their page that will look like this:
<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 5: sample amp-geo implementation
The amp-geo component provides country-level geolocation. As every other component in AMP, publishers also need to add a separate script to the head of the page:
<script async custom-element="amp-geo" src="https://cdn.ampproject.org/v0/amp-geo-0.1.js"></script>
Note: Please make sure there is only one instance of <amp-geo> or <amp-consent> present on the page.
Amp Consent Tag
If you’re using CCPA, we’re adding a new key to our amp-consent tag called geoOverride
<!-- 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": false,
"geoOverride": {
"usca": {
"consentRequired": "remote",
"promptUISrc": "https://quantcast.mgr.consensu.org/tcfv2/amp.html?usp"
}
},
"clientConfig": {
"premiumProperties": {},
"coreUiLabels": {},
"premiumUiLabels": {},
"coreConfig": {
"quantcastAccountId": "quantcastAccountId",
"privacyMode": ["USP"],
"publisherCountryCode": "US",
"publisherName": "TestMeOut",
"uspVersion": 1,
"uspJurisdiction": ["CA"],
"uspLspact": "N"
}
}
}
</script>
</amp-consent>
<!-- QUANTCAST CMP END -->
Image 6: sample CCPA tag, enabled for California only
In this example, what will happen is that if you’re on any of the defined geoOverride regions (those keys need to be the same as defined in the amp-geo component), the promptUISrc will now use an USP flag, making the CMP load in USP mode. If you’re not in a matched region, no param will be added so you will use the GDPR CMP by default.
If a user wishes to target the entire US, they should use the “us” key to do the override. If the user only wants to target California, then the “usca” key is the one to use.
Since AMP provides an amp-geo component, the CMP will not use our internal geo-location API. When we render the iframe, we assume that the user has been successfully geolocated by the amp-geo component.
This allows the AMP CMP to have a faster performance by only initializing what's needed for each regulation, and by having less HTTP calls.
UspString is stored by the amp-consent, so cannot be accessed directly. Whether the consent is provided or not, is shared by AMP to the blocking tags.
Adding the disclaimer prompt link:
<!-- 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 -->
In this example we are adding to the disclaimer an <a> element which will prompt the CMP by clicking it.
How it works
Once the API endpoint determines that the user needs to be asked for consent, the CMP will set the default USP value (as the regular web CMP does) and no UI will be shown. Then, if the user clicks on the Privacy Settings button, the CCPA popup will be displayed and users can change their consent.
GDPR only inEU
Amp Geo
For GDPR only inEU implementation, publishers also need to implement an amp-geo component on their page that will look like this:
<amp-geo layout="nodisplay">
<script type="application/json">
{
"ISOCountryGroups": {
"eea": ["preset-eea", "unknown"]
}
}
</script>
</amp-geo>
Image 7: sample amp-geo code to validate inEU
The amp-geo component provides country-level geolocation. As every other component in AMP, publishers also need to add a separate script to the head of the page:
<script async custom-element="amp-geo" src="https://cdn.ampproject.org/v0/amp-geo-0.1.js"></script>
Amp Consent Tag
<!-- 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": false,
"geoOverride": {
"eea": {
"consentRequired": "remote",
"promptUISrc": "https://quantcast.mgr.consensu.org/tcfv2/amp.html"
}
},
"clientConfig": {
"coreUiLabels": {},
"theme": {},
"coreConfig": {
"quantcastAccountId": "quantcastAccountId",
"privacyMode": ["GDPR"],
"hashCode": "xxxxxxxxxxxxxxxxxxx",
"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": true,
"lang_": "en",
"displayUi": "inEU",
"publisherConsentRestrictionIds": [],
"publisherLIRestrictionIds": [],
"publisherPurposeIds": [],
"publisherPurposeLegitimateInterestIds": [],
"publisherSpecialPurposesIds": [],
"publisherFeaturesIds": [],
"publisherSpecialFeaturesIds": [],
"stacks": [1, 42],
"vendorListUpdateFreq": 30
}
}
}
</script>
</amp-consent>
<!-- QUANTCAST CMP END -->
Image 8: sample AMP tag with geoOverride
Note: Get AMP Tag generates the full tag for all the combinations for GDPR and CCPA. Publishers can combine the geoOverrides for both USP and GDPR modes if they want to support GDPR only inEU, and CCPA in the US or California.
Now that we talked you through all the different tags we will address how blocking ads is working using the consent given by the user.
Blocking behaviors
Basic blocking
The <amp-consent> element can be used to block any other AMP components on the page from loading (except <amp-consent> itself).
The basic usage is either add a data-block-on-consent attribute to every amp component that you want to block until consent. Alternatively, you can add an amp-consent-blocking meta tag specifying every component you wish to block until consent, like this:
<meta name="amp-consent-blocking" content="amp-analytics,amp-ad" />
Advanced blocking
The data-block-on-consent attribute works as block-until accept by default, but you can change it. It has three possible values:
_till_accepted (Default. it will unblock the component when consent is received)
_till_responded (it will unblock the component when any response is received)
_auto_reject (it will auto-reject the consent whenever the consent is required but unknown. This reject will not be stored)
Custom blocking
An optional policy object can be added to the <amp-consent> element's JSON configuration object to customize consent blocking behaviors.
Example:
<amp-consent layout="nodisplay" id="consent-element">
<script type="application/json">
{
"clientConfig": {...},
"policy": {
"default": {
"timeout": {
"seconds": 5,
"fallbackAction": "reject"
}
}
}
}
</script>
</amp-consent>
Image 9
In this example, AMP will wait for 5 seconds to get any consent response, if none is given it will reject it as a fallback.
Right now only customizing the default policy instance is supported. The "default" behavior policy applies to every component that is blocked by consent with data-block-on-consent attribute.
You can find more information on this in the amp.dev documentation.
Getting the TC String
RTC Vendors
There’s a list of vendors that support real-time configurations. If you’re using <amp-ad> and your vendor supports RTC, 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.
Also, whatever we expose through our API in the sharedData object will be stored under window.context.consentSharedData.
Currently, there’s no other way of getting the TCString other than in amp-ad or amp-iframe components. Publishers don’t have access to it on their site. The AMP group tracks this issue here #30385. We will expand this in the future.
Getting the Google string
The additional Google consent string is available for vendors using <amp-ad> under window.context.intialConsentMetadata.additionalConsent.
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.