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​​__tcfapi()commands​
The __tcfapi() function takes up to four arguments:
Argument | Description |
Command | The specific action your organization wishes to perform. |
Transparent Consent Framework API version | Currently version 2. The value would be |
Callback function | A callback function can be custom code defined by your organization to complete a task depending on the value of |
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 stringsuccess- a boolean value (true/false) that informs if the command request was successful
function custom_fn(tcdata,success) {// your custom callback code can be included hereconsole.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]);
The __tcfapi() function provides four commands: getTCData, ping, addEventListener, removeEventListener
​getTCDatacommand​​pingcommand​​addEventListenercommand​
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:
​getVendorPurposeMapping​​getCustomVendorConsents​​postCustomConsent​
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:
__tcfapi('getTCData', 2, function(tcdata,success) {// your custom callback code can be included hereconsole.log("retrieving TCDATA:", tcdata)});
The response is a JSON object that contains the consent data described here:
Property | Description |
| the CMP sets the value:
• |
| the status of the CMP. This property has three values: • • • |
| the status of the CMP. This property has three values: • • • |
| the id of the listener if the |
cmpStatus: "loaded"eventStatus: "useractioncomplete"gdprApplies: truelistenerId: 0
For consent given by purpose and publisher the response is described here:
Response | Description |
| List of purpose ids. Each purpose id has a boolean value: • • |
| List of purpose ids. Each purpose id has a boolean value: • • |
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}
For consent given by vendor the the response is described here:
Response by vendor | Description |
| List of vendor ids. Each vendor id has a boolean value: • • |
| List of vendor ids. Each vendor id has a boolean value: • • |
vendor:consents: {1: false, 2: false, 3: false, 4: true, 5: true, ...}legitimateInterests: {1: false, 2: true, 3: true, 4: false, 5: false, ...}
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 |
| List of purpose ids. Each purpose id has a list of vendor ids |
| List of vendor ids. Each vendor id has an integer value: • • • |
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}
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.
__tcfapi('ping', 2, (pingReturn) => {// your custom callback code can be included hereconsole.log("retrieving pingReturn:", pingReturn)});
The response is a JSON object that contains the data described here:
Parameter | Description |
| version of the CMP API that is supported. Currently the value is "2.0" |
| indicates if the CMP main script has loaded: • • |
| the CMP sets the value:
• |
cmpLoaded: falsecmpStatus: "stub"gdprApplies: true
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.
Your organization has the option to specify when the callback function is triggered for three specific event status.
Event Status | Description |
| The CMP is loaded and prepared to sent a TC string |
| The CMP has displayed the first layer message to the end-user |
| The user has confirmed or re-confirmed their consent choices and the CMP will respond with the corresponding TC string. |
function callback_function(tcData, success) {// your custom callback code can be included hereif(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);
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.
__tcfapi('removeEventListener', 2, function (success) {// your custom callback code can be included hereconsole.log('removed event listener: ' + tcData.listenerId);}, tcData.listenerId);
function callback_function(tcData, success) {// your custom callback code can be included hereif(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);
