__tcfapi function - getCustomVendorConsents

March 15, 2023 18:38

Sourcepoint has extended the functionality of the IAB's TCF API to offer your organization additional commands that can be used with the __tcfapi() function call. This provides a level of consistency and feature overlap between IAB TCF API and custom function integrations.

The getCustomVendorConsents command enables your organization to handle vendors that participate in the TCF API and custom vendors that do not participate in the TCF API.

Command
Response

Command

ThegetCustomVendorConsents command returns an object that contains information on IAB and custom vendors an end-user consents to, and the legitimate interest and consent purposes mapped to a vendor.

Your organization can call the command through the browser console or Javascript code on a webpage.

Enter the following command directly into the browser tools' console window.

__tcfapi('getCustomVendorConsents', 2, function(data, success) {console.log("getCustomVendorConsents response: ", data, " + ", success);});

...

function show_cvc(data)  {
    var vendors = Object.keys(data.grants);
    var grants = Object.values(data.grants);
    console.log("date created - " + data.dateCreated);
    console.log("new user - " + data.newUser);
    for(i in vendors) {
       var vendor = vendors[i];
       console.log(" ");
       console.log("for vendor - " + vendor);
       console.log(" >> vendor grant - " + grants[i].vendorGrant);
       var purpose_grants = grants[i].purposeGrants;
       var purposes = Object.keys(purpose_grants);
       var purpose_consent = Object.values(purpose_grants);
       for(j in purposes)   {
          console.log(" >> purpose id " + purposes[j] + " has consent given - " + purpose_consent[j]);
       }
    }
    console.log(" ");
    var consented_purposes = data.consentedPurposes;
    for(i in consented_purposes)  {
       var purpose = consented_purposes[i];
       console.log("purpose id " + purpose._id + " is " + purpose.name);
    }
    console.log(" ");
    var consentedCustomVendors = data.consentedVendors;
    for(i in consentedCustomVendors) {
       var custom_vendor = consentedCustomVendors[i];
       console.log("purpose id " + custom_vendor._id + " is " + custom_vendor.name + " and type " + custom_vendor.vendorType);
    }
    console.log(" ");
    var legitimateInterestPurposes = data.legIntPurposes;
    for(i in legitimateInterestPurposes)   {
       var li_purpose = legitimateInterestPurposes[i];
       console.log("legitimate interest purpose id " + li_purpose._id + " is " + li_purpose.name);
    }
 }

 __tcfapi('addEventListener', 2, function(tcdata, success) {
    if(success) {

       // call TCF API getCustomVendorConsent command
       __tcfapi('getCustomVendorConsents', 2, (data, success) => {
          show_cvc(data);
       });

       if (tcdata.eventStatus === 'useractioncomplete') {
          // call code when user has made an action
       } else if (tcdata.eventStatus === 'tcloaded') {
          // call code when consent string has loaded
       } else if (tcdata.eventStatus === 'cmpuishown') {
          // call code when cmp message is shown
       }
    }
 });
 ...

Note: This example uses the addEventListener that allows your organization to listen to specific events (e.g. an end-user changes their consent), and automatically perform custom actions in response. The addEventListener is described in this article.

Response

The response is a JSON object that contains the consent data and this is divided into four parts:

Attribute	Type	Value
consentedPurposes	Array	Lists the purposes that apply to the end-user
consentedVendors	Array	Lists the custom vendors in the vendor list that apply to the end-user
grants	Object	Lists the consented purposes for each vendor
legIntPurposes	Array	Lists the purposes that are listed as legitimate interest for all vendors

Object {
   dateCreated: "2022-02-28T15:11:26.129Z"
   newUser: true
   consentedPurposes {
      0: {_id: "60925aa29ccb1d3420efac20", name: "Select basic ads"}
      1: {_id: "60925aa29ccb1d3420efac2e", name: "Measure ad performance"}
      2: {_id: "60925aa29ccb1d3420efac0b", name: "Apply market research to generate audience insights"}
      3: {_id: "60925aa29ccb1d3420efabf7", name: "Select personalised content"}
      4: {_id: "60925aa29ccb1d3420efabfe", name: "Create a personalised content profile"}
      5: {_id: "60925aa29ccb1d3420efac05", name: "Measure content performance"}
      6: {_id: "60925aa29ccb1d3420efac19", name: "Select personalised ads"}
      7: {_id: "60925aa29ccb1d3420efac27", name: "Create a personalised ads profile"}
      8: {_id: "60925aa29ccb1d3420efac36", name: "Store and/or access information on a device"}
      9: {_id: "60925aa29ccb1d3420efac12", name: "Develop and improve products"}
   }
   consentedVendors:
      0: {_id: "5f3bc0d7b8e05c606f3dfc27", name: "Artefact S.A.", vendorType: "CUSTOM"}
   grants:
      5e7ced57b8e05c47e418b73c:    
         purposeGrants: {
            60925aa29ccb1d3420efabf7: true,
            60925aa29ccb1d3420efabfe: true,
            60925aa29ccb1d3420efac05: true,
            60925aa29ccb1d3420efac0b: true,
            60925aa29ccb1d3420efac12: true,
            60925aa29ccb1d3420efac19: true,
            60925aa29ccb1d3420efac20: true,
            60925aa29ccb1d3420efac27: true,
            60925aa29ccb1d3420efac2e: true,
            60925aa29ccb1d3420efac36: true,
            62092ef7dbaa6007ad004677: true 
         },
         vendorGrant: true
      5e7ced57b8e05c47e418b73c:    
         purposeGrants: {
            60925aa29ccb1d3420efabf7: true,
            60925aa29ccb1d3420efabfe: true,
            60925aa29ccb1d3420efac05: true,
            60925aa29ccb1d3420efac0b: true,
            60925aa29ccb1d3420efac12: true,
            60925aa29ccb1d3420efac19: true,
            60925aa29ccb1d3420efac20: true,
            60925aa29ccb1d3420efac27: true,
            60925aa29ccb1d3420efac2e: true,
            60925aa29ccb1d3420efac36: true,
            62092ef7dbaa6007ad004677: true 
         },
         vendorGrant: true
      5f1aada6b8e05c306c0597d7:    
         purposeGrants: {
            60925aa29ccb1d3420efabf7: true,
            60925aa29ccb1d3420efabfe: true,
            60925aa29ccb1d3420efac0b: true,
            60925aa29ccb1d3420efac12: true,
            60925aa29ccb1d3420efac19: true,
            60925aa29ccb1d3420efac20: true,
            60925aa29ccb1d3420efac27: true,
            60925aa29ccb1d3420efac2e: true,
            60925aa29ccb1d3420efac36: true,
            62092ef7dbaa6007ad004677: true
         },
         vendorGrant: true
      5f3bc0d7b8e05c606f3dfc27:    
         purposeGrants: {
            60925aa29ccb1d3420efabf7: true,
            60925aa29ccb1d3420efabfe: true,
            60925aa29ccb1d3420efac05: true,
            60925aa29ccb1d3420efac0b: true,
            60925aa29ccb1d3420efac12: true,
            60925aa29ccb1d3420efac19: true,
            60925aa29ccb1d3420efac20: true,
            60925aa29ccb1d3420efac27: true,
            60925aa29ccb1d3420efac2e: true,
            60925aa29ccb1d3420efac36: true,
            62092ef7dbaa6007ad004677: true
         },
         vendorGrant: true
      5e37fc3e56a5e6614776722e:    
         purposeGrants: {
            60925aa29ccb1d3420efac2e: true,
            60925aa29ccb1d3420efac36: true,
            62092ef7dbaa6007ad004677: true
         },
         vendorGrant: true
   legIntPurposes: Array(6)
      0: {_id: "6011ea75c5d9c787531b3ede", name: "Apply market research to generate audience insights"}
      1: {_id: "6011ea75c5d9c787531b3ee6", name: "Select personalised content"}
      2: {_id: "6011ea75c5d9c787531b3eed", name: "Create a personalised content profile"}
      3: {_id: "6011ea75c5d9c787531b3ef5", name: "Measure content performance"}
      4: {_id: "6011ea75c5d9c787531b3f05", name: "Create a personalised ads profile"}
      5: {_id: "6011ea75c5d9c787531b3f18", name: "Develop and improve products"}
}

Every array element in the consentedPurposes array is an object that lists the purposes that apply to the end-user. The model for each object is as follows:

Key	Type	Value
`_id`	String	The purpose's `Purpose ID`
`name`	String	Purpose description as described in vendor list

index: {_id: "purpose id", name: "purpose description"}

consentedPurposes: Array(10)
   0: {_id: "60925aa29ccb1d3420efac20", name: "Select basic ads"}
   1: {_id: "60925aa29ccb1d3420efac2e", name: "Measure ad performance"}
   2: {_id: "60925aa29ccb1d3420efac0b", name: "Apply market research to generate audience insights"}
   3: {_id: "60925aa29ccb1d3420efabf7", name: "Select personalised content"}
   4: {_id: "60925aa29ccb1d3420efabfe", name: "Create a personalised content profile"}
   5: {_id: "60925aa29ccb1d3420efac05", name: "Measure content performance"}
   6: {_id: "60925aa29ccb1d3420efac19", name: "Select personalised ads"}
   7: {_id: "60925aa29ccb1d3420efac27", name: "Create a personalised ads profile"}
   8: {_id: "60925aa29ccb1d3420efac36", name: "Store and/or access information on a device"}
   9: {_id: "60925aa29ccb1d3420efac12", name: "Develop and improve products"}
   10: {_id: '62e3b7976b7b52047dc09de2', name: 'Test custom purpose'}

Every array element in the consentedVendors array is an object that lists the custom vendors in the vendor list that apply to the end-user. The model for each object is as follows:

Key	Type	Value
`_id`	String	The custom vendor's `Vendor ID`
`name`	String	Custom vendor name as described in vendor list
`vendorType`	String	The vendor type, if the vendor is custom or affiliated to the IAB

index: {_id:"vendor id", name:"vendor name", vendorType:"vendor type"}

consentedVendors: Array(5)
    0: {_id: '5ff4d000a228633ac048be41', name: 'Game Accounts', vendorType: 'CUSTOM'}
    1: {_id: '5ed0eb688a76503f1016578f', name: 'Google Ads Remarketing', vendorType: 'CUSTOM'}
    2: {_id: '5e542b3a4cd8884eb41b5a72', name: 'Google Analytics', vendorType: 'CUSTOM'}
    3: {_id: '604b52a487b9d0678590aead', name: 'Google Floodlight', vendorType: 'CUSTOM'}
    4: {_id: '5f3709d0fda30f43c04e2cfb', name: 'Insticator', vendorType: 'CUSTOM'}
    length: 5

Every property in the grants object is a vendor on your vendor list (identified by its vendor_id) and contains the applicable purposes and the consent status for that vendor. The model for each object is as follows:

Key	Type	Value
`purposeGrants`	Object	Contains all applicable purposes and whether consent was given from the end-user. See below
`vendorGrant`	Boolean	`true` if end-user granted consent to all applicable purposes for the vendor `false` if end-user has not given consent to one or more applicable purposes for the vendor

The purposeGrants object contains all applicable purposes (identified by its purpose_id) for the vendor and whether consent was given from the end-user. The model for each object is as follows:

Key	Type	Value
`purpose_id`	Boolean	`true` if the end-user has granted consent for the purpose `false` if the end-user has not granted consent for the purpose

vendor_id: {vendorGrant: status, purposeGrants: { "purpose_id 1": status, "purpose_id 2": status, ...}}

grants:
  5e7ced57b8e05c47e418b73b:
    purposeGrants: {
      62bb62d24136b805f13d755b: true,
      62bb62d24136b805f13d756a: true,
      62bb62d24136b805f13d757e: true,
      62bb62d24136b805f13d7560: true,
      62bb62d24136b805f13d7565: true,
      62bb62d24136b805f13d7574: true,
      62bb62d24136b805f13d7588: false,
      62e3b7976b7b52047dc09de2: true
    },
    vendorGrant: false
  5e542b3a4cd8884eb41b5a72:
    purposeGrants: {
      62bb62d24136b805f13d755b: true,
      62bb62d24136b805f13d756a: true,
      62bb62d24136b805f13d7560: true,
      62bb62d24136b805f13d7565: true,
      62e3b7976b7b52047dc09de2: true
    },
    vendorGrant: true

Every array element in the LegIntPurposes array is an object that lists a purpose who uses legitimate interest as a legal basis for at least one vendor on your vendor list. The model for each object is as follows:

Key	Type	Value
`_id`	String	The purpose's `Purpose ID`
`name`	String	Purpose description as described in vendor list

index: {_id: "purpose id", name: "purpose description"}

legIntPurposes: Array(6)
   0: {_id: "6011ea75c5d9c787531b3ede", name: "Apply market research to generate audience insights"}
   1: {_id: "6011ea75c5d9c787531b3ee6", name: "Select personalised content"}
   2: {_id: "6011ea75c5d9c787531b3eed", name: "Create a personalised content profile"}
   3: {_id: "6011ea75c5d9c787531b3ef5", name: "Measure content performance"}
   4: {_id: "6011ea75c5d9c787531b3f05", name: "Create a personalised ads profile"}
   5: {_id: "6011ea75c5d9c787531b3f18", name: "Develop and improve products"}

Was this article helpful?

0 out of 0 found this helpful

__tcfapi function - getCustomVendorConsents

Command

Response

Articles in this section