This document contains the CMP TCFv2 and CCPA API reference guide, including sample code illustrating the API's intent. This is an advanced topic targeted for web developers.
The sample code in this document is for illustration purposes only and does not provide complete workable code that you can use on your webpage.
Support Center
__tcfapi('ping', 2, function(pingData) { console.log('cmp responded:', pingData);});
__tcfapi('getTCData', 2, function(tcData, success) { console.log('cmp responded:', tcData, success);});
__tcfapi('addEventListener', 2, function(tcData, success) { console.log('cmp responded:', tcData, success);});
__tcfapi('getNonIABVendorConsents',2, function(consent, success) { console.log('cmp responded:', consent, success);});
__tcfapi('displayConsentUi',2, function() {});
__tcfapi('getConfig',2, function(config) { console.log(config); } );
As of version 2.2, the getTCData command is deprecated. Vendors who depend on this command to obtain the TC string are advised to use event listeners. The adoption of event listeners ensures that vendors consistently access the latest version of the TC string, concurrently minimizing the frequency of API calls required by the vendor. Please update your implementations accordingly to align with this deprecation.
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
}
});
}
}
});
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.
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.
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.
Use the following APIs to identify the CCPA CMP status and information on your website.
__uspapi("getUSPData", 1, function(uspData, success) { console.log('cmp responded:', uspData, success);});
__uspapi("displayUspUi");
__cmp("displayUspUi");
__uspapi("uspPing", 1, function(uspData, success) { console.log('cmp responded:', uspData, success);});
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.
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/
By installing this SDK update, you agree that your Children Privacy Compliance setting remains accurate or that you will update that setting, whenever there is a change in your app's audience. You may update the app's Children Privacy Compliance settings at https://publisher.inmobi.com/my-inventory/app-and-placements.