IAB TCF 2.0 SDK Developer Guide

Note:

As of September 2021, global scope will no longer be supported per the recent TCF Policy and Technical Specifications. To view the formal notification, please refer to the IAB Europe PDF Notification and IAB Europe PDF Notification Update.

Required API Commands

All CMPs must support four required API commands: getTCData, ping, addEventListener, and removeEventListener.

The TCF API 2.0 function take the general form:

CODE 
__tcfapi(command, version, callback, parameter)

getTCData

Argument Name

Type

Optional

Value

command

string

No

getTCData

verson

number

No

2

callback

function

No

function(tcData: TCData, sucess: boolean)

parameter

int array

Yes

vendorIDs

Example:

CODE 
__tcfapi('getTCData', 2, (tcData, success) => {

  if(success) {

    // do something with tcData

  } else {

    // do something else

  }

}, [1,2,3]);

This will return TCData.

ping

Argument Name

Type

Value

command

string

ping

version

number

2

callback

function

function(PingReturn: object)

Example:

CODE 
__tcfapi('ping', 2, (pingReturn) => {

  // do something with pingReturn

});

addEventListener

Argument Name

Type

Value

command

string

addEventListener

version

number

2

callback

function

function(tcData: TCData, success: boolean)

Example:

JAVASCRIPT 
const callback = (tcData, success) => {

  if(success && tcData.eventStatus === 'tcloaded') {

    // do something with tcData.tcString

    // remove the ourself to not get called more than once
    __tcfapi('removeEventListener', 2, (success) => {

      if(success) {

        // oh good...

      }

    }, callback);


  } else {

    // do something else

  }

}

__tcfapi('addEventListener', 2, callback);

eventStatus

Description

tcloaded

The CMP is loaded and prepared to sent a TC string.

cmpuishown

The TC string is available and has rendered 'Transparency'. The CMP will create TC string will contain the vendors' Legitimate Interest and the consent signals set to false.

useractioncomplete

The user has confirmed or re-confirmed their consent choices and the CMP will respond with the corresponding TC string.

removeEventListener

Argument Name

Type

Value

command

string

removeEventListener

version

number

2

callback

function

function(success: boolean)

parameter

function

previously registered callback (addEventListener)

For example, see addEventListener. The callback will be false if the listener could not be removed. This may happen, for instance, if a listener corresponding to listenerId is not found.

Optional API commands

getInAppTCData

Argument Name

Type

Value

command

string

getInAppTCData

version

number

2

callback

function

function(inAppTCData: InAppTCData, success: boolean)

Example:

CODE 
__tcfapi('getInAppTCData', 2, (inAppTCData, success) => {

  if(success) {

    // do something with inAppTCData

  } else {

    // do something else

  }

});

getVendorList

Argument Name

Type

Optional

Value

command

string

No

getVendorList

version

number

No

2

callback

function

No

function(gvl: GlovalVendorList, success: boolean)

parameter

int or string

Yes

vendorListVersion

Example:

CODE 
__tcfapi('getVendorList', 2, (gvl, success) => {

  if(success) {

    // do something with gvl

  } else {

    // do something else

  }

}, 'LATEST');

Returned Objects

TCData

JSON 
TCData = {
  tcString: 'base64url-encoded TC string with segments',
  tcfPolicyVersion: 2,
  cmpId:1000,
  cmpVersion: 1000,
  gdprApplies: Boolean | undefined,
  eventStatus: String,
  cmpStatus: 'string',
  listenerId: Number | undefined,
  isServiceSpecific: Boolean,
  useNonStandardStacks: Boolean,
  publisherCC: 'Two-letter ISO 3166-1 alpha-2 code',
  purposeOneTreatment: Boolean,
  outOfBand: {
    allowedVendors: {
      '[vendor id]': Boolean
    },
    discloseVendors: {
      '[vendor id]': Boolean
    }
  },
  purpose: {
    consents: {
      '[purpose id]': Boolean
    },
   legitimateInterests: {
      '[purpose id]': Boolean
    }
  },
  vendor: {
    consents: {
      '[vendor id]': Boolean
    },
    legitimateInterests: {
      '[vendor id]': Boolean
    }
  },
  specialFeatureOptins: {
      '[special feature id]': Boolean
  },
  publisher: {
    consents: {
      '[purpose id]': Boolean
    },
    legitimateInterests: {
      '[purpose id]': Boolean
    },
    customPurpose: {
      consents: {
        '[purpose id]': Boolean
      },
      legitimateInterests: {
        '[purpose id]': Boolean
      },
    },
    restrictions: {
      '[purpose id]': {
        '[vendor id]': 1
      }
    }
  }
}

Value

Description

gdprApplies

  • true - GDPR Applies

  • false - GDPR Does not apply

  • undefined - unknown whether GDPR Applies

eventStatus

See addEventListener command.

cmpStatus

See Ping Status Codes in following table.

listenerId

  • If this TCData is sent to the callback of addEventListener: number, the unique ID assigned by the CMP to the listener function registered via addEventListener.

  • Others: undefined

isServiceSpecific

  • true - if using a service-specific or publisher-specific TC String

  • false - if using a global TC String

useNonStandardStacks

  • true - CMP is using publisher-customized stack descriptions

  • false - CMP is NOT using publisher-customized stack descriptions

publisherCC

Country code of the country that determines the policy.

purposeOneTreatment

Only exists on service-specific TC.

  • true - Purpose 1 not disclosed at all. CMPs use PublisherCC to indicate the publisher's country of establishment to help vVendors * determine whether the vendor requires Purpose 1 consent.

  • false - There is no special Purpose 1 treatment status. Purpose 1 was disclosed normally (consent) as expected by TCF Policy.

outOfBand

Only exists on global-scope TC.

allowedVendors

  • true - Vendor is allowed to use an Out-of-Band Legal Basis

  • false - Vendor is NOT allowed to use an Out-of-Band Legal Basis

discloseVendors

  • true - Vendor has been disclosed to the user

  • false - Vendor has NOT been disclosed to the user

purpose
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

vendor
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

specialFeatureOptins

  • true - Special Feature Opted Into

  • false - Special Feature NOT Opted Into

publisher
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

customPurpose
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

restrictions

'[purposeId]':

  • 0 - Not Allowed

  • 1 - Require Consent

  • 2 - Require Legitimate Interest

'[vendor id]': 1

InAppTCData

JSON 
InAppTCData = {
  tcString: 'base64url-encoded TC string with segments',
  tcfPolicyVersion: 2,
  cmpId:1000,
  cmpVersion: 1000,
  gdprApplies: 1,
  eventStatus: 'string',
  isServiceSpecific: 1,
  useNonStandardStacks: 1,
  publisherCC: 'Two-letter ISO 3166-1 alpha-2 code',
  purposeOneTreatment: 1,
  purpose: {
    consents: '01010 -- Purpose bitfield'
    legitimateInterests: '01010 -- Purpose bitfield'
  },
  vendor: {
    consents: '01010 -- Vendor bitfield',
    legitimateInterests: '01010 -- Vendor bitfield'
  },
  specialFeatureOptins: '01010 -- Special Feature bitfield',
  publisher: {
    consents: '01010 -- Purpose bitfield',
    legitimateInterests: '01010 -- Purpose bitfield',
    customPurpose: {
      consents: '01010 -- Purpose bitfield',
      legitimateInterests: '01010 -- Purpose bitfield'
    },
    restrictions: {
      '[purpose id]': '01201221'
    }
  }
}

Value

Description

gdprApplies

  • 1 - GDPR Applies

  • 0 - GDPR Does not apply

  • undefined - unknown whether GDPR applies

eventStatus

See addEventListener.

isServiceSpecific

  • 1 - If using a service-specific or publisher-specific TC String.

  • 0 - If using a global TC String.

useNonStandardStacks

  • 1 - CMP is using publisher-customized stack descriptions.

  • 0 - CMP is NOT using publisher-customized stack descriptions.

publisherCC

Country code of the country that determines the policy.

purposeOneTreatment

  • 1 - Purpose 1 not disclosed at all. CMPs use PublisherCC to indicate the publisher's country of establishment to help vVendors determine whether the vendor requires Purpose 1 consent.

  • 0 - There is no special Purpose 1 treatment status. Purpose 1 was disclosed normally (consent) as expected by TCF Policy.

purpose
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

vendor
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

specialFeatureOptins

  • true - Special Feature Opted Into

  • false - Special Feature NOT Opted Into

publisher

consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

CustomPurpose
consents

  • true - Consent

  • false - No Consent

legitimateInterests

  • true - Legitimate Interest Established

  • false - No Legitimate Interest Established

restrictions

'[purposeId]':

  • 0 - Not Allowed

  • 1 - Require Consent

  • 2 - Require Legitimate Interest

PingReturn

JSON 
PingReturn = {
  gdprApplies: Boolean | undefined,
  cmpLoaded: Boolean,
  cmpStatus: String,
  displayStatus: String,
  apiVersion: String,
  cmpVersion: Number | undefined,
  cmpId: Number | undefined,
  gvlVersion: Number | undefined,
  tcfPolicyVersion: Number | undefined,
};

Value

Description

gdprApplies

* true - GDPR Applies * false - GDPR Does not apply * undefined - unknown whether GDPR Applies * see the section: "What does the gdprApplies value mean?"

cmpLoaded

* true - CMP main script is loaded * false - still running stub

cmpStatus
stub

CMP not yet loaded – stub still in place.

loading

CMP is loading.

loaded

CMP has loaded.

error

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 this status if, for any reason, it is unable to perform the operations in compliance with the TCF.

displayStatus
visible

The user interface is displayed.

hidden

The user interface is not being displayed.

disabled

The user interface will not be displayed. This will be returned when GDPR does not apply or the TC string does not need renewal.

apiVersion

Version of the CMP API that is supported, e.g. "2.0".

cmpVersion

CMPs own/internal version that is currently running. It is undefined if still the stub

cmpId

IAB assigned CMP ID. It is undefined if the stub is still in place.

gvlVersion

Version of the GVL currently loaded by the CMP. It is undefined if the stub is still in place.

tcfPolicyVersion

Number of the supported TCF version. It is undefined if the stub is still in place.