![InteractiveAdvertisingBureau](https://circleci.com/gh/InteractiveAdvertisingBureau/iabtcf-es.svg?style=shield)
@iabtechlabtcf/core
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).
Installation
npm
npm install @iabtechlabtcf/core --save
yarn
yarn add @iabtechlabtcf/core
Using
This example demonstrates the basic use case of a CMP creating a "default all-no" TC string.
import {TCModel, TCString, GVL} from '@iabtechlabtcf/core';
GVL.baseUrl = "http://mydomain.com/cmp/vendorlist";
const tcModel = new TCModel(new GVL());
tcModel.gvl.readyPromise.then(() => {
const encodedString = TCString.encode(tcModel);
console.log(encodedString);
});
const decodedTCModel = TCString.decode(encodedString);
TCModel
Creating a new TCModel
To encode a TCModel
a GVL
must be included.
import {TCModel} from '@iabtechlabtcf/core';
const tcModel = new TCModel();
tcModel.cmpId =
tcModel.cmpVersion =
CMP Meta Fields
This exmple shows how to set the basic fields that all TC strings need to have set.
import {TCModel} from '@iabtechlabtcf/core';
const tcModel = new TCModel();
tcModel.cmpId =
tcModel.cmpVersion =
tcModel.consentScreen =
Vectors
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:
- Vendors
vendorConsents
vendorLegitimateInterests
vendorsAllowed
vendorsDisclosed
- Global Purposes
purposeConsents
purposeLegitimateInterests
- Special Feature Opt-Ins
- Publisher
publisherConsents
publisherCustomConsents
publisherLegitimateInterests
publisherCustomLegitimateInterests
publisherRestrictions
- This Vector is a special
PurposeRestrictionVector
of PurposeRestrictions
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.
tcModel.vendorConsents.set(24);
console.log(tcModel.vendorConsents.has(24));
console.log(tcModel.vendorConsents.maxId);
console.log(tcModel.vendorConsents.size);
tcModel.vendorConsents.unset(24);
console.log(tcModel.vendorConsents.has(24));
console.log(tcModel.vendorConsents.maxId);
console.log(tcModel.vendorConsents.size);
tcModel.vendorConsents.set([24, 14, 24, 100, 102]);
console.log(tcModel.vendorConsents.has(24));
console.log(tcModel.vendorConsents.has(14));
console.log(tcModel.vendorConsents.has(200));
console.log(tcModel.vendorConsents.maxId);
console.log(tcModel.vendorConsents.size);
tcModel.vendorConsents.forEach((hasConsent, vendorId) => {
});
tcModel.vendorConsents.empty();
console.log(tcModel.vendorConsents.has(24));
console.log(tcModel.vendorConsents.maxId);
console.log(tcModel.vendorConsents.size);
Setting Publisher Restrictions
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 '@iabtechlabtcf/core';
const purposeRestriction = new PurposeRestriction();
purposeRestriction.purposeId = 2;
purposeRestriction.restrictionType = RestrictionType.NOT_ALLOWED;
tcModel.publisherRestrictions.add(2000, purposeRestriction);
GVL
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.
Autoload latest vendor-list.json
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 '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
const gvl = new GVL();
gvl.readyPromise.then(() => {
});
Loading with custom filename
import {GVL} from '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
GVL.latestFilename = 'latest/vendorlist.js';
const gvl = new GVL();
gvl.readyPromise.then(() => {
});
Autoload specific version vendor-list.json
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 '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
const gvl = new GVL(23);
gvl.readyPromise.then(() => {
});
Changing version name scheme
import {GVL} from '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
GVL.versionedFilename = 'vendorlist[VERSION].json';
const gvl = new GVL(23);
gvl.readyPromise.then(() => {
});
Pass vendor-list.json object
You may also just pass in the json object (not strigified)
import {GVL} from '@iabtechlabtcf/core';
const gvl = new GVL(gvljson);
Change GVL Language
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 '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/';
const gvl = new GVL(gvljson);
gvl.changeLanguage('fr').then(() => {
});
Changing filename load
import {GVL} from '@iabtechlabtcf/core';
const gvl = new GVL(gvljson);
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/';
GVL.langaugeFilename = 'langauges/purp[LANG].json';
gvl.changeLanguage('fr').then(() => {
});
Cloning a GVL with a Non-Default language
When cloning a GVL with a non-default language, make sure that any prior changeLanguage
call is resolved. If changeLanguage has not yet resolved, clone
will make an http request for the current language but will have no indication of resolving that request since it is synchronous.
import {GVL} from '@iabtechlabtcf/core';
const gvl = new GVL();
gvl.changeLanguage('fr').then(() => {
const clone = gvl.clone();
})
const someAsyncFunction = async () => {
await gvl.changeLanguage('fr');
const clone = gvl.clone();
}
Get only vendors with a specific feature or purpose under legal basis
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 '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
const gvl = new GVL();
gvl.readyPromise.then(() => {
const vendorMap = gvl.getVendorsWithConsentPurpose(1);
Object.keys(vendorMap).forEach(console.log);
});
Narrow the list of vendors
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 '@iabtechlabtcf/core';
GVL.baseUrl = 'http://cmp.mysupercoolcmp.com/cmp/';
const gvl = new GVL();
gvl.readyPromise.then(() => {
gvl.narrowVendorsTo([1,2,3]);
console.log(gvl.vendors);
const vendorsWithLegInt2 = gvl.getVendorsWithLegIntPurpose(2);
});
TCString
Decode an IAB TC String
import {TCString, TCModel} from '@iabtechlabtcf/core';
const myTCModel = TCString.decode(encodedTCString);
returns: TCModel
Encode an IAB TC String
import {TCString, TCModel, GVL} from '@iabtechlabtcf/core';
GVL.baseUrl = "http://mydomain.com/cmp/vendorlist";
const gvl = new GVL("LATEST");
gvl.readyPromise.then(() => {
const tcModel = new TCModel(gvl);
const encodedTCString = TCString.encode(tcModel);
console.log(encodedTCString);
});
Decoding A Segment At A Time
It is possible to pass a reference to an already created TCModel
and add individual segments to the model. An important use case for this is if using a globally-scoped TC string and storing the Publisher TC Segment separately in a first-party cookie.
import {TCString, Segment} from '@iabtechlabtcf/core';
const publisherTCSegment = getCookie('euconsent-ptc');
let tcModel;
getGlobalTCString().then((encodedTCString) => {
tcModel = TCString.decode(encodedTCString);
TCString.decode(publisherTCSegment, tcModel);
});
Encoding Options
Options may be passed to the encoder to override defaults. In most cases the encoder can figure out what segments to include but if the string is surfaced to vendors or for storing in a cookie the encoding is slightly different. The @iabtechlabtcf/cmpapi
handles this difference and CMPs don't need to worry about it.
import {TCString, Segment} from '@iabtechlabtcf/core';
const cmpApiEncodedString = TCString.encode(tcModel, { isForVendors: true });
const encodingOptions = {
segments: [
Segment.CORE,
Segment.VENDORS_DISCLOSED,
Segment.VENDORS_ALLOWED,
Segment.PUBLISHER_TC,
]
}
const customEncodedString = TCString.encode(tcModel, encodingOptions);
Encoding a Publisher TC Segment
By default if the TCModel.isServiceSpecific = true
then encoding a string will include the publisherTC segment. But if TCModel.isServiceSpecific = false
then the segment should only be surfaced through the __tcfapi
interface and not saved to the global cookie. However, one will need a way to access and save the publisher TC segment separately from the main TC String to store as a first-party cookie. In that case you can use the EncodingOptions
to generate only a Publisher TC segment.
const encodingOptions = {
segments: [Segment.PUBLISHER_TC]
}
const publisherTCSegment = TCString.encode(tcModel, encodingOptions);