The ping command will return the IAB TCF v2 ping object that you can use to determine whether the main CMP script has loaded and if GDPR applies for your pageview.
Note: Click here to find more information about the TCF API commands from the IAB.
Command
Your organization can call the ping command through the browser console or Javascript code on a webpage.
Once your organization's website has loaded, enter the following command directly into the browser tools' console window.
__tcfapi('ping', 2, (pingReturn) => {
console.log("retrieving pingReturn: ", pingReturn)
});Your organization could also use JavaScript code similar to the following example to utilize the values from the ping object:
...
function show_pingReturn(pingReturn) {
// custom code displays the properties of pingReturn data object
console.log('value cmpId is ' + pingReturn.cmpId);
console.log('value cmpVersion is ' + pingReturn.cmpVersion);
console.log('value cmpLoaded is ' + pingReturn.cmpLoaded);
console.log('value gdprApplies is ' + pingReturn.gdprApplies);
console.log('value tcfPolicyVersion is ' + pingReturn.tcfPolicyVersion);
console.log('value cmpLoaded is ' + pingReturn.cmpLoaded);
console.log('value cmpStatus is ' + pingReturn.cmpStatus);
console.log('value displayStatus is ' + pingReturn.displayStatus);
console.log('value apiVersion is ' + pingReturn.apiVersion);
}
__tcfapi('addEventListener', 2, function(tcdata, success) {
if(success) {
// call TCF API ping command
__tcfapi('ping', 2, (pingReturn) => {
// call custom code to display values of pingReturn data object properties
show_pingReturn(pingReturn);
});
if (tcdata.eventStatus === 'useractioncomplete') {
// call code when user has made an action
} else if (tcdata.eventStatus === 'tcloaded') {
// call code when consent string has loaded
} else if (tcdata.eventStatus === 'cmpuishown') {
// call code when cmp message is shown
}
}
});
... Note: This example uses the addEventListener that allows your organization to listen to specific events (e.g. an end-user changes their consent), and automatically perform custom actions in response. The addEventListener is described in this article.
Response
The ping response is an object that contains the data described below:
| Key | Type | Value |
cmpId |
Number | IAB Assigned CMP ID |
cmpStatus |
String | This property has the following values:
|
cmpVersion |
Number | CMPs own/internal version that is currently running |
gvlVersion |
Number | Version of the Global Vendor List currently loaded by the CMP |
gdprApplies |
Boolean | the CMP sets the value: • true if GDPR applies• false if GDPR does not applyIf your organization decides that GDPR applies to all traffic they can signal the CMP to always return true. |
tcfPolicyVersion |
Number | CMPs own/internal version that is currently running |
cmpLoaded |
Boolean | indicates if the CMP main script has loaded: • true CMP main script is ready• false CMP main script has not loaded, stub still running |
displayStatus |
String | visible | hidden | disabled |
apiVersion |
String | version of the CMP API that is supported. Currently the value is "2.0" |
Object {
apiVersion: "2"
cmpId: 6
cmpLoaded: true
cmpStatus: "loaded"
cmpVersion: 1
displayStatus: "disabled"
gdprApplies: true
gvlVersion: 130
tcfPolicyVersion: 2
}