IAB Transparency and Consent Framework (TCF) Tool Suite

You can extend the window.__tcfapi functionality by passing a map of custom commands to the CmpApi constructor.

Requirements:

• Custom functions must accept a callback as the first parameter.
• The CMP is responsible for validating and handling errors within these functions.

Middleware Pattern: Starting from version 1.1.0, if a custom command name overlaps with a built-in command ("ping", "getTCData", "getInAppTCData", "getVendorList"), the custom command acts as middleware. It receives the built-in command's response and must call a next() function to pass the response along to the original caller.

import {CmpApi} from '@iabtechlabtcf/cmpapi';

const cmpApi = new CmpApi(1, 3, false, {
  // Standard custom command
  'bingo': (callback, dogName) => {
    callback(`There was a farmer who had a dog, and ${dogName} was his name-o`);
  },

  // Middleware for a built-in command
  'getTCData': (next, tcData, status) => {
    // Note: when used with 'removeEventListener', tcData might be a boolean
    if (typeof tcData !== 'boolean') {
      tcData.reallyImportantExtraProperty = true;
    }
    // You MUST call next() or the caller's callback will never execute
    next(tcData, status);
  },
});

// Calling a custom command via the global __tcfapi
__tcfapi('bingo', 2, (lyrics, success) => {
  if(success) console.log(lyrics);
}, 'Bingo');

The TCModel uses a Vector data structure (similar to a JavaScript Set) to manage consents, opt-ins, and restrictions. This applies to properties like vendorConsents, purposeConsents, specialFeatureOptins, and various publisher properties.

Common Vector methods include:

• .set(id) or .set([ids]): Add a single ID or an array of IDs.
• .has(id): Check if an ID is present.
• .unset(id): Remove an ID.
• .empty(): Clear all IDs.
• .size: Get the number of elements.
• .maxId: Get the highest ID in the vector.
• .forEach((value, id) => ...): Iterate through the vector.

// Give Vendor ID 24 consent
tcModel.vendorConsents.set(24);

console.log(tcModel.vendorConsents.has(24)); // true
console.log(tcModel.vendorConsents.maxId); // 24
console.log(tcModel.vendorConsents.size); // 1

// remove vendor 24
tcModel.vendorConsents.unset(24);
console.log(tcModel.vendorConsents.has(24)); // false

// give a group of vendors consent
tcModel.vendorConsents.set([24, 14, 24, 100, 102]);
console.log(tcModel.vendorConsents.has(24)); // true
console.log(tcModel.vendorConsents.maxId); // 102
console.log(tcModel.vendorConsents.size); // 5

// loop through all ids 1 to maxId
tcModel.vendorConsents.forEach((hasConsent, vendorId) => {
  // check each id for consent
});

// empty everything
tcModel.vendorConsents.empty();

The GVL (Global Vendor List) class can be instantiated in three ways: by autoloading the latest version, autoloading a specific version, or passing a pre-loaded JSON object.

Important: When autoloading, you must set the static GVL.baseUrl property before creating an instance. Use gvl.readyPromise to ensure the asynchronous loading is complete before accessing data.

Autoloading Latest

Set GVL.baseUrl. If GVL.latestFilename is set, it will use that instead of the default vendor-list.json.

Autoloading Specific Version

Pass the version number to the constructor. You can customize the filename pattern using GVL.versionedFilename (use the [VERSION] token).

Passing JSON Object

If you already have the vendor-list.json object, pass it directly to the constructor. This is synchronous and does not require waiting for readyPromise.

import {GVL} from '@iabtechlabtcf/core';

// Autoload latest
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
const gvl = new GVL();
await gvl.readyPromise;

// Autoload specific version
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
const gvlVersioned = new GVL(23);
await gvlVersioned.readyPromise;

// Pass object directly
const gvlFromObject = new GVL(gvljson);

The GVL class acts as a manager for the Global Vendor List JSON data. It handles fetching the JSON from a configured baseUrl, caching the results (both the vendor list and language translations) to optimize performance, and providing high-level accessors to group vendors by their declared Purposes or Features.

Lifecycle:

1. Configuration: Set GVL.baseUrl.
2. Instantiation: Create new GVL(...).
3. Resolution: Wait for gvl.readyPromise to resolve.
4. Usage: Access gvl.vendors, gvl.purposes, or use helper methods like getVendorsWithPurpose().

Caching:

• The class maintains static caches for both the vendor lists (by version) and language translations.
• You can manually clear these using GVL.emptyCache(version?) or GVL.emptyLanguageCache(lang?).

// Typical usage pattern
GVL.baseUrl = 'https://my-cache.com/';
const gvl = new GVL();

gvl.readyPromise.then(() => {
  console.log('GVL is ready:', gvl.vendorListVersion);
  console.log('Vendors:', gvl.vendors);
});