Choice CMP2 & CCPA API Index

  • Last Updated

This document contains the Choice TCFv2 and CCPA API reference guide including sample code illustrating the APIs intent. This is an advanced topic targeted for web developers. 

Note: the sample code in this document are samples for illustration purpose only and do not provide complete workable code that you can use on your webpage.

Other documents in this series:

TCF v2 APIs for Identifying Consent Status

CCPA v1 APIs (USP)

TCF v2 APIs for Identifying Consent Status

CMP Ping

  • Description: Pings the CMP state and checks whether the _tcfapi is operational.
  • Created by: IAB Framework
  • Script: 
__tcfapi('ping', 2, function(pingData) { console.log('cmp responded:', pingData);});

 

Synchronous Consent String API

  • Description: Get the full encoded consent string that the CMP has set on the browser page. This is  a synchronous call resolved immediately after it is called
  • Created by: IAB Framework
  • Script: 
__tcfapi('getTCData', 2, function(tcData, success) { console.log('cmp responded:', tcData, success);});

 

Asynchronous Consent String API

  • Description: Add an event listener to the consent string object that the CMP has set on the browser page. This is intended to be an asynchronous call performed by the CMP after certain conditions are met
  • Created by: IAB Framework
  • Script: 
__tcfapi('addEventListener', 2, function(tcData, success) { console.log('cmp responded:', tcData, success);});

 

Non-IAB Vendor API

  • Description: Find out the user’s consent preference for non-IAB Vendor list
  • Created by: Quantcast Choice
  • Script: 
__tcfapi('getNonIABVendorConsents',2, function(consent, success) { console.log('cmp responded:', consent, success);});

 

Reprompt CMP API

  • Description: Hard re-prompt of the CMP on the website, outside of the Persistent Consent Link feature 
  • Created by: Quantcast Choice
  • Script: 
__tcfapi('displayConsentUi',2, function() {});

Please note: This code will force the "list view" to appear regardless of UI settings chosen.

 

CMP Configuration API

  • Description: Returns the full configurations of the CMP for debugging purposes
  • Created by: Quantcast Choice
  • Script: 
__tcfapi('getConfig',2, function(config) { console.log(config); } );

  

Adding Asynchronous Callbacks to the CMP

Note: This section contains an important change as of Choice v6! With Choice CMP update 6 we corrected the value returned by tcData.eventStatus to conform with the IAB TCFv2 specification. 

For the TCF v2 implementation, callbacks are intended to be handled directly by the CMP through event listeners, as the calls to the CMP commands are intended to be resolved in a synchronous way.

In this sense, the CMP no longer stacks callbacks waiting for consent to be resolved or through a manual definition like the “__cmp(‘setConsentUiCallback’, callback)” command used to be supported in our TCF v1.1 implementation.

We recommend attaching asynchronous callbacks to the CMP through this method as it will be the source of information set up by the CMP at specific moments.

We consider the eventStatus of the TCData object received as the indicator of whether the CMP has loaded valid consent cookies. The eventStatus will either be "tcloaded" for the case that a valid TCF string has been found and no UX has to be shown or be “useractioncomplete” for the case when the UX was shown to the user and the consent string was created or updated. For more details please consult the TCFv2 API tech specification.

Example 1 - IAB Vendors: Sample event listener code for checking IAB Vendor's consent. Here, the Vendor (Id #99) needs consent for Purpose #2, Legitimate Interest for Purpose #3 and either ("Flexible Basis") for Purpose #4.


window.__tcfapi('addEventListener', 2, function(tcData, listenerSuccess) { 
 if (listenerSuccess) {
   // check the eventstatus 
   if (tcData.eventStatus === 'useractioncomplete' || 
     tcData.eventStatus === 'tcloaded') {
     
     // Block of code for parsing tcData for IAB Vendor consents               
     if ((tcData.vendor.consents[99] || tcData.vendor.legitimateInterests[99]) 
       && (tcData.purpose.consent[2] && tcData.purpose.legitimateInterests[3] 
       && (tcData.purpose.consent[4] || tcData.purpose.legitimateInterests[4]))) {
         // perform the function for vendor #99, i.e. insert the vendor tag or make the vendor SDK call
     }

   }
  }
});

 

Example 2 - NonIAB Vendors: Sample event listener code for checking non IAB vendor's consent. Here, the Publisher has assigned this Vendor, the Id #2.

window.__tcfapi('addEventListener', 2, function(tcData, listenerSuccess) { 
  if (listenerSuccess) {
      // check the eventstatus 
      if (tcData.eventStatus === 'useractioncomplete' || 
          tcData.eventStatus === 'tcloaded') {
          console.log('Do IAB Vendors Actions Here');

          // Block of code for the case if nonIAB vendors have 
          // been declared
         window.__tcfapi('getNonIABVendorConsents',2,function(nonIabConsent, nonIabSuccess) {
           if (nonIabSuccess && nonIabConsent.nonIabVendorConsents && nonIabConsent.nonIabVendorConsents[2]) {
             // perform the function for non-iab vendor #2, insert the vendor tag or make the vendor SDK call
           }
         });
      }
   }
}); 

 

Checking Legal Bases for your Vendors 

The legal basis model for NonIAB Vendors is “simple” that is a consent-given or no-consent-given on a per-vendor basis. The legal basis model for IAB Vendors is more complex where vendors can request that consent be given, or Legitimate Interest be disclosed and not objected or a “flexible basis” can be declared. A “flexible” basis means a vendor is flexible about whether a publisher requests that consent be given, or a Legitimate Interest be disclosed and not objected. In addition, vendors can declare that they need Consent or Legitimate Interest for a set of up to 10 pre-defined data processing purposes.

  1. Pull up the vendor list from https://iabeurope.eu/vendor-list-tcf-v2-0/
  2. Find your vendor in the vendor list. The vendor configuration will look like this
11: {
  id: 11,
  name: "Quantcast International Limited",
  purposes: [1,3,4],
  legIntPurposes: [2,7,8,9,10],
  flexiblePurposes: [2,3,4,7,8,9,10],
  specialPurposes: [1,2],
  features: [1,2,3],
  specialFeatures: [ ],
  policyUrl: "https://www.quantcast.com/privacy/"
},

 

The lists purposes shows purposes for which the vendor requests Consent are obtained, legIntPurposes shows purposes for which the vendor requests Legitimate Interest is declared and not obtained and flexiblePurposes indicate which purposes the vendor is flexible on to switch between Legal Bases. Note that if a vendor is flexible, they will by default rely on legal bases shown in the purposes and legIntPurposes lists respectively unless a publisher override instructs them to switch away from their default.



Note: The vendor may not require Consent or Legitimate Interest for all the purposes listed for every operation, check with the vendor’s documentation to see which ones you should apply for your particular use case.

For more information on the IAB TCFv2.0 APIs, please refer to The GitHub IAB Consent Management Platform API.

 

CCPA(USP) APIs to identify CMP Status

Use the following APIs to identify the CCPA CMP status and information on your website.

 

Get USP Data API

  • Description: Returns USP Data and Success, Success is either “true” or “false”.
  • Created by: IAB Framework
  • Script: 
__uspapi("getUSPData", 1, function(uspData, success) { console.log('cmp responded:', uspData, success);});

 

Display USP API

  • Description: Will display the U.S Privacy UI (modal dialog) . It will inherit style and style overrides given in the config object.
  • Created by: Quantcast Choice
  • Script: 
__uspapi("displayUspUi");
  • Outdated Equivalent Command:  
__cmp("displayUspUi");

 

USP Ping API

  • Description: Pings the CMP state and checks whether the _tcpapi is operational.
  • Created by: IAB Framework
  • Script: 
__uspapi("uspPing", 1, function(uspData, success) { console.log('cmp responded:', uspData, success);});

 

Adding USP Ping to CMP  

You can use a call to __uspapi(“uspPing”) to get information about the mode the CMP is running, the jurisdiction configured and the location the user is at. Depending on your webpage configuration you may decide to use your own geo-location validation and not the one provided by our Choice CMP.

Note: This code requires that the CMP has already been loaded as specified in the previous step. 

See example of how to wrap this around an API call below: 

<script>
if (typeof window.__uspapi === 'function') {
    window.__uspapi('uspPing', 1, function(obj, status) {
      if (status && obj.mode.includes('USP') && obj.jurisdiction.includes(obj.location.toUpperCase())) {
          document.getElementById('qc-demo-page-footer').innerHTML = '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 href="#" onclick="window.__uspapi('displayUspUi');"` 
            + '>Do Not Sell My Data</a>' 
            + '.';
          window.__uspapi('setUspDftData', 1, function(obj, status) {
                if (!status) {
                    console.log("Error: USP string not updated!")
                }
          });
        }
       });
     }
  });
}
</script>
 


For more information on the IAB US Privacy API, please refer to https://github.com/InteractiveAdvertisingBureau/USPrivacy/

Return to top
Was this article helpful?
0 out of 0 found this helpful

Related articles

Help