Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Functionality

This function is used to notify the caller about the users consent when it is available. It is part of the IAB Europe Transparency and Consent Framework (TCF) Specifications.

Syntax

function __tcfapi()

argument name

type

optional

value

description

command

string

'addEventListener'

version

integer

✔️

null|2

The TCF API version to use. Can be null instead.

callback

function

function(tcData:TCData, success:boolean)

The callback function that is called with the function call result.

Description

In order to retrieve user consent, the IAB specification provides two different functions: addEventListener and getTCData. Although both can retrieve user consent, addEventListener is recommended, given it can "follow" the user interaction, making sure that it will eventually return the consent data once the user has finished interacting with the CMP GUI. On the other hand, getTCData function just returns the current consent status. This means that it may return uninitialized, incomplete or full consent data, depending on the timing it is called. This means that the responsibility to obtain the definite data for the consent falls over the publisher lap. With addEventListener every consent status change triggers a new call to the given callback, which means that the only thing needed to process the consent data is a simple check for whether or not that consent data is final, thus usable down the line.

When addEventListener is called, it will immediately respond with a result, no matter if the user consented already or not. The callback will be called again for every status change so that it will eventually receive the users consent.

An event listener registered with addEventListener can be removed with removeEventListener

Scope

The function can be called at any time, but the response will change depending when it is called.

Examples

Wait for AdConsent to ask for users consent

AdConsent will ask the user for consent, if required, and wait until the user finished, then fire the callback.
For regions where no consent is required, AdConsent will immediately continue and fire the callback.
This example is used, when using a 3rd party library that requires the __tcfapi and the user to finish his choices.

__tcfapi('addEventListener', 2, function(tcData, success) {
  if(success && (tcData.eventStatus === 'tcloaded' || tcData.eventStatus === 'useractioncomplete')) {
    // AdConsent finished asking for consent, do something that is dependend on user consent ...
    console.log("Get consent finished", tcData);
  }
});

Wait for consent and do something only once

Wait for consent and remove event listener. This example will trigger the dependent code only once.

__tcfapi('addEventListener', 2, function(tcData, success) {
  if(success && (tcData.eventStatus === 'tcloaded' || tcData.eventStatus === 'useractioncomplete')) {
    __tcfapi('removeEventListener', 2, null, tcData.listenerId);
    // AdConsent finished asking for consent, do something that is dependend on user consent ...
    console.log("This code is triggered only once", tcData);
  }
});

Wait for consent and check if Google got consent

Google API's like gpt or adsense require vendor consent for Google and devices access. This example will wait for the users consent choice and check the requirements.

__tcfapi('addEventListener', 2, function(tcData, success) {
  if(success && (tcData.eventStatus === 'tcloaded' || tcData.eventStatus === 'useractioncomplete')) {
    // Check if Google has vendor consent and device access: Google Id is 755, Device access is purpose 1
    if(!tcData.gdprApplies || (tcData.vendor.consents[755] && tcData.purpose.consents[1])) {
      // for example, trigger adsense
      console.log("Google has vendor consent and device access which is required for gpt and adsense", tcData);
    } else {
      console.log("Google is missing consent", tcData);
    }
  }
});

Wait for consent and check the users choices

This example shows how to check for full or partial user consent.

__tcfapi('addEventListener', 2, function(tcData, success) {
  if(success && (tcData.eventStatus === 'tcloaded' || tcData.eventStatus === 'useractioncomplete')) {
    if(tcData.gdprApplies) {
      // Get global vendor list and check if all vendors got consent
      __tcfapi('getVendorList', 2, function(gvl, success) {
        if(success) {
          if(Object.keys(tcData.vendor.consents).length == Object.keys(gvl.vendors).length &&
             Object.keys(tcData.purpose.consents).length == Object.keys(gvl.purposes).length) {
            // User clicked "Accept All"
            console.log("User gave full consent", tcData);
          } else if(Object.keys(tcData.vendor.consents).length == 0 &&
                    Object.keys(tcData.purpose.consents).length == 0) {
            // User clicked "Customize choices" and then "Save preferences"
            console.log("User rejected consent", tcData);
          } else {
            // User customized consent choices
            console.log("User gave partial customized consent", tcData);
          }
        }
      });
    } else {
      console.log("GDPR does not apply, have full consent");
    }
  } else {
    console.log("User consent not available yet", tcData);
  }
});

  • No labels