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 NameTypeOptionalValue
commandstringNogetTCData
versonnumberNo2
callbackfunctionNofunction(tcData: TCData, sucess: boolean)
parameterint arrayYesvendorIDs

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 NameTypeValue
commandstringping
versionnumber2
callbackfunctionfunction(PingReturn: object)

Example:

__tcfapi('ping', 2, (pingReturn) => {
  // do something with pingReturn
});

addEventListener

Argument NameTypeValue
commandstringaddEventListener
versionnumber2
callbackfunctionfunction(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);
eventStatusDescription
tcloadedThe CMP is loaded and prepared to sent a TC string.
cmpuishownThe 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.
useractioncompleteThe user has confirmed or re-confirmed their consent choices and the CMP will respond with the corresponding TC string.

removeEventListener

Argument NameTypeValue
commandstringremoveEventListener
versionnumber2
callbackfunctionfunction(success: boolean)
parameterfunctionpreviously 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 NameTypeValue
commandstringgetInAppTCData
versionnumber2
callbackfunctionfunction(inAppTCData: InAppTCData, success: boolean)

Example:

__tcfapi('getInAppTCData', 2, (inAppTCData, success) => {
  if(success) {
    // do something with inAppTCData
  } else {
    // do something else
  }
});

getVendorList

Argument NameTypeOptionalValue
commandstringNogetVendorList
versionnumberNo2
callbackfunctionNofunction(gvl: GlovalVendorList, success: boolean)
parameterint or stringYesvendorListVersion

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
      }
    }
  }
}
ValueDescription
gdprApplies true - GDPR Applies
false - GDPR Does not apply
* undefined - unknown whether GDPR Applies
eventStatusSee addEventListener command
cmpStatusSee 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
publisherCCCountry code of the country that determines the policy.
purposeOneTreatmentOnly 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.
outOfBandOnly 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
purposeconsents
true - Consent
false - No Consent

legitimateInterests
true - Legitimate Interest Established
false - No Legitimate Interest Established
vendorconsents
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
publisherconsents
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'
    }
  }
}
ValueDescription
gdprApplies 1 - GDPR Applies
0 - GDPR Does not apply
* undefined - unknown whether GDPR applies
eventStatusSee 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.
publisherCCCountry 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.
purposeconsents
true - Consent
false - No Consent

legitimateInterests
true - Legitimate Interest Established
false - No Legitimate Interest Established
vendorconsents
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
publisherconsents
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
};
ValueDescription
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.
apiVersionVersion of the CMP API that is supported, e.g. "2.0".
cmpVersionCMPs own/internal version that is currently running. It is undefined if still the stub
cmpIdIAB assigned CMP ID. It is undefined if the stub is still in place.
gvlVersionVersion of the GVL currently loaded by the CMP. It is undefined if the stub is still in place.
tcfPolicyVersionNumber of the supported TCF version. It is undefined if the stub is still in place.