__tcfapi function - ping call

In this article we will cover the IAB __tcfapi() function with the ping command. 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 TCF API commands from the IAB.


the ping command

The ping command will return the IAB TCF v2 ping object that determines whether the main CMP script has loaded and if GDPR applies.

ping command

__tcfapi('ping', 2, function(pingReturn) {
   console.log("retrieving pingReturn: ", pingReturn)
});

Example implementation

Your organization can call the ping command through the browser console or Javascript code on a webpage.

With browser console Javascript code

Once your organization's website has loaded enter this command directly into the browser tools console window and press enter:

__tcfapi('ping', 2, (pingReturn) => {
   console.log("retrieving pingReturn: ", pingReturn)
});

API response

The response is an object that contains the data described here:

Parameter Description
cmpId IAB Assigned CMP ID
cmpStatus This property has the following values:
  • loaded if the CMP has finished loading
  • stub if the CMP not yet loaded – stub still in place
  • error if the CMP is in an error state. A CMP shall not respond to any other API requests if this cmpStatus is present.
A CMP may set an error if it is unable to perform the operations in compliance with the TCF
cmpVersion CMPs own/internal version that is currently running
gvlVersion Version of the Global Vendor List currently loaded by the CMP
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.
tcfPolicyVersion CMPs own/internal version that is currently running
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
displayStatus visible | hidden | disabled
apiVersion 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
}
Was this article helpful?
0 out of 0 found this helpful