Overview

Browser SDK V3 is a lightweight headless library which you can integrate with your own custom user interface for consent management

💡 The SDK includes full TypeScript definitions for all exported classes and methods.

Table of Contents

• Installing
  • Package manager
• Example
• Usercentrics API
  • Applying Consent
    • acceptAllConsents
    • denyAllConsents
    • updateServiceConsent
    • updateServicesConsents
    • updateCategoryConsent
    • updateCategoriesConsents
    • saveConsents
  • Data
    • getServices
    • getServicesBaseInfo
    • getCategories
    • getLanguages
  • Other methods
    • changeLanguage
    • areAllConsentsAccepted
    • areAllConsentsDenied
    • getIsConsentRequired
• Implementation Examples
• Building your custom TCF UI
• License

Installing

Package manager

Using npm:

$ npm install @usercentrics/cmp-web-sdk

Using yarn:

$ yarn add @usercentrics/cmp-web-sdk

Once the package is installed, you can import the library using import or require approach:

import WebSdk, {GdprWebSdk} from '@usercentrics/cmp-web-sdk'

You can also use the default export, for a more generic approach:

import WebSdk from '@usercentrics/cmp-web-sdk';

If you use require for importing, only default export is available:

const WebSdk = require('@usercentrics/cmp-web-sdk');

For some bundlers and some ES6 linters you may need to do the following:

import { default as WebSdk } from '@usercentrics/cmp-web-sdk';

Example

Initializing the generic SDK

import WebSdk from '@usercentrics/cmp-web-sdk';

(async () => {
    // Create the SDK instance
    const webSdk = new WebSdk();
    const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID'); // Initialize the SDK with your SettingsId
})();

Initializing the GDPR-specific SDK

import { GdprWebSdk } from '@usercentrics/cmp-web-sdk';

(async () => {
    // Create the SDK instance
    const webSdk = new GdprWebSdk();
    // Initialize the SDK with your SettingsId
    const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID'); 
})();

Initializing the TCF-specific SDK

import { TcfWebSdk } from '@usercentrics/cmp-web-sdk';

(async () => {
    // Create the SDK instance
    const webSdk = new TcfWebSdk();
    // Initialize the SDK with your SettingsId
    const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID'); 
})();

Initializing the US-specific SDK

import { UsWebSdk } from '@usercentrics/cmp-web-sdk';

(async () => {
    // Create the SDK instance
    const webSdk = new UsWebSdk();
    // Initialize the SDK with your SettingsId
    const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID');
})();

Usercentrics API

Applying Consent

acceptAllConsents

await webSdk.acceptAllConsents();

denyAllConsents

await webSdk.denyAllConsents();

updateServiceConsent

Update a single service consent

await webSdk.updateServiceConsent({
    id: 'SERVICE_ID',
    consent: true, // or false
});

updateServicesConsents

Update multiple services consents

await webSdk.updateServicesConsents([
  {
    id: 'SERVICE_ID_1',
    consent: true, // or false
  },
  {
    id: 'SERVICE_ID_2',
    consent: false, // or true
  }
]);

updateCategoryConsent

Update a Category consent

await webSdk.updateCategoryConsent({
  id: 'CATEGORY_ID',
  consent: true, // or false
});

updateCategoriesConsents

Update multiple categories consents

await webSdk.updateCategoriesConsents([
  {
    id: 'CATEGORY_ID_1',
    consent: true, // or false
  },
  {
    id: 'CATEGORY_ID_2',
    consent: false, // or true
  },
]);

saveConsents

Note: Consent usage All of the above methods just change the consent state internally to persist the user decision (e.g. after a save consent button click by the user) you need to persist/save the consents

await webSdk.saveConsents();

Data

getServices

await webSdk.getServices();

getServicesBaseInfo

await webSdk.getServicesBaseInfo();

getCategories

await webSdk.getCategories();

getLanguages

await webSdk.getLanguages();

Other methods

changeLanguage

Change the language to a supported language For the list of supported languages, please refer to getLanguages

await webSdk.changeLanguage('en');

areAllConsentsAccepted

Returns true if all the consents are accepted

const allConsentsAccepted = await webSdk.areAllConsentsAccepted();

areAllConsentsDenied

Returns true if all the consents are denied

const allConsentsDenied = await webSdk.areAllConsentsDenied();

getIsConsentRequired

Returns true if a user decision is needed

const isConsentRequired = await webSdk.getIsConsentRequired();

Implementation Examples

GDPR

// import GDPR optimized GdprWebSdk
import { GdprWebSdk, GdprCmpController, UiView } from '@usercentrics/cmp-web-sdk';

// Vanilla JS view
class CmpView {
  private cmpController: GdprCmpController;
  private cmpElement: HTMLDivElement;

  constructor(cmpController: GdprCmpController) {
    this.cmpController = cmpController;
  }

  public async init() {
    // create and attach the ui view
      
    const cmpElement = document.createElement('div');
    cmpElement.id = 'cmp';

    if (typeof cmpElement.attachShadow === 'function') {
      // optional: attach shadow
      cmpElement.attachShadow({ mode: 'open' });
    }

    this.cmpElement = (cmpElement.shadowRoot as HTMLDivElement) || cmpElement;
    this.setView(this.cmpController.ui.initialView || 'none');

    return new Promise((resolve) => {
      if (document.body) {
        document.body.appendChild(cmpElement);
        resolve();
      }

      document.addEventListener('DOMContentLoaded', () => {
        document.body.append(cmpElement);
        resolve();
      });
    });
  }

  public setView(view: UiView) {
    const consents = JSON.stringify(this.cmpController.dps.getServicesConsents()); // data example

    switch (view) {
      case 'none':
        // do not show the cmp, do not show a cmp button/trigger
        this.cmpElement.innerHTML = '';
        break;
      case 'button':
        // do not show the cmp, show a cmp button/trigger
        this.cmpElement.innerHTML = 'custom button view';
        break;
      case 'first':
        // the cmp needs to be shown
        this.cmpElement.innerHTML = `custom first layer view: ${consents}`;
        break;
      case 'second':
        //  the optional custom secondary layer (never an initial view)
        this.cmpElement.innerHTML = `custom second layer view ${consents}`;
        break;
    }
  }
}

(async () => {
  const gdprWebSdk = new GdprWebSdk();
  const gdprCmpController = await gdprWebSdk.initBySetting('YOUR_GDPR_SETTINGS_ID');

  const cmpView = new CmpView(gdprCmpController);
  await cmpView.init();
})();

Considerations for building your custom TCF UI

Note: This does NOT apply if you use the unaltered Usercentrics UI together with this SDK

If you plan to build your own custom UI for TCF, Usercentrics cannot be liable that your custom UI conforms to all the IAB rules and guidelines. In this case, you can still use this SDK, but you need to register your solution at the IAB yourself. You can then enter your cmp-id (provided by the IAB) and cmp-version through the Usercentrics Admin Interface.

In the case that you build your own TCF UI it is NOT allowed to use the default Usercentrics cmp-id and cmp-version.

License