IAB TCF Developer Guide

📘
Note
As of September 2021, the 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
removeEventListener

The TCF API 2.0 function takes the general form:

__tcfapi(command, version, callback, parameter)

getTCData

📘
Note
getTCData is deprecated in TCF v2.2. Instead add an 'addEventListener' and use its callback function to access the tcData object.

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:

__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:

__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:

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:

__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:

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

  if(success) {
    // do something with gvl
  } else {
    // do something else
  }
}, 'LATEST');

Returned Objects

TCData

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 Vendors 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

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

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.

OneTrust Internal Users: DO NOT MAKE ANY DIRECT CHANGES!

IAB TCF Developer Guide

📘
Note

Required API Commands

getTCData

📘
Note

Example:

ping

Example:

addEventListener

Example:

removeEventListener

Optional API Commands

getInAppTCData

Example:

getVendorList

Example:

Returned Objects

TCData

InAppTCData

PingReturn

OneTrust Internal Users: DO NOT MAKE ANY DIRECT CHANGES!

📘Note

Required API Commands

getTCData

📘Note

Example:

ping

Example:

addEventListener

Example:

removeEventListener

Optional API Commands

getInAppTCData

Example:

getVendorList

Example:

Returned Objects

TCData

InAppTCData

PingReturn

📘
Note

📘
Note