ping

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.

• Command
• Response

---

Command

Browser console

//call the __tcfapi() function from the browser console with the ping command 
__tcfapi('ping', 2, (pingReturn) => {
   console.log("retrieving pingReturn: ", pingReturn)
});

JavaScript

...
        
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
    }
    }
});
...

---

Response

200 example

{
  "apiVersion": "2",
  "cmpId": 6,
  "cmpLoaded": true,
  "cmpStatus": "loaded",
  "cmpVersion": 1,
  "displayStatus": "hidden",
  "gdprApplies": true,
  "gvlVersion": 196,
  "tcfPolicyVersion": 2
}

Schema (YAML)

schema:
    description: Response for [PingReturn object](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md#pingreturn)
    type: object
    properties:
      apiVersion:
        type: string
        description: Version of the CMP API that is supported. Currently the value is 2
        example: 2
      cmpId:
        type: number
        description: IAB assigned CMP ID
        example: 6
      cmpLoaded:
        type: boolean
        description: Indicates if the CMP main script has loaded. true means CMP main script is ready. false means CMP main script has not loaded, stub is still running
        example: true
      cmpStatus:
        type: string
        description: Returns loaded | stub | error. Loaded is if the CMP has finished loading. Stub is if the CMP has not yet loaded and the stub is in place. Error is if the CMP is in an error state. A CMP shall not respond to any other API requests if cmpStatus returns error.
        example: loaded
      cmpVersion:
        type: number
        description: CMPs own/internal version that is currently running
        example: 1
      displayStatus:
        type: string
        description: Returns visible | hidden | disabled.
        example: hidden
      gdprApplies:
        type: boolean
        description: true is if GDPR applies to end-user browser session. false if if GDPR does not apply to end-user browser session
        example: true
      gvlVersion:
        type: number
        description: Version of the Global Vendor List currently loaded by the CMP
        example: 196
      tcfPolicyVersion:
        type: number
        description: Number of the supported TCF version
        example: 2

📘

Click here for additional information on the pingReturn object .