API Functions (GDPR for Web)

__tcfapi(command, [version], [callback], [parameter])

Argument Name	Type	Value
command	String	Name of the command to execute
version	number	Optional parameter, version of the API, currently v1.0
callback	function	Function to be executed with the result of the command
parameter	number	Parameter to be passed to the command function

Consent Status

Caution

getTCData Command Depreciation

In compliance with TCF v2.2, the getTCData command has been depreciated. TCF v2.2 mandates the use of event listeners to ensure that any changes to TC strings are proactively communicated to them and other vendors.

You can add an 'addEventListener' and use its callback function to access the tcData object.

ping

The ping command will return the IAB TCF v2 ping object i.e. to determine whether or not the main CMP script has loaded and whether GDPR applies.

__tcfapi('ping', null, (pingReturn) => {console.log(pingReturn)})

Argument Name	Type	Value
command	string	`'ping'`
version	number	`2`
callback	function	Function to be executed with the result of the command `function(PingReturn:object)`

Result Object

Argument Name	Value
gdprApplies	true if publisher has configured CMP to apply GDPR to all (including non-EEA) visitors
cmpLoaded	true if CMP main script is loaded, false if still running stub
cmpStatus	stub \| loading \| loaded \| error
displayStatus	visible \| hidden \| disabled
apiVersion	version of the CMP API that is supported, e.g. "2.0"
cmpId	IAB Assigned CMP ID
cmpVersion	CMPs own/internal version that is currently running
gvlVersion	Version of the GVL currently loaded by the CMP
tcfPolicyVersion	Number of the supported TCF version
[parameter]	(ignored)

Result Object Example

{gdprApplies: true, cmpLoaded: true, cmpStatus: "loaded", displayStatus: "visible", apiVersion: "2.0", …}
apiVersion: "2.0"
cmpId: 3
cmpLoaded: true
cmpStatus: "loaded"
cmpVersion: 1
displayStatus: "visible"
gdprApplies: true
gvlVersion: 67
tcfPolicyVersion: 2

getFullTCData

The getFullTCData command will return consent data including custom consent string data.

__tcfapi('getFullTCData', 2, (tcData, success) => {console.log(tcData)});

Argument Name	Type	Value
command	string	`'getFullTCData'`
version	number	`2`
callback(result, success)	function	`function(result: TCData, success: boolean)`

Result Object Example

{tcfPolicyVersion: 2, cmpId: 3, cmpVersion: 1, gdprApplies: true, tcString: "CO69m8oO9K-yuADABCENBBCsAPPAAAAAAAAAADNQAAAAAA.YAAAAAAAAAA", …}
cmpId: 3
cmpStatus: "loaded"
cmpVersion: 1
eventStatus: "cmpuishown"
gdprApplies: true
isServiceSpecific: true
listenerId: null
publisher: {consents: {…}, legitimateInterests: {…}}
publisherCC: "aa"
purpose: {consents: {…}, legitimateInterests: {…}}
purposeOneTreatment: false
specialFeatureOptins: {1: true, 2: true}
tcString: "CO69m8oO9K-yuADABCENBBCsAPPAAAAAAAAAADNQAAAAAA.YAAAAAAAAAA"
tcStringCustom: "CO69m8oO9K-yuADABCENBBCgAAAAAAAAAAAAAAAAAAAA.YAAAAAAAAAA"
tcfPolicyVersion: 2
useNonStandardStacks: false
vendor: {consents: {…}, legitimateInterests: {…}}

checkConsent

The checkConsent command will return an object whether or not there is consent for the given vendor.

__tcfapi("checkConsent", 2 ,(data, success)=>{console.log(data)}, [parameter]);

Argument Name	Type	Value
command	string	`'checkConsent'`
version	number	`2`
callback(result)	function	`function(result: boolean)` True if there's consent for provided vendors.
parameter	Array\|Object	Array of objects or only object with `vendorId`, `purposeIds` and `featureIds` properties to check consent for if no data or invalid one is provided result will be false. `recheckConsentOnChange=true` Will trigger every time the consent status has changed by listening to the event consent changed. It will be invoked depending on the event. Per vendor Passing the `perVendor` parameter as `false` will return a boolean regarding all the data which was passed. Passing the `perVendor` parameter as `true` will return an array of objects, and each object will represent consent per vendor from the passed data.

Examples

Example 1

Checking vendorId: 33 and purposeIds: [1,3,5,6] :

__tcfapi("checkConsent", 2, (data, success) => {
    console.log(data)
}, {
    data: [{
        vendorId: 33,
        purposeIds: [1, 3, 5, 6]
    }]
});

Note

If you provide features or/and purposes together with vendorId it will check if that vendor has only those purposes enabled.

So incase purposeIds: [1, 3, 5] is true and purposeIds: [ 6 ] is revoked (false) through the UI. Passing the following command:

__tcfapi("checkConsent", 2, (data, success) => {
    console.log(data)
}, {
    data: [{
        vendorId: 33,
        purposeIds: [1, 3, 5]
    }]
});

Will return true because purpose 6 is not included in the purposeIds Array.

Example 2

If you want to check consent for vendor and all purposes and special features that are associated with it in the global vendor list, you can just pass vendorId:

__tcfapi("checkConsent", 2, (data, success) => {
    console.log(data)
}, {
    data: {
        vendorId: 33
    }
});

In this case the command will check vendorId: 33 and purposeIds: [1, 3, 5, 6] and the return boolean value will reflect the consent state of these purposes as well as the vendor.

Example 3

In this example we tackle the following parameters:

recheckConsentOnChange: true
Custom vendorId: [10007, 10009] (Facebook, LinkedIn)
perVendor: true we are passing/checking more than one vendor ID which will create array of objects, and each object will represent consent pre vendor from the passed data.

        window.__tcfapi('checkConsent', null, function (data, success) {
            console.log(data);        
        }, {
            data: [{
                "vendorId": 10007
            }, {
                "vendorId": 10009
            }],
            recheckConsentOnChange: true,
            perVendor: true
        });

Response, if vendorId: [10007, 10009 ] are in the config and consented:

(2)[{
    0: hasConsent: true
    vendorId: 10007
    vendorName: "Facebook"
    __proto__: Object
}, {
    1: hasConsent: true
    vendorId: 10009
    vendorName: "LinkedIn"
}]

From here for custom solutions (conditional firing) it is recommended to check for the hasConsent property and populate an array or an object with the values, so it can be used later for triggering a certain tag or a function:

window.__tcfapi('checkConsent', null, function (data, success) {
    // a different approach can be integrated here to store 
    //   the vendor boolean values as a refrence. 

    const vendorsWithConsentHc = [];

    if (data && data.length) {
        data.forEach((item) => {
            if (item.hasConsent && item.vendorName) {
                vendorsWithConsentHc.push(item.vendorId);
            }
        });
    }

    window.consentlayer = window.consentlayer || [];
    window.consentlayer.push({
        vendorsWithConsentHc
    });

}, {
    data: [{
        "vendorId": 10007
    }, {
        "vendorId": 10021
    }],
    recheckConsentOnChange: true,
    perVendor: true
});

getConsentCriteria

The getConsentCriteria retrieves the information about the configured vendors with publisher and/or purposes for a configuration.

Argument Name	Type	Value
command	string	`getConsentCriteria`
version	number	(ignored)
callback(result)	function	Function to be executed with the result of the command.
parameter	string	null \| {vendors: boolean, purposes: boolean}. If no argument is passed, return object with vendors and purposes. If vendors or purposes are set to true, only items that are set to true will be returned. Both vendors and purposes properties are optional.

Returns

Object with configured vendors and/or purposes.

Examples

Example 1

__tcfapi('getConsentCriteria', null, (data, success) => {console.log(data)})

Returns

{
  vendors: {
    1: "Exponential Interactive, Inc d/b/a VDX.tv",
    2: "Captify Technologies Limited",
    3: "affilinet",
    0: "Publisher / Brand"
  },
  purposes: {
    1: "Store and/or access information on a device",
    2: "Strictly Necessary",
    3: "Functional",
    4: "Analytics",
    5: "Marketing",
    6: "Personalization",
    7: "Social Media"
  }
}

Example 2

__tcfapi('getConsentCriteria', null, (data, success) => {console.log(data)}, { vendors: true })

Returns

{
  vendors: {
    1: "Exponential Interactive, Inc d/b/a VDX.tv",
    2: "Captify Technologies Limited",
    3: "affilinet",
    0: "Publisher / Brand"
  }
}

Example 3

__tcfapi('getConsentCriteria', null, (data, success) => {console.log(data)}, { purposes: true })

Returns

{
  purposes: {
    1: "Store and/or access information on a device",
    2: "Strictly Necessary",
    3: "Functional",
    4: "Analytics",
    5: "Marketing",
    6: "Personalization",
    7: "Social Media"
  }
}

Example 4

__tcfapi('getConsentCriteria', null, (data, success) => {console.log(data)}, { purposes: true, vendors: true })

Returns

{
  vendors: {
    1: "Exponential Interactive, Inc d/b/a VDX.tv",
    2: "Captify Technologies Limited",
    3: "affilinet",
    0: "Publisher / Brand"
  },
  purposes: {
    1: "Store and/or access information on a device",
    2: "Strictly Necessary",
    3: "Functional",
    4: "Analytics",
    5: "Marketing",
    6: "Personalization",
    7: "Social Media"
  }
}

getVendorList

The getVendorList command returns the latest global vendor list.

__tcfapi('getVendorList', 2, (result) => {console.log(result)});

Argument Name	Type	Value
command	string	`'getVendorList'`
version	number	(ignored) or `2`
callback(result)	function	`function(result: object)` To return the vendor list.

Argument Name

Type

Value

command

string

'getVendorList'

version

number

(ignored) or 2

callback(result)

function

function(result: object)

To return the vendor list.

Result Object Example

{gvlSpecificationVersion: 2, vendorListVersion: 68, tcfPolicyVersion: 2, lastUpdated: "2020-12-10T16:05:27Z", purposes: {…}, …}
features: {1: {…}, 2: {…}, 3: {…}}
gvlSpecificationVersion: 2
lastUpdated: "2020-12-10T16:05:27Z"
purposes: {1: {…}, 2: {…}, 3: {…}, 4: {…}, 5: {…}, 6: {…}, 7: {…}, 8: {…}, 9: {…}, 10: {…}, 25: {…}, 26: {…}, 27: {…}, 28: {…}, 29: {…}, 30: {…}}
specialFeatures: {1: {…}, 2: {…}}
specialPurposes: {1: {…}, 2: {…}, 25: {…}, 26: {…}}
stacks: {1: {…}, 2: {…}, 3: {…}, 4: {…}, 5: {…}, 6: {…}, 7: {…}, 8: {…}, 9: {…}, 10: {…}, 11: {…}, 12: {…}, 13: {…}, 14: {…}, 15: {…}, 16: {…}, 17: {…}, 18: {…}, 19: {…}, 20: {…}, 21: {…}, 22: {…}, 23: {…}, 24: {…}, 25: {…}, 26: {…}, 27: {…}, 28: {…}, 29: {…}, 30: {…}, 31: {…}, 32: {…}, 33: {…}, 34: {…}, 35: {…}, 36: {…}, 37: {…}, 38: {…}, 39: {…}, 40: {…}, 41: {…}, 42: {…}}
tcfPolicyVersion: 2
vendorListVersion: 68
vendors: {1: {…}, 2: {…}, 4: {…}, 6: {…}, 7: {…}, 8: {…}, 9: {…}, 10: {…}, 11: {…}, 12: {…}, 13: {…}, 14: {…}, 15: {…}, 16: {…}, 18: {…}, 20: {…}, 21: {…}, 22: {…}, 23: {…}, 24: {…}, 25: {…}, 26: {…}, 27: {…}, 28: {…}, 30: {…}, 31: {…}, 32: {…}, 33: {…}, 34: {…}, 36: {…}, 37: {…}, 39: {…}, 40: {…}, 41: {…}, 42: {…}, 44: {…}, 45: {…}, 46: {…}, 47: {…}, 48: {…}, 49: {…}, 50: {…}, 51: {…}, 52: {…}, 53: {…}, 57: {…}, 58: {…}, 59: {…}, 60: {…}, 61: {…}, 62: {…}, 63: {…}, 65: {…}, 66: {…}, 67: {…}, 68: {…}, 69: {…}, 70: {…}, 71: {…}, 72: {…}, 73: {…}, 76: {…}, 77: {…}, 78: {…}, 79: {…}, 80: {…}, 82: {…}, 83: {…}, 84: {…}, 85: {…}, 86: {…}, 87: {…}, 88: {…}, 89: {…}, 90: {…}, 91: {…}, 92: {…}, 93: {…}, 94: {…}, 95: {…}, 97: {…}, 98: {…}, 100: {…}, 101: {…}, 102: {…}, 104: {…}, 108: {…}, 109: {…}, 110: {…}, 111: {…}, 114: {…}, 115: {…}, 119: {…}, 120: {…}, 122: {…}, 124: {…}, 126: {…}, 127: {…}, 128: {…}, 129: {…}, …}

addEventListener

The addEventListener command registers a callback function with the CMP. The listener's callback is triggered when for example the consent string status has changed. The listener is registered with an ID for later removal.

__tcfapi('addEventListener', 2, (tcData, success) => {console.log(tcData)}, [parameter]);

Argument Name	Type	Value
command	string	`'addEventListener'`
version	number	(ignored) or `2`
callback(result)	function	`result (Object, Boolean)`: Object containing the event name or `listenerId` and any data the event may return, Boolean if success
parameter	String	Name of the event to listen to. You can choose the event name from the list in "Events."

Note

If addEventListener command is called without parameter, on every change you should get tcData object based on the specs containing the event listenerId.

If LiveRamps custom events were passed as a parameter. e.g. consentChanged then no listenerId will be returned. You can remove it removeEventListener by passing event name instead of an ID.

removeEventListener

The removeEventListener command removes the event listener.

__tcfapi('removeEventListener', 2, (result) => {console.log(tcData)}, [parameter]);

Argument Name	Type	Value
command	string	`'removeEventListener'`
version	number	(ignored) or `2`
callback(result)	function	`function(result:boolean)` Callback function to remove as a listener, boolean if success.
parameter	number\|string	Unique ID assigned by the CMP to the registered callback (via `addEventListener`) or event name. You can choose the event name from the list in "Events."

gdprApplies

The gdprApplies command allows you to determine if GDPR applies based on the user's geo-location.

__tcfapi('gdprApplies', 2, (result) => {console.log(result)});

Argument Name	Type	Value
command	string	`'gdprApplies'`
version	number	(ignored) or `2`
callback(result)	function	`function(result:boolean)` `True` if TCF details apply for current user.

Argument Name

Type

Value

command

string

'gdprApplies'

version

number

(ignored) or 2

callback(result)

function

function(result:boolean)

True if TCF details apply for current user.

Result Object Example

INFO - (CMP) Proccess command: gdprApplies, parameter: undefined, version: 2
true

consentDataExist

The consentDataExist method will trigger a callback with information if the user interacted with the CMP.

__tcfapi("consentDataExist", 2, (data, success) => { console.log(data)})

Argument Name	Type	Value
command	string	`'consentDataExist'`
version	number	(ignored) or `2`
callback(result)	function	`function(result:boolean)` `True`: if the End user has interacted with the tool `False`: if the End user has not yet interacted with the tool (consent notice)
parameter	Ignored

Example:

When a unique user lands on the page, and not yet interacted with the consent notice (no prior interaction with the tool ) the call back of the API consentDataExist will return false, otherwise it will be true.

accept

The accept method will simulate a user clicking on the accept button. The object can be used for specific purposeIds, vendorIds, legIntPurposeIds, legIntVendorIds and/or specialFeatureIds. If the object is empty all vendors will be accepted.

__tcfapi('accept', 2, (result) => {console.log(result)}, [parameter]);

Argument Name	Type	Value
command	string	`'accept'`
version	number	(ignored) or `2`
callback(result,)	function	`function(result: Void)`
parameter	Array	Object with `purposeIds`, `vendorIds`, `legIntPurposeIds`, `legIntVendorIds` and/or `specialFeatureIds`properties. If none is passed all vendors will be accepted.

__tcfapi('accept', 2, (result) => {console.log(result)});

Examples

Example

For a single IAB Vendor:

By passing the vendorId, the library will look for the mapped purposes to that specific Vendor ID and pass accept to all of them.

If we take the vendor Emerse Sverige AB.

Passing vendorIds: [8] will pass consent to purposeIds: [1, 3, 4].

__tcfapi('accept', 2, (data,result) => {console.log(result)}, {
  vendorIds: [8]
});

For a single non-IAB Vendor:

With regards to non-IAB vendors, you need to pass the purposes mapped to that vendor, depending on what is mapped in the configuration.

Example

From the console if you map the purposes for Twitter to be social media, then passing consent for this individual vendor should be done alongside with the purposes which were mapped in the configuration.

Here we mapped Twitter to request consent for purpose 1 (by default, can not be changed) and purpose 29 Social Media.

In Console:

How it reflects it in the CMP:

Command to pass consent for vendorIds: [10006] and purposesIds: [1, 29].

__tcfapi('accept', 2, (data,result) => {console.log(result)}, {
  vendorIds: [10006],
  purposeIds: [29]
});

Note

Purpose 1 will be passed by default.
Purpose 29 is social media, you can see the custom purposes ids int he console.

reject

The rejected method will simulate a user click on the reject button. The object can be used for specific purposeIds, vendorIds, legIntPurposeIds, legIntVendorIds and/or specialFeatureIds. If the object is empty all vendors will be rejected.

__tcfapi('reject', 2, (result) => {console.log(result)}, [parameter]);

Argument Name	Type	Value
command	string	`'reject'`
version	number	(ignored) or `2`
callback(result)	function	`function(result: Void)`
parameter	Array	Array of vendors with purposes, if none is passed all vendors will be rejected.

__tcfapi('reject', 2, (result) => {console.log(result)});

For a single IAB Vendor:

By passing the vendorId, the library will look for the mapped purposes to that specific Vendor ID and pas accept to all of them.

If we take the vendor Emerse Sverige AB.

Passing vendorIds: [8] will pass consent to purposeId: [1, 3, 4].

__tcfapi('reject', 2, (data,result) => {console.log(result)}, {
  vendorIds: [8]
});

For a single non-IAB Vendor:

With regards to the non-IAB vendors, you need to pass the purposes mapped to that vendor, depending on what is mapped in the configuration.

From the console, if you map the purposes for Twitter to be social media, then passing reject for this individual vendor should be done alongside with the purposes which were mapped in the configuration.

Passing the following command will revoke consent for the vendor Twitter ( vendorId: [10006] and the purpose social purposeId: [29] ):

__tcfapi('reject', 2, (data,result) => {console.log(result)}, {
  vendorIds: [10006],
  purposeIds: [29]
});

Audit ID

getAuditID

The getAuditId command will retrieve the LiveRamp Audit ID of a user. The Audit ID is only present, logged and stored after a user saves its consent preferences.

__tcfapi('getAuditId', 2, (result) => {console.log(result)});

Argument Name	Type	Value
command	string	`'getAuditId'`
version	number	(ignored) or `2`
callback(result)	function	`function(result: string)` `AuditId` of a user.

Argument Name

Type

Value

command

string

'getAuditId'

version

number

(ignored) or 2

callback(result)

function

function(result: string)

AuditId of a user.

resetAuditId

The resetAuditId command will reset the LiveRamp Audit ID.

__tcfapi('resetAuditId', 2, (tcData, success) => {console.log(tcData)});

Argument Name	Type	Value
command	string	`'resetAuditId'`
version	number	(ignored) or `2`
callback(result)	function	`function(result: string)` Auto generated `AuditId`

Argument Name

Type

Value

command

string

'resetAuditId'

version

number

(ignored) or 2

callback(result)

function

function(result: string)

Auto generated AuditId

UI API

showConsentManager

The showConsentManager command will surface the consent manager UI at any given time regardless of consent state.

__tcfapi('showConsentManager', 2, (result) => {console.log(result)}, [parameter]);

Argument Name	Type	Value
command	string	`'showConsentManager'`
version	number	(ignored) or `2`
callback(result)	function	`function(result: Void)` Consent manager will be displayed.
parameter	Ignored

You can embed the API showConsentManager to be triggered from an element on the page.

Example

Example

JavaScript which needs to be included in your environment:

    <script>
        function showConsentManager() {
            __tcfapi('showConsentManager', 2, (result) => {});
        }
    </script>

Embedding the function on an HTML element (e.g., anchor element, button, etc.)

<a href="#" onclick="showConsentManager()"> Show Consent Manager </a>

toggleConsentTool

The toggleConsentTool command will surface the notice screen at any given time regardless of the consent state.

__tcfapi('toggleConsentTool', 2, (result) => {console.log(result)}, [parameter]);

Argument Name	Type	Value
command	string	`'toggleConsentTool'`
version	number	(ignored) or `2`
callback(result)	function	`function(result: Void)` Consent notice or manager will be toggled (i.e. it would be shown or hidden based on current state). If in configuration `noticeConfig.display` is set to `false` consent manager will be displayed else consent notice will be displayed.
parameter	Optional(boolean) If passed it will be used to force consent tool state to show or hide regardless of the current state.

You can embed this API to be triggered to hide or show the consent tool regardless of the current state. At the same time this API can also be used to toggle around consent notice or manager based on the Boolean value of noticeConfig.display in the configuration.

UI Content Language API

setLanguage(code: String)

The setLanguage command will set the Privacy Manager language if the selected language code is in the list of available languages for your configuration. The language will override the configuration of a preferred language.

__tcfapi('changeLanguage', null, null, locale);

Parameters

Name	Type	Description
command	String	Language code to use for the Web SDK Content.

Example

The following API will set the privacy manager language to Dutch:

__tcfapi('changeLanguage', null, (result) => {console.log(result)}, 'nl');

Note

Make sure that the language is included in the CMP configuration through Console.

Language Codes

List of language codes supported by the CMP:

Language	Language Code
Bulgarian	Bg
Catalan	Ca
Chinees	Zh
Swedish	Sv
Slovenian	Sl
Slovak	Sk
Russian	Ru
Romanian	Ro
Portuguese	Pt
Polish	Pl
Norwegian	No
Dutch	Nl
Maltez	Mt
Latvian	Lv
Lithuanian	Lt
Italian	It
Hungarian	Hu
Croatian	Hr
French	Fr
Finnish	Fi
Estonian	Et
Spanish	Es
Czech	Cs
Danish	Da
German	De
Greek	El
Turkish	Tr

Execute a Command from Description Text

There may be a case where you want to invoke the Reject All command from the Privacy Manager UI, but not use the reject all button.

Place the following string in any description text field in Console for Privacy Manager GDPR:

${executeCommand(rejectAll, LINK NAME)}

Example:

${executeCommand(rejectAll, Reject all purposes)}

In this section:

API Functions (GDPR for Web)

Consent Status

Caution

ping

Result Object Example

getFullTCData

Result Object Example

checkConsent

Examples

Note

getConsentCriteria

Examples

getVendorList

Result Object Example

addEventListener

Note

removeEventListener

gdprApplies

Result Object Example

consentDataExist

accept

Examples

Note

reject

Audit ID

getAuditID

resetAuditId

UI API

showConsentManager

Example

toggleConsentTool

UI Content Language API

setLanguage(code: String)

Note

Language Codes

Execute a Command from Description Text

Search results