IAB __tcfapi function

In this article we will cover the IAB __tcfapi()function. Your organization can use these commands in Javascript source code to perform actions specific to your needs. Click here to find more information about the TCFv2 API commands from the IAB.

__tcfapi() arguments

The __tcfapi() function takes up to four arguments:

Argument description
Argument description

Argument

Description

Command

The specific action your organization wishes to perform.

Transparent Consent Framework API version

Currently version 2. The value would be '2'

Callback function

A callback function can be custom code defined by your organization to complete a task depending on the value of success and using the data in tcData. See below for more information.

Vendor ids

This argument is optional. These are ids for specific vendors your organization wish to check. This will limit the content of the TC String to these vendors only.

Your organization could write a custom callback function that returns the vendors in the tcData that operate under legitimate interest.

The callback function has two arguments:

  • tcData - a JSON object that contains both the encoded and unencoded values of the TC string

  • success - a boolean value (true/false) that informs if the command request was successful

Code example
Code example
function custom_fn(tcdata,success) {
// your custom callback code can be included here
console.log(tcdata, success)
}
// call the __tcfapi() function with callback only
__tcfapi('addEventListener', 2, custom_fn);
// call the __tcfapi() function with callback & vendor ids
__tcfapi('getTCData', 2, custom_fn, [1,2,3,4]);

__tcfapi() commands

The __tcfapi() function provides four commands: getTCData, ping, addEventListener, removeEventListener

Sourcepoint has created additional commands in order to amend the standard mechanisms provided by the IAB's TCFv2 with an API that returns an additional data set to handle a broader range of use cases. Please see below for more information:

getTCData command

The getTCData command allows your organization to retrieve unencoded and encoded values of the TC String. The TC String also provides additional information about the CMP event status, if GDPR applies to the end-user and more.

The getTCData command can be called in the browser console. For more information, please follow the links below:

Code
API Response
Purpose & Publisher Response
Vendor Response
Restrictions
Code
__tcfapi('getTCData', 2, function(tcdata,success) {
// your custom callback code can be included here
console.log("retrieving TCDATA:", tcdata)
});
API Response

The response is a JSON object that contains the consent data described here:

Property

Description

gdprApplies

the CMP sets the value: • true if GDPR applies • false if GDPR does not apply If your organization decides that GDPR applies to all traffic they can signal the CMP to always return true.

eventStatus

the status of the CMP. This property has three values:

tcloaded - if the CMP has a valid TC String to deliver to any calling scripts

cmpuishown - when the first layer message is shown to the end-user

useractioncomplete - when the end-user has confirmed their choices and the CMP has the corresponding TC String to send to any calling scripts

cmpStatus

the status of the CMP. This property has three values:

stub - the CMP has not yet loaded

loaded - the CMP has loaded

error - the CMP has an error and is unable to repond to any API requests. A CMP may set this if, for any reason, it cannot perform an operation that complies with the TCF

listenerId

the id of the listener if the getTCData command has been called in response from an addEventListener action

cmpStatus: "loaded"
eventStatus: "useractioncomplete"
gdprApplies: true
listenerId: 0
Purpose & Publisher Response

For consent given by purpose and publisher the response is described here:

Response

Description

consents

List of purpose ids. Each purpose id has a boolean value:

true - consent granted

false - no consent given

legitimateInterests

List of purpose ids. Each purpose id has a boolean value:

true - legitimate interest established

false - no legitimate interest established

publisher:
consents: {1: true, 2: true, 3: false, 4: true, 5: false, 6: true, 7: true, 8: true, 9: true, 10: true}
legitimateInterests: {1: false, 2: false, 3: true, 4: false, 5: true, 6: true, 7: false, 8: false, 9: true, 10: true}
purpose:
consents: {1: true, 2: true, 3: true, 4: true, 5: true, 6: true, 7: true, 8: true, 9: true, 10: true}
legitimateInterests: {1: false, 2: false, 3: true, 4: false, 5: true, 6: true, 7: false, 8: true, 9: true, 10: true}
Vendor Response

For consent given by vendor the the response is described here:

Response by vendor

Description

consents

List of vendor ids. Each vendor id has a boolean value:

true - consent granted

false - no consent given

legitimateInterests

List of vendor ids. Each vendor id has a boolean value:

true - legitimate interest established

false - no legitimate interest established

vendor:
consents: {1: false, 2: false, 3: false, 4: true, 5: true, ...}
legitimateInterests: {1: false, 2: true, 3: true, 4: false, 5: false, ...}
Restrictions

Click here for more information about publisher restrictions.

For restrictions set by the publisher through the vendor list the response is described here:

Restriction by purpose id, vendor id

Description

purpose id

List of purpose ids. Each purpose id has a list of vendor ids

vendor id

List of vendor ids. Each vendor id has an integer value:

0 - not allowed

1 - require consent

2 - require legitimate interest

restrictions:
2: {174: 0, 915: 1}
3: {753: 2}
6: {828: 1}
7: {174: 0, 467: 1, 915: 1}
8: {828: 1}
9: {109: 1, 828: 1}
10: {828: 1, 915: 1}

ping command

The ping command informs whether or not the main CMP script has loaded and if GDPR applies. This command should be implemented and called before any other command.

Code
ping Response
Code
__tcfapi('ping', 2, (pingReturn) => {
// your custom callback code can be included here
console.log("retrieving pingReturn:", pingReturn)
});
ping Response

The response is a JSON object that contains the data described here:

Parameter

Description

apiVersion

version of the CMP API that is supported. Currently the value is "2.0"

cmpLoaded

indicates if the CMP main script has loaded:

true - CMP main script is ready

false - CMP main script has not loaded, stub still running

gdprApplies

the CMP sets the value: • true if GDPR applies • false if GDPR does not apply If your organization decides that GDPR applies to all traffic they can signal the CMP to always return true.

cmpLoaded: false
cmpStatus: "stub"
gdprApplies: true

addEventListener command

Your organization can respond to specific events or actions made by the end-user using the addEventListener command. The addEventListener command registers a callback function with the CMP.

The event listener is registered with an ID for later removal.

The callback will be triggered for every end-user action unless unless it is removed via removeEventListener. The callback function can optionally be triggered for three specific event status.

addEventListener event status
addEventListener event status

Your organization has the option to specify when the callback function is triggered for three specific event status.

Event Status

Description

tcloaded

The CMP is loaded and prepared to sent a TC string

cmpuishown

The CMP has displayed the first layer message to the end-user

useractioncomplete

The user has confirmed or re-confirmed their consent choices and the CMP will respond with the corresponding TC string.

Example
Example
function callback_function(tcData, success) {
// your custom callback code can be included here
if(success) {
console.log('tcData response:', tcData);
if (tcData.eventStatus === 'useractioncomplete') {
// where eventStatus is 'useractioncomplete'
console.log('eventStatus is useractioncomplete');
} else if (tcData.eventStatus === 'tcloaded') {
// where eventStatus is 'tcloaded'
console.log('eventStatus is tcloaded');
} else if (tcData.eventStatus === 'cmpuishown') {
// where eventStatus is 'cmpuishown'
console.log('eventStatus is cmpuishown');
}
}
}
__tcfapi('addEventListener', 2, callback_function);

removeEventListener command

To remove the event listener you call the __tcfapi() function using the removeEventListener command.

An additional parameter is required, the listener id tcData.listenerId. This id is automatically created with the addEventListener command.

Code
Example
Code
__tcfapi('removeEventListener', 2, function (success) {
// your custom callback code can be included here
console.log('removed event listener: ' + tcData.listenerId);
}, tcData.listenerId);
Example
function callback_function(tcData, success) {
// your custom callback code can be included here
if(success) {
console.log('tcData response:', tcData);
if (tcData.eventStatus === 'useractioncomplete') {
// where eventStatus is 'useractioncomplete'
console.log('eventStatus is useractioncomplete');
} else if (tcData.eventStatus === 'tcloaded') {
// where eventStatus is 'tcloaded'
console.log('eventStatus is tcloaded');
} else if (tcData.eventStatus === 'cmpuishown') {
// where eventStatus is 'cmpuishown'
console.log('eventStatus is cmpuishown');
}
// remove event listener to prevent being called more than once
__tcfapi('removeEventListener', 2, (success) => {
if(success) {
console.log('removed event listener: ' + tcData.listenerId);
}
}, tcData.listenerId);
}
}
__tcfapi('addEventListener', 2, callback_function, event);