This library is DEPRECATED and will not be maintained

Please use https://github.com/IABTechLab/iabgpp-es instead

Purpose

A client library to construct IAB's Global Privacy Platform (GPP) strings

This library includes support for:

| Section ID | Client-side API Prefix | Description | Supported | | ---------- | ---------------------- | ----------------------------------------- | --------- | | 1 | tcfeuv1 | EU TCF v1 section (deprecated) | N/A | | 2 | tcfeuv2 | EU TCF v2 section | Not yet | | 3 | GPP | Header section (REQUIRED, see note below) | Not yet | | 4 | -- | GPP signal integrity section | Not yet | | 5 | tcfca | Canadian TCF section | Not yet | | 6 | uspv1 | USPrivacy String (Unencoded Format) | Yes | | 7 | usnat | US - national section | Not yet | | 8 | usca | US - California section | Yes | | 9 | usva | US - Virginia section | Not yet | | 10 | usco | US - Colorado section | Not yet | | 11 | usut | US - Utah section | Not yet | | 12 | usct | US - Connecticut section | Not yet |

Getting started

Installation

Before we get started, you'll need to install Node and Yarn or npm, and create a directory for your project. Then, install the library using Yarn:

yarn add @paginar/gppstring

Or when using npm run:

npm install @paginar/gppstring

The library can be used in CommonJS & ES6/ESM environments. To use the CJS version:

let {
  UspcaSection,
  GPPString,
} = require("@paginar/gppstring/dist/cjs/index.cjs");

To use the ESM version:

import { UspcaSection, GPPString } from "@paginar/gppstring/dist/esm/index.mjs";

Creating a GPP string

In order to create a GPP string, you first need to create & configure each of the Sections you want to support.

For example if your application needs to support CPRA (for details see the California's privacy rights act spec) you would build a uspca section object, assigning the appropiate values to each user consent

import { UspcaSection, GPPString } from "@paginar/gppstring/dist/esm/index.mjs";

let uspca = new UspcaSection.Builder()
  .setSaleOptOutNotice(0)
  .setSharingOptOutNotice(1)
  .setSensitiveDataLimitUseNotice(1)
  .setSaleOptOut(1)
  .setSharingOptOut(1)
  .setSensitiveDataProcessing([0, 0, 0, 0, 0, 0, 0, 0, 0])
  .setKnownChildSensitiveDataConsents([0, 0])
  .setPersonalDataConsents(0)
  .setMspaCoveredTransaction(0)
  .setMspaOptOutOptionMode(0)
  .setMspaServiceProviderMode(0)
  .build();

let gppString = new GPPString.Builder().addSection(uspca).build();
console.log(gppString.encode2Base64Websafe())

In the console you should see the output as a base64-websafe string: "DBABBa~BAAAAAAA"

Examples

See the /examples folder for CommonJS & ESM examples. Also most source files have Jest tests (/src/**/*.test.js) files which should prove useful.

Caveats

• The base64-websafe encoding does not match 100% the examples given in the spec. This may be due to an improper padding (we are splicing the bit string into 6 bit chars, and padding the remainder with "0").
  • 0000110000010000000000010011 > DBABM (not DBABMA)
  • 000011000001000000000010001101011 > DBACNY (not DBACNYA)
  • 000011000001000000000001100011110000 > DBABdq (not DBABjw)

To do

• Add all other sections
• Add console logging (with different log levels)
• Create the localStorage key names (ie IABGPP_8_String)
• GPP String decoder function to assist in debugging? (:thumbsdown:)

Contributors

• Juan de Tomaso https://github.com/juandeto