Add GPP/TCF cmpapi integration to respect device access in EU/CA/US

[zapo]

In optable-web-sdk we currently defer the responsibility of detecting regulations and handling consent to the user which usually results in gating the load of the SDK which is not ideal.

In this PR we propose to detect regulation that should apply and integrate directly with CMP APIs (namely TCF and GPP) to gather visitor consent. Based on the detected regulation and consent, device access may be granted.

To do so, this PR introduces a new "consent" config property holding either a static consent object passed by the user, or automatically inferred:

 type Consent = { 
  // Whether localStorage read/writes are granted
  deviceAccess: boolean; 
  
  // Regulation that applies
  reg: "us" | "can" | "gdpr" | null;
  
  // GPP string when applicable
  gpp?: string;
  
  // TCF string when applicable
  tcf?: string;
  
  // GPP section IDs when applicable
  gppSectionIDs?: number[];
 }

This also updates the config object passed to instanciate the SDK to accept an optional consent retrieval configuration:

{
  // A "static" consent object already built by the publisher
  static?: Consent;
  // A "cmpapi" configuration indicating that consent should be gathered from CMP apis.
  cmpapi?: { 
    // An optional vendor ID from global vendor list when interpretting TCF/GPP EU consent,
    // when not passed, defaults to publisher consent.
    tcfeuVendorID?: string;
  }
}

• Passing directly the static consent object allows the user to control device access and passing consent strings to the DCN based on their own integration with CMPs.
• Passing "cmpapi" let the SDK automatically detect the regulation that should apply and infer device access based on the preferred CMP API for this regulation.

When absent, consent is granted for device access to preserve existing behavior. Eventually this may be changed to "cmpapi". Users should start passing consent: { static: { deviceAccess: true, reg: null } } if they want to preserve the existing behavior.

Regulation Detection & device access

Regulation detection is currently implemented by looking up the timezone of the device and the languages supported.
When no regulation is detected, device access is automatically granted.

regulation	cmp api	detection	device access
TCF CA V1 ("can")	gpp	QC timezone and french browser language	always granted
TCF EU V2 ("gdpr")	tcfapi if available, otherwise gpp	EU country timezone	purpose 1 pub or vendor consent (when tcfeuVendorID is passed) when gdpr applies
US ("us")	gpp (usnat + states)	US time zone	always granted

Signals passing to the DCN

Additionally to gating device access, the regulation and corresponding consent strings are passed to any DCN call as query strings as soon as they are available and set. This allows the DCN to degrade behavior based on applicable regulation, consent vs those APIs purpose

[patmmccann]

this is incorrect, one cannot have LI on purpose 1.
You could check: ((data.purpose.consents and a vendor id you take as config) or data.publisher.consents["1"])

Going to a friendly site, https://highfivve.com/en/from-publisher-to-publisher/, and typing

__tcfapi('addEventListener', 2, function(tcData, success) { console.log('cmp responded:', tcData, success);});

your check fails bc no publisher purposes are defined and you aren't checking data.purpose at all. To check vendors, you could look at data.vendor.consents, customVendorConsents, and/or googleVendorConsents. I recommend optable register for the Google vendor list.

[zapo]

Thanks, I'll remove LI purpose 1 check.
As for checking vendor consent it's a good idea and I'll go ahead with checking vendor.consents alongside purpose.consents if a vendor ID is provided.

For customVendorConsents and googleVendorConsents properties I'm having trouble finding where they come from, I don't see it documented in https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#tcdata . Is it possible it's a consentmanager.net only thing? The only ref I found is https://help.consentmanager.net/books/cmp/page/changes-to-the-iab-cmp-framework-js-api

[patmmccann]

It is documented here

https://support.google.com/admanager/answer/9681920?hl=en

[patmmccann]

Might have to parse the ac string to get the additional consented vendor list. I do suggest Optable register for this list, then you could just check for consent to yourself