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.
The __tcfapi() function takes up to four arguments:
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
1
functioncustom_fn(tcdata,success){
2
// your custom callback code can be included here
3
console.log(tcdata, success)
4
}
5
​
6
// call the __tcfapi() function with callback only
7
__tcfapi('addEventListener',2, custom_fn);
8
​
9
// call the __tcfapi() function with callback & vendor ids
10
__tcfapi('getTCData',2, custom_fn,[1,2,3,4]);
Copied!
__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:
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:
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
1
cmpStatus:"loaded"
2
eventStatus:"useractioncomplete"
3
gdprApplies:true
4
listenerId:0
Copied!
For consent given by purpose and publisher the response is described here:
Response
Description
consents
List of purposeids. Each purpose id has a boolean value:
• true - consent granted
• false - no consent given
legitimateInterests
List of purposeids. Each purpose id has a boolean value:
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
1
restrictions:
2
2:{174:0,915:1}
3
3:{753:2}
4
6:{828:1}
5
7:{174:0,467:1,915:1}
6
8:{828:1}
7
9:{109:1,828:1}
8
10:{828:1,915:1}
Copied!
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
1
__tcfapi('ping',2,(pingReturn)=>{
2
// your custom callback code can be included here
3
console.log("retrieving pingReturn:", pingReturn)
4
});
Copied!
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.
1
cmpLoaded:false
2
cmpStatus:"stub"
3
gdprApplies:true
Copied!
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
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.