__tcfapi getCustomVendorConsents API

The Sourcepoint Consent Management Platform (CMP) is designed to enable publishers and advertisers to control the onsite delivery of first and third party scripts based on the users consent decisions. This article covers the getCustomVendorConsents command, which is designed to amend the standard mechanisms provided by the IAB's TCFv2 with an API to return an additional data set to handle a broader range of use cases. Specifically, the getCustomVendorConsents API enables publishers and advertiser to handle Custom Vendors that are not are not participating in the TCFv2. However, the getCustomVendorConsents command utilizes the TCFv2 __tcfapi function to provide a level of consistency and feature overlap between IAB TCFv2 and Custom Vendor integrations.

The __tcfapi function utilizes the following arguments to return Custom Vendor data sets.

argument name

type

value

command

string

'getCustomVendorConsents'

version

integer

2

callback

function

(vendorConsents: vendorConsents, success: boolean)

Below is an example of the getCustomConsentData command being run in the javascript console:

__tcfapi('getCustomVendorConsents', 2, function(vendorConsents,success){
if(success){
//do something for success
console.log(vendorConsents);
}
else{
//do something else
}
});

Data the __tcfapi getCustomConsentData API returns

The command returns user specific Custom Consent data in the vendorConsents JSON object. The object contains information on the purposes and vendors a user has consented to, the legitimate interested purposes a user has not objected to, as well as the status information on purposes that are mapped to a specific vendor on the vendor list. Below is the format of the vendorConsents JSON Object.

vendorConsents={
/**
* returns information on the purposes a users has consented to
* includes IAB TCFv2 Purposes and Custom Purposes
* _id - Sourcepoint internal Purpose ID, specific to each vendor list
* name - Sourcepoint Purpose Name as defined in each vendor list
*/
consentedPurposes: {
_id: String,
name: String,
},
/**
* returns information on the vendors a users has consented to
* includes Custom Purposes
* _id - Sourcepoint internal vendor ID, unique across vendor list
* name - Sourcepoint internal Vendor Name
*/
consentedVendors: {
_id: String,
name: String,
vendorType: String,
},
/**
* returns information on purposes that are mapped to a vendor
* purposeGrants - indicates the consent and legitimate interst status for all purposes that are mapped to a vendor
* vendorGrant - indicates if a vendor has consent or legitmate interest for all purposes the vendor is matched to
*/
grants: {
'Vendor ID':{
purposeGrants:{
'Purpose ID':Boolean,
},
},
vendorGrant: Boolean,
},
/**
* returns information on the purposes that are classified as legitimate interest in the vendor list
* includes IAB TCFv2 Purposes and Custom legitimate interest Purposes a user has not objected to
* _id - Sourcepoint internal Purpose ID, specific to each vendor list
* name - Sourcepoint Purpose Name as defined in each vendor list
*/
legIntPurposes: {
id: String",
name: String,
}
}

Using getCustomConsentData

To retrieve the users Custom Consent Data, the function below can be called to return the vendorConsents JSON object.

__tcfapi('getCustomVendorConsents', 2, function(vendorConsents, success) {});

The function below will print the user's consent string to the console and is useful troubleshooting tool.

__tcfapi('getCustomVendorConsents', 2, function(vendorConsents, success) {
console.log(vendorConsents);
});

Combining getCustomVendorCommand with __tcfapi addeventlistener command

The below function combines the getCustomVendorConsents command with the TCFv2 provided addEventListener argument for __tcfapi. By way of using the addEventListener command in conjunction with getCustomVendorConsents the function only returns the data after the user has completed their consent action. Using this function is a convenient way retrieving Custom Vendor consents in sync with IAB TCFv2 Vendor consent.

__tcfapi('addEventListener', 2, function (tcData, success) {
if (tcData.eventStatus === 'tcloaded' || tcData.eventStatus === 'useractioncomplete') {
__tcfapi('getCustomVendorConsents', 2, (data) => console.log(data))
}
});