add support for TCF2 (prebid#4911)

* initial support for TCF2

* update wording in err message

* update logic and comment around safeframe workflow

* fix typo

Author: jsnellbaker

modules/consentManagement.js

@@ -19,6 +19,7 @@ export let consentTimeout;
 export let allowAuction;
 export let staticConsentData;
 
+let cmpVersion = 0;
 let consentData;
 let addedConsentHook = false;
 
@@ -47,11 +48,70 @@ function lookupStaticConsentData(cmpSuccess, cmpError, hookConfig) {
  * @param {object} hookConfig contains module related variables (see comment in requestBidsHook function)
  */
 function lookupIabConsent(cmpSuccess, cmpError, hookConfig) {
-  function handleCmpResponseCallbacks() {
+  function findCMP() {
+    let f = window;
+    let cmpFrame;
+    let cmpFunction;
+    while (!cmpFrame) {
+      try {
+        if (typeof f.__tcfapi === 'function' || typeof f.__cmp === 'function') {
+          if (typeof f.__tcfapi === 'function') {
+            cmpVersion = 2;
+            cmpFunction = f.__tcfapi;
+          } else {
+            cmpVersion = 1;
+            cmpFunction = f.__cmp;
+          }
+          cmpFrame = f;
+          break;
+        }
+      } catch (e) { }
+
+      // need separate try/catch blocks due to the exception errors thrown when trying to check for a frame that doesn't exist in 3rd party env
+      try {
+        if (f.frames['__tcfapiLocator']) {
+          cmpVersion = 2;
+          cmpFrame = f;
+          break;
+        }
+      } catch (e) { }
+
+      try {
+        if (f.frames['__cmpLocator']) {
+          cmpVersion = 1;
+          cmpFrame = f;
+          break;
+        }
+      } catch (e) { }
+
+      if (f === window.top) break;
+      f = f.parent;
+    }
+    return {
+      cmpFrame,
+      cmpFunction
+    };
+  }
+
+  function v2CmpResponseCallback(tcfData, success) {
+    utils.logInfo('Received a response from CMP', tcfData);
+    if (success) {
+      if (tcfData.eventStatus === 'tcloaded' || tcfData.eventStatus === 'useractioncomplete') {
+        cmpSuccess(tcfData, hookConfig);
+      } else if (tcfData.eventStatus === 'cmpuishown' && tcfData.tcString.length > 0 && tcfData.purposeOneTreatment === true) {
+        cmpSuccess(tcfData, hookConfig);
+      }
+    } else {
+      cmpError('CMP unable to register callback function.  Please check CMP setup.', hookConfig);
+    }
+  }
+
+  function handleV1CmpResponseCallbacks() {
     const cmpResponse = {};
 
     function afterEach() {
       if (cmpResponse.getConsentData && cmpResponse.getVendorConsents) {
+        utils.logInfo('Received all requested responses from CMP', cmpResponse);
         cmpSuccess(cmpResponse, hookConfig);
       }
     }
@@ -68,10 +128,13 @@ function lookupIabConsent(cmpSuccess, cmpError, hookConfig) {
     }
   }
 
-  let callbackHandler = handleCmpResponseCallbacks();
+  let v1CallbackHandler = handleV1CmpResponseCallbacks();
   let cmpCallbacks = {};
-  let cmpFunction;
+  let { cmpFrame, cmpFunction } = findCMP();
 
+  if (!cmpFrame) {
+    return cmpError('CMP not found.', hookConfig);
+  }
   // to collect the consent information from the user, we perform two calls to the CMP in parallel:
   // first to collect the user's consent choices represented in an encoded string (via getConsentData)
   // second to collect the user's full unparsed consent information (via getVendorConsents)
@@ -81,34 +144,28 @@ function lookupIabConsent(cmpSuccess, cmpError, hookConfig) {
   // check to see if prebid is in a safeframe (with CMP support)
   // else assume prebid may be inside an iframe and use the IAB CMP locator code to see if CMP's located in a higher parent window. this works in cross domain iframes
   // if the CMP is not found, the iframe function will call the cmpError exit callback to abort the rest of the CMP workflow
-  try {
-    cmpFunction = window.__cmp || utils.getWindowTop().__cmp;
-  } catch (e) { }
 
   if (utils.isFn(cmpFunction)) {
-    cmpFunction('getConsentData', null, callbackHandler.consentDataCallback);
-    cmpFunction('getVendorConsents', null, callbackHandler.vendorConsentsCallback);
-  } else if (inASafeFrame() && typeof window.$sf.ext.cmp === 'function') {
-    callCmpWhileInSafeFrame('getConsentData', callbackHandler.consentDataCallback);
-    callCmpWhileInSafeFrame('getVendorConsents', callbackHandler.vendorConsentsCallback);
-  } else {
-    // find the CMP frame
-    let f = window;
-    let cmpFrame;
-    while (!cmpFrame) {
-      try {
-        if (f.frames['__cmpLocator']) cmpFrame = f;
-      } catch (e) { }
-      if (f === window.top) break;
-      f = f.parent;
+    utils.logInfo('Detected CMP API is directly accessible, calling it now...');
+    if (cmpVersion === 1) {
+      cmpFunction('getConsentData', null, v1CallbackHandler.consentDataCallback);
+      cmpFunction('getVendorConsents', null, v1CallbackHandler.vendorConsentsCallback);
+    } else if (cmpVersion === 2) {
+      cmpFunction('addEventListener', cmpVersion, v2CmpResponseCallback);
     }
-
-    if (!cmpFrame) {
-      return cmpError('CMP not found.', hookConfig);
+  } else if (cmpVersion === 1 && inASafeFrame() && typeof window.$sf.ext.cmp === 'function') {
+    // this safeframe workflow is only supported with TCF v1 spec; the v2 recommends to use the iframe postMessage route instead (even if you are in a safeframe).
+    utils.logInfo('Detected Prebid.js is encased in a SafeFrame and CMP is registered, calling it now...');
+    callCmpWhileInSafeFrame('getConsentData', v1CallbackHandler.consentDataCallback);
+    callCmpWhileInSafeFrame('getVendorConsents', v1CallbackHandler.vendorConsentsCallback);
+  } else {
+    utils.logInfo('Detected CMP is outside the current iframe where Prebid.js is located, calling it now...');
+    if (cmpVersion === 1) {
+      callCmpWhileInIframe('getConsentData', cmpFrame, v1CallbackHandler.consentDataCallback);
+      callCmpWhileInIframe('getVendorConsents', cmpFrame, v1CallbackHandler.vendorConsentsCallback);
+    } else if (cmpVersion === 2) {
+      callCmpWhileInIframe('addEventListener', cmpFrame, v2CmpResponseCallback);
     }
-
-    callCmpWhileInIframe('getConsentData', cmpFrame, callbackHandler.consentDataCallback);
-    callCmpWhileInIframe('getVendorConsents', cmpFrame, callbackHandler.vendorConsentsCallback);
   }
 
   function inASafeFrame() {
@@ -138,17 +195,22 @@ function lookupIabConsent(cmpSuccess, cmpError, hookConfig) {
   }
 
   function callCmpWhileInIframe(commandName, cmpFrame, moduleCallback) {
+    let apiName = (cmpVersion === 2) ? '__tcfapi' : '__cmp';
+
     /* Setup up a __cmp function to do the postMessage and stash the callback.
       This function behaves (from the caller's perspective identicially to the in-frame __cmp call */
-    window.__cmp = function (cmd, arg, callback) {
+    window[apiName] = function (cmd, arg, callback) {
       let callId = Math.random() + '';
+      let callName = `${apiName}Call`;
       let msg = {
-        __cmpCall: {
+        [callName]: {
           command: cmd,
           parameter: arg,
           callId: callId
         }
       };
+      if (cmpVersion !== 1) msg[callName].version = cmpVersion;
+
       cmpCallbacks[callId] = callback;
       cmpFrame.postMessage(msg, '*');
     }
@@ -157,28 +219,19 @@ function lookupIabConsent(cmpSuccess, cmpError, hookConfig) {
     window.addEventListener('message', readPostMessageResponse, false);
 
     // call CMP
-    window.__cmp(commandName, null, cmpIframeCallback);
+    window[apiName](commandName, null, moduleCallback);
 
     function readPostMessageResponse(event) {
-      let json = (typeof event.data === 'string' && strIncludes(event.data, 'cmpReturn')) ? JSON.parse(event.data) : event.data;
-      if (json.__cmpReturn && json.__cmpReturn.callId) {
-        let i = json.__cmpReturn;
+      let cmpDataPkgName = `${apiName}Return`;
+      let json = (typeof event.data === 'string' && strIncludes(event.data, cmpDataPkgName)) ? JSON.parse(event.data) : event.data;
+      if (json[cmpDataPkgName] && json[cmpDataPkgName].callId) {
+        let payload = json[cmpDataPkgName];
         // TODO - clean up this logic (move listeners?); we have duplicate messages responses because 2 eventlisteners are active from the 2 cmp requests running in parallel
-        if (typeof cmpCallbacks[i.callId] !== 'undefined') {
-          cmpCallbacks[i.callId](i.returnValue, i.success);
-          delete cmpCallbacks[i.callId];
+        if (typeof cmpCallbacks[payload.callId] !== 'undefined') {
+          cmpCallbacks[payload.callId](payload.returnValue, payload.success);
         }
       }
     }
-
-    function removePostMessageListener() {
-      window.removeEventListener('message', readPostMessageResponse, false);
-    }
-
-    function cmpIframeCallback(consentObject) {
-      removePostMessageListener();
-      moduleCallback(consentObject);
-    }
   }
 }
 
@@ -204,6 +257,7 @@ export function requestBidsHook(fn, reqBidsConfigObj) {
 
   // in case we already have consent (eg during bid refresh)
   if (consentData) {
+    utils.logInfo('User consent information already known.  Pulling internally stored information...');
     return exitModule(null, hookConfig);
   }
 
@@ -232,22 +286,50 @@ export function requestBidsHook(fn, reqBidsConfigObj) {
  * @param {object} hookConfig contains module related variables (see comment in requestBidsHook function)
  */
 function processCmpData(consentObject, hookConfig) {
-  let gdprApplies = consentObject && consentObject.getConsentData && consentObject.getConsentData.gdprApplies;
-  if (
-    (typeof gdprApplies !== 'boolean') ||
-    (gdprApplies === true &&
-      !(utils.isStr(consentObject.getConsentData.consentData) &&
-        utils.isPlainObject(consentObject.getVendorConsents) &&
-        Object.keys(consentObject.getVendorConsents).length > 1
+  function checkV1Data(consentObject) {
+    let gdprApplies = consentObject && consentObject.getConsentData && consentObject.getConsentData.gdprApplies;
+    return !!(
+      (typeof gdprApplies !== 'boolean') ||
+      (gdprApplies === true &&
+        !(utils.isStr(consentObject.getConsentData.consentData) &&
+          utils.isPlainObject(consentObject.getVendorConsents) &&
+          Object.keys(consentObject.getVendorConsents).length > 1
+        )
       )
-    )
-  ) {
-    cmpFailed(`CMP returned unexpected value during lookup process.`, hookConfig, consentObject);
-  } else {
-    clearTimeout(hookConfig.timer);
-    storeConsentData(consentObject);
+    );
+  }
+
+  function checkV2Data() {
+    let gdprApplies = consentObject && consentObject.gdprApplies;
+    let tcString = consentObject && consentObject.tcString;
+    return !!(
+      (typeof gdprApplies !== 'boolean') ||
+      (gdprApplies === true && !utils.isStr(tcString))
+    );
+  }
 
-    exitModule(null, hookConfig);
+  // do extra things for static config
+  if (userCMP === 'static') {
+    cmpVersion = (consentObject.getConsentData) ? 1 : (consentObject.getTCData) ? 2 : 0;
+    // remove extra layer in static v2 data object so it matches normal v2 CMP object for processing step
+    if (cmpVersion === 2) {
+      consentObject = consentObject.getTCData;
+    }
+  }
+
+  // determine which set of checks to run based on cmpVersion
+  let checkFn = (cmpVersion === 1) ? checkV1Data : (cmpVersion === 2) ? checkV2Data : null;
+
+  if (utils.isFn(checkFn)) {
+    if (checkFn(consentObject)) {
+      cmpFailed(`CMP returned unexpected value during lookup process.`, hookConfig, consentObject);
+    } else {
+      clearTimeout(hookConfig.timer);
+      storeConsentData(consentObject);
+      exitModule(null, hookConfig);
+    }
+  } else {
+    cmpFailed('Unable to derive CMP version to process data.  Consent object does not conform to TCF v1 or v2 specs.', hookConfig, consentObject);
   }
 }
 
@@ -279,17 +361,27 @@ function cmpFailed(errMsg, hookConfig, extraArgs) {
  * @param {object} cmpConsentObject required; an object representing user's consent choices (can be undefined in certain use-cases for this function only)
  */
 function storeConsentData(cmpConsentObject) {
-  consentData = {
-    consentString: (cmpConsentObject) ? cmpConsentObject.getConsentData.consentData : undefined,
-    vendorData: (cmpConsentObject) ? cmpConsentObject.getVendorConsents : undefined,
-    gdprApplies: (cmpConsentObject) ? cmpConsentObject.getConsentData.gdprApplies : undefined
-  };
+  if (cmpVersion === 1) {
+    consentData = {
+      consentString: (cmpConsentObject) ? cmpConsentObject.getConsentData.consentData : undefined,
+      vendorData: (cmpConsentObject) ? cmpConsentObject.getVendorConsents : undefined,
+      gdprApplies: (cmpConsentObject) ? cmpConsentObject.getConsentData.gdprApplies : undefined
+    };
+  } else {
+    consentData = {
+      consentString: (cmpConsentObject) ? cmpConsentObject.tcString : undefined,
+      vendorData: (cmpConsentObject) || undefined,
+      gdprApplies: (cmpConsentObject) ? cmpConsentObject.gdprApplies : undefined
+    };
+  }
+  consentData.apiVersion = cmpVersion;
+
   gdprDataHandler.setConsentData(consentData);
 }
 
 /**
  * This function handles the exit logic for the module.
- * There are several paths in the module's logic to call this function and we only allow 1 of the 3 potential exits to happen before suppressing others.
+ * While there are several paths in the module's logic to call this function, we only allow 1 of the 3 potential exits to happen before suppressing others.
  *
  * We prevent multiple exits to avoid conflicting messages in the console depending on certain scenarios.
  * One scenario could be auction was canceled due to timeout with CMP being reached.
@@ -336,6 +428,7 @@ function exitModule(errMsg, hookConfig, extraArgs) {
 export function resetConsentData() {
   consentData = undefined;
   userCMP = undefined;
+  cmpVersion = 0;
   gdprDataHandler.setConsentData(null);
 }
 

modules/userId/index.js

@@ -208,7 +208,10 @@ function hasGDPRConsent(consentData) {
     if (!consentData.consentString) {
       return false;
     }
-    if (consentData.vendorData && consentData.vendorData.purposeConsents && consentData.vendorData.purposeConsents['1'] === false) {
+    if (consentData.apiVersion === 1 && utils.deepAccess(consentData, 'vendorData.purposeConsents.1') === false) {
+      return false;
+    }
+    if (consentData.apiVersion === 2 && utils.deepAccess(consentData, 'vendorData.purpose.consents.1') === false) {
       return false;
     }
   }