The __tcfapi getTCData API Overview

Overview

The Consent Management Platform (CMP) API provides a standardized means for publisher and third party vendors to access user consent preferences managed by the CMP. The __tcfapi function is the means by which publisher, advertisers and third party vendors can access consent data. This article covers the getTCData command, which is provided by the IAB's TCFv2 and is designed to return the standardized consent signals defined by the TCFv2's API specifications.

The __tcfapi function takes up to four arguments to handle TCFv2 standard use cases:

  • command - the type of functionality you want to perform:

    • getTCData

    • ping

    • addEventListener

    • removeEventListener

  • version - the version of the Transparence Consent Framework (TCV), currently 2.

  • callback - a function that gets two arguments passed to it.

    • TCData - a JSON object that contains both the encoded and unencoded values of the TC String as well as information about the CMP.

    • status - a boolean value whether or not the request was successful. A value of false will be passed as the argument to the success callback parameter if an invalid vendorIds argument is passed with this command.

  • vendor IDs (optional) - the IDs for specific vendors for which to check. This will limit the data output to the array of the vendor IDs only.

Below is an example of a the getTCData command being run in the javascript console:

__tcfapi('getTCData', 2, (tcData, success) => {
if(success) {
// do something with tcData
} else {
// do something else
}
}, [1,2,3]);

The command returns user specific consent data in a JSON object. Of particular interest is the data detailing the consent status of specific purposes and vendors. For each vendor or purpose, the JSON object will contain the ID as defined in the Global Vendor List (GVL) for the vendor or purpose. It also contains a consent status of true or false as detailed in the purpose and vendor sections of the JSON object.

Below is an output from a __tcfapi function call to the getTCData command that asks for the consent for vendors with IDs 2, 4, 6, 8, and 10. In other words, running __tcfapi('getTCData', 2, function(data,success){console.log(data);},[2,6,8,10]);

In the javascript console, you would see the output similar to what you see below for vendors and consents

purpose:
consents: {1: true}
legitimateInterests: {2: true, 7: true, 10: true}
vendor:
consents:
2: false
6: false
8: false
10: true

To learn more about the __tcfapi(), the getTCData command TCData object, you can visit the IAB's web site on the Consent Management API.