@iabtcf/core
Advanced tools
Ensures consistent encoding and decoding of TC Signals for the iab. Transparency and Consent Framework (TCF).
Ensures consistent encoding and decoding of IAB's Transparency and Consent Framework (TCF) TC Strings and the stateful persistence of the Transparency and Consent information while providing tools for the handling and manipulation of the TCF Global Vendor List data all free and open sourced (License).
TCModel - Creates a stateful model to store a Transparency and Consent user interaction with all the fields specifed in the TC string encoding schema.
TCModel into a TC string and decodes a TC string into a TCModel
npm
npm install @iabtcf/core --save
yarn
yarn add @iabtcf/core
import {TCModel, TCString, GVL} from '@iabtcf/core';
/**
* the IAB requires CMPs to host their own vendor-list.json files. This must
* be set before creating any instance of the GVL class.
*/
GVL.baseUrl = "http://mydomain.com/cmp/vendorlist";
// create a new TC string
const tcModel = new TCModel(new GVL());
// Some fields will not be populated until a GVL is loaded
tcModel.gvl.readyPromise.then(() => {
// Set values on tcModel...
const encodedString = TCString.encode(tcModel);
console.log(encodedString); // TC string encoded begins with 'C'
}
// take an encoded TC string and decode into a TCModel
const decodedTCModel = TCString.decode(encodedString);
To encode a TCModel a GVL must be included.
import {TCModel} from '@iabtcf/core';
// creates a TCModel
const tcModel = new TCModel();
// to encode you must have a cmpId and cmpVersion
tcModel.cmpId = //{myCMPID}
tcModel.cmpVersion = //{myCMPVersion}
/**
* we now have a TCString assigned with a GVL which will set vendorListVersion,
* tcfPolicyVersion and consentLanguage
*/
import {TCModel} from '@iabtcf/core';
const tcModel = new TCModel();
tcModel.cmpId = // my CMP ID
tcModel.cmpVersion = // my CMP Version
tcModel.consentScreen = // On which 'screen' consent was captured; this is a cmp proprietary number encoded into the TC string
The TCModel leverages a Set style Vector data structure to set consents, optins, allowed, disclosed, and legitimate interest establishment. Properties that leverage this data structure are:
Example with vendorConsents
The vendorConsents property on the TCModel is a Vector. This example illustrates the methods of a Vector. With the exception of the publisherRestrictions, which implements a different type of PurposeRestrictionVector, all of the above Vectors will have this interface and functionality.
// Give Vendor ID 23 consent
tcModel.vendorConsents.set(23);
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
console.log(tcModel.vendorConsents.maxId); // 0
console.log(tcModel.vendorConsents.size); // 0
// 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.has(14)); // true
console.log(tcModel.vendorConsents.has(200)); // false
console.log(tcModel.vendorConsents.maxId); // 102
console.log(tcModel.vendorConsents.size); // 5
// loop through all ids 1 to maxId (102 loops)
tcModel.vendorConsents.forEach((hasConsent, vendorId) => {
// check each id for consent
});
// empty everything
tcModel.vendorConsents.empty();
console.log(tcModel.vendorConsents.has(24)); // false
console.log(tcModel.vendorConsents.maxId); // 0
console.log(tcModel.vendorConsents.size); // 0
A Publisher Restriction is a restriction placed on a Vendor by a publisher limiting the purposes for which that Vendor is allowed to process personal data. The TCModel.publisherRestrictions is an instance of the PurposeRestrictionVector, which is a vector containing PurposeRestrictions's.
Example of setting publisher restrictions
import {TCModel, PurposeRestriction, RestrictionType} from '@iabtcf/core';
// first you must create a PurposeRestriction
const purposeRestriction = PurposeRestriction();
purposeRestriction.purposeId = 2;
purposeRestriction.restrictionType = RestrictionType.NOT_ALLOWED;
// vendorID and restriction
tcModel.publisherRestrictions.add(2000, purposeRestriction);
The GVL class provides two ways to instantiate. Either by passing in a vendor-list.json object to populate it or autoloading a vendor-list.json from a url.
Autoloading a vendor-list.json will accept into the constructor a vendor list version number or if nothing or "LATEST" is passed it will load the latest version of the vendor list. NOTE. You must set the GVL.baseUrl parameter before instantiating a GVL instance. If desired the GVL.latestFilename may be set if vendor-list.json is not used.
Loading default filename
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
// loads 'http://cmp.mysupercoolcmp.com/cmp/vendor-list.json'
const gvl = new GVL();
gvl.readyPromise.then(() => {
// GVL has loaded and it's ready to use
});
Loading with custom filename
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
GVL.latestFilename = 'latest/vendorlist.js';
// loads 'http://cmp.mysupercoolcmp.com/cmp/latest/vendorlist.json'
const gvl = new GVL();
gvl.readyPromise.then(() => {
// GVL has loaded and it's ready to use
});
Autoloading a specific version requires that you both set the GVL.baseUrl static variable and pass into the constructor the version number you wish to load. Optionally if your filename has a version other than vendor-list-v[VERSION].json you may set a different filename with version as GVL.versionedFilename = 'vendorlist[VERSION].json'; and the token [version] will be replaced with the version number you pass into the constructor.
Loading default filename for version
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
// loads 'http://cmp.mysupercoolcmp.com/cmp/archives/vendor-list-v23.json'
const gvl = new GVL(23);
gvl.readyPromise.then(() => {
// GVL has loaded and it's ready to use
});
Changing version name scheme
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
GVL.versionedFilename = 'vendorlist[VERSION].json';
// loads 'http://cmp.mysupercoolcmp.com/cmp/vendorlist23.json'
const gvl = new GVL(23);
gvl.readyPromise.then(() => {
// GVL has loaded and it's ready to use
});
You may also just pass in the json object (not strigified)
import {GVL} from '@iabtcf/core';
const gvl = new GVL(gvljson);
// no need for ready promise because no asynchronous action has occurred
// gvl is ready to use
All vendorlists are published by default as english. There are alternate languages that the iab publishes which are essetnailly a vendor list without the vendors. GVL.baseUrl must be set for langauges changes. To load an alternate you simply call gvl.changeLanguage(/**language*/); langauge is the iso639-1 two-letter langauge code. For the full list of iab provided language translations click here. If desired the GVL.languageFilename may be set if purposes-[LANG].json is not used.
Default filename load
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/';
const gvl = new GVL(gvljson);
// loads the French langauge
gvl.changeLanguage('fr').then(() => {
// French Language GVL is ready for use
});
Changing filename load
import {GVL} from '@iabtcf/core';
const gvl = new GVL(gvljson);
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/';
GVL.langaugeFilename = 'langauges/purp[LANG].json';
// loads the French langauge from 'http://cmp.mysupercoolcmp.com/purpfr.json'
gvl.changeLanguage('fr').then(() => {
// French Language GVL is ready for use
});
A CMP UI may want to group vendors by what purpose they use under what legal basis and/or features. This can be accomplished quite easily by using one of the 6 grouping methods:
getVendorsWithConsentPurpose(purposeId)getVendorsWithFeature(featureId)getVendorsWithFlexiblePurpose(purposId)getVendorsWithLegIntPurpose(purposId)getVendorsWithSpecialFeature(featureId)getVendorsWithSpecialPurpose(purposId)All 6 grouping methods return an IntMap<Vendor> object
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
// loads 'http://cmp.mysupercoolcmp.com/cmp/vendor-list.json'
const gvl = new GVL();
gvl.readyPromise.then(() => {
const vendorMap = gvl.getVendorsWithConsentPurpose(1);
// logs all vendor ids who have specified they require consent for purpose 1
Object.keys(vendorMap).forEach(console.log);
});
If loading a CMP would like to show a subset of the Vendor List a filter may be passed to only work with those vendors on the list.
import {GVL} from '@iabtcf/core';
// only needs to be set once per application as this is a static variable
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
// loads 'http://cmp.mysupercoolcmp.com/cmp/vendor-list.json'
const gvl = new GVL();
gvl.readyPromise.then(() => {
// now this gvl instance only has these 3 vendors
gvl.narrowVendorsTo([1,2,3]);
// will only show the Vendor objects for 1, 2, and 3
console.log(gvl.vendors);
// will only return the vendors within the narrowed vendor list
const vendorsWithLegInt2 = gvl.getVendorsWithLegIntPurpose(2);
});
import {TCString, TCModel} from '@iabtcf/core';
const myTCModel = TCString.decode(encodedTCString);
returns: TCModel
import {TCString, TCModel, GVL} from '@iabtcf/core';
/**
* With v2.0 of the TCF, CMPs are required to host their own vendor-list.json for
* their client-side scripts to consume. This GVL class follows the convention
* outlined in the GVL URL Version scheme. (latest at vendor-list.json and
* version specific at archives/vendor-list-v{vendor-list-version}.json
*/
GVL.baseURL = "http://mydomain.com/cmp/vendorlist";
// we'll get the latest GVL to encode this TCString to
const gvl = new GVL("LATEST");
// have to wait for it to fetch the json
gvl.readyPromise.then(() => {
const tcModel = new TCModel(gvl);
const encodedTCString = TCString.encode(tcModel);
/**
* this will output a default all "no" encoded string to the console at the
* lastest GVL version.
*/
comsole.log(encodedTCString);
});
FAQs
Ensures consistent encoding and decoding of TC Signals for the iab. Transparency and Consent Framework (TCF).
The npm package @iabtcf/core receives a total of 19,035 weekly downloads. As such, @iabtcf/core popularity was classified as popular.
We found that @iabtcf/core demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.