Amphtml: I2I: Allow receiving TCF 2.0 consent string via TCF postmessage API

[klipstein]

Summary

Currently only <amp-ad> and <amp-iframe> have the capability to receive the TC-String, which could be gathered via <amp-consent>. We would like to enable more components to receive the TC-String by implementing a proxy between <amp-consent> and the TCF 2.0 postmessage API.

This idea was already mentioned by @renebaudisch in this thread and we would like to propose and discuss a potential solution that implements a minimal TCF 2.0 API.

All consumers that rely on TCF 2.0 already have TCF 2.0 reading implemented and this feature would prevent that those consumers need to adjust their code.

Other use-cases where the consent-string cannot be queried at the moment:

• When an ad gets delivered via <amp-ad> and where the ad is delivered via safeframe
• Standardize receiving the consent-string for prebid integrations: https://github.com/prebid/prebid-universal-creative/issues/114

Design Document

We would like to extend <amp-consent> so that a publisher can expose his AMP CMP via the TCF postmessage API as such:

Option A

~~~html
exposes="tcfapi"
...

~~~

Option B

~html


~

With assigning multiple values to exposes, it would be possible to extend this feature to support further consent APIs (e.g. uspapi). Alternative names to exposes would be installs, or provides.

When a publisher exposes his CMP as tcfapi the following happens:

1. Installs a new window frame with the name __tcfapiLocator next to the top window, which indicates to a foreign iframe that a TCF 2.0 API is available. A foreign iframe can query for the existence of a TCF API by testing for window.top.frames.__tcfapiLocator.
2. Within the top window we then would install listeners for the getTCData, addEventListener removeEventListener and ping window messages as specced here and here
3. When a TCF API request is received in one of those listeners, call the AMP consent APIs in order to gather consent information, which were stored within AMP (The used AMP APIs will be: getConsentMetadata, getConsentPolicyState, getConsentPolicyInfo and getConsentPolicySharedData) and use that stored data to answer with a minimal TCData response.

Because not all necessary data of a TCF 2.0 compliant CMP is stored within AMP, it is not possible to construct a completely filled TCData object. The most important information within the TCData object is the tcString and a lot of information within the TCData object is just expanded information that is encoded within the tcString. Because of that we propose a minimal TCData object that looks like this:

~~~js
const metadata = await getConsentMetadata();
const policyState = await getConsentPolicyState();
const policyInfo = await getConsentPolicyInfo();
const sharedData = await getConsentPolicySharedData();

const tcData = {
// mixing in additionalConsent and sharedData from a CMP
additionalConsent: metadata.additionalConsent,
...sharedData,
consentStringType: metadata.consentStringType, // TCF-Version
gdprApplies: metadata.gdprApplies,
tcString: policyInfo,
// will be defined when "addEventListener" is used
listenerId: undefined,
// this can be defaultet to "loaded" when e.g. getConsentMetadata answered
cmpStatus: 'loaded',
// same as above, when we receive an answer, we can assume that everything is ready
eventStatus: 'tcloaded'
};
~~~

Motivation

We've implemented the consent-reading support for amp-iframe and we now wanted to provide the same functionality for <amp-video-iframe>. Because other components (e.g. other video player components) will also have the requirement to follow the TCF 2.0 standard we want to offer a more generic way to distribute it and we think that the TCF 2.0 postmessage specification solves this problem already.

Alternative solution would be, that all AMP components, that require TCF 2.0 consent reading would have to implement it.

/cc @ampproject/wg-approvers
/cc @zhouyx, @jridgewell, @alanorozco (because you reviewed https://github.com/ampproject/amphtml/pull/29636)

[klipstein]

@zhouyx, @jridgewell, @alanorozco what can we do to move this forward?

[jridgewell]

It needs to be brought do a design review, with @ampproject/wg-monetization in attendance. /cc @zhouyx

[micajuine-ho]

Hi @klipstein, thank you for your proposal. I have written up a design doc for this work, and I would love some feedback from the community before I take it to design review.

Thanks!

[klipstein]

@micajuine-ho thanks for writing the detailed design doc. Maybe you could express better that the postmessage listeners need to be installed on the frame that contains the __tcfapiLocator frame (which mostly will be the top window). But other than that it looks good to me.

[micajuine-ho]

I'll track the work done for this project here:

• [ ] Add exposes API to amp-consent
• [ ] Install the __tcfApiLocator window
• [ ] Allow PostMessages for the ping, getTcData, addEventListener, and removeEventListener commands
• [ ] Create the ping API (along with the MinimalPing object)
• [ ] Create the getTcData API (along with the MinimalTCData object)
• [ ] Create the addEventListener API
• [ ] Create the removeEventListener API
• [ ] Tests/Documentation

/cc @zhouyx

[renebaudisch]

Is there anything the crowd can help to push this forward?

[micajuine-ho]

Got positive feedback from the design review today, will look to move forward with these PRs