extensions/amp-consent/integrating-consent.md
To enable customers to operate a CMP to manage their user consents in AMPHTML pages, Consent Management Providers should integrate their service in amp-consent.
To add your consent management service to AMP runtime, it is expected that you:
width: 100vw, height: 30vh), and the full screen size (width: 100vw, height: 100%) after user interactions.<amp-consent type='yourName'></amp-consent> on the page won't block any components by default. Please make sure to inform your service users to block AMP components either by the <meta name="amp-consent-blocking"> metaTag, or the data-block-on-consent attribute._ping_ CMP service implementation that the AMP team creates for testing purpose.A remote endpoint is expected to tell the AMP runtime whether the user consent is required. It can also pass extra information via AMP to third party vendors. More information on the remote endpoint can be found here.
The AMP runtime will embed the CMP's prompt in an iframe. amp-consent will create the iframe when it is necessary. A default placeholder will be displayed, and the prompt iframe will remain hidden until it has finished loading.
In case you need to enable additional sandbox restrictions to be removeed for the generated iframe, specify them in the sandbox configuration variable. It takes a string with space-seperated sandbox restrictions. The restrictions allow-scripts and allow-popups are removed by default. Right now, the only allowed additional sandbox restrictions are allow-popups-to-escape-sandbox and allow-top-navigation-by-user-activation.
The prompt iframe and the parent AMP page will communicate through postMessages and the iframe name attribute. In the case of using postMessage, messages from nested iframes will be ignored. The lists of support APIs are:
Iframes can send a consent-ui message to the parent AMP page to request UI state change.
window.parent.postMessage(
{
type: 'consent-ui',
action: 'ready',
initialHeight: (optional string, default `30vh`),
enableBorder: (optional boolean, default true),
},
'*'
);
Action 'ready' informs the AMP runtime to hide the placeholder and show the consent prompt instead.
The initialHeight property is used to set the size of consent prompt. Valid values are 30vh to 80vh. A valid value below 60vh (inclusive) will result in amp-consent rendering the consent dialog as a bottom sheet, and a valid value above 60vh will style the consent prompt as a modal.
The enableBorder property determines if the top corners of the consent prompt will be rounded for consent prompts that have an initialHeight less than or equal to 60vh.
window.parent.postMessage(
{
type: 'consent-ui',
action: 'enter-fullscreen',
},
'*'
);
Action 'enter-fullscreen' requests the AMP runtime to expand the iframe to fullscreen. amp-consent will only allow the iframe enter fullscreen if it detects user interaction with the iframe (e.g. clicking on the iframe). Once the request is received, amp-consent will send a message (via postMessage()) to the iframe to inform the success of the request:
{
type: 'amp-consent-response',
requestType: 'consent-ui',
requestAction: 'enter-fullscreen',
state: 'success',
info: 'Entering fullscreen.'
}
Iframes can send a consent-response message to the parent AMP page to inform the user actions along with additional consent information.
accept or reject. AMP will strictly respect the incoming info value. If the info value is undefined, any previously value will be discarded.window.parent.postMessage(
{
type: 'consent-response',
action: 'accept',
info: /string/ /* optional */,
consentMetadata: /object/ /* optional */,
tcfPolicyVersion: /number/ /* optional (integer) - if not provided 2 is default */,
},
'*'
);
The user action accept informs AMP runtime to unblock all components that are waiting the user consent.
window.parent.postMessage(
{
type: 'consent-response',
action: 'reject',
info: /string/ /* optional */,
consentMetadata: /object/ /* optional */,
tcfPolicyVersion: /number/ /* optional (integer) - if not provided 2 is default */,
},
'*'
);
The user action reject informs AMP runtime that the user has declined to give consent. AMP runtime will unblock components based on the consent blocking policy configuration.
window.parent.postMessage(
{
type: 'consent-response',
action: 'dismiss',
},
'*'
);
The user action dismiss informs AMP runtime that no info on user consent has been gathered. The info value is not supported. This is because the info string is not useful when the user decides to not give any information.
When the iframe is created, the following information will be passed to the iframe via the name attribute.
clientConfig: The configuration from the publisherconsentStateValue: The stored consent state if there's any. The value will be 'accepted'/'rejected'/'unknown'. A friendly reminder is to be aware of the difference between the consent state string value ('accepted'/'rejected'/'unknown') and the user action string value ('accept'/'reject'/'dismiss').consentString: The stored consent info string if there's any.One can get access to the client information via the name attribute inside the iframe.
/* Expect info to be an object of format
* {
* 'clientConfig': *,
* 'consentStateValue': 'accepted'/'rejected'/'unknown'/undefined,
* 'consentString': string/undefined,
* };
*/
info = JSON.parse(window.name);
<amp-consent> caches and passes consent information to vendors via consentMetadata objects as well as a non-empty consentString. You can find and example of the consentMetadata object and its supported fields below.
{
"consentStringType": {enum} [1: TCF V1, 2: TCF V2, 3: US Privacy String] (optional),
"gdprApplies": {boolean} (optional),
"additionalConsent": {string} (optional),
"purposeOne": {boolean} (optional),
"gppSectionId": {string} (optional)
}
Once you have the remote endpoint and prompt UI iframe ready, you are ready to add your configuration to the AMP runtime.
consentInstanceId: The localStorage key to store/retrieve the user consent response.checkConsentHref: Your remote endpoint destination.promptUISrc: Your prompt UI iframe src.cmp-vendors.amp.html using your service. Note, the examples and filters should be in alphabetical order, and _ping_ should be the first example.extensions/amp-consent/cmp. See the _ping_ documentation as an example.extensions/amp-consent/amp-consent.md.