Table of Contents

• Installing
  • Package manager
• Example
• Usercentrics API
  • Applying Consent
    • acceptAllConsents
    • denyAllConsents
    • updateServiceConsent
    • updateServiceConsents
    • updateCategoryConsent
    • updateCategoriesConsents
    • saveConsents
  • Data
    • getServices
    • getServicesBaseInfo
    • getCategories
    • getLanguages
  • Other methods
    • changeLanguage
    • areAllConsentsAccepted
    • areAllConsentsDenied
    • getIsConsentRequired
• Implementation Examples
• 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 cmpWebSdk.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 cmpWebSdk.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 cmpWebSdk.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 cmpWebSdk.initBySetting('YOUR_SETTINGS_ID');
})();

Usercentrics API

Applying Consent

acceptAllConsents

await webSdk.acceptAllConsents();

denyAllConsents

await webSdk.denyAllConsents();

updateServiceConsent

Update a single service consent

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

updateServiceConsents

Update a multiple services consent

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

updateCategoryConsent

Update a Category consent

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

updateCategoriesConsents

Update a multiple categories consent

await cmpWebSdk.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 cmpWebSdk.saveConsents();

Data

getServices

await cmpWebSdk.getServices();

getServicesBaseInfo

await cmpWebSdk.getServicesBaseInfo();

getCategories

await cmpWebSdk.getCategories();

getLanguages

await cmpWebSdk.getLanguages();

Other methods

changeLanguage

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

await cmpWebSdk.changeLanguage('en');

areAllConsentsAccepted

Returns true if all the consents are accepted

const allConsentsAccepted = await cmpWebSdk.areAllConsentsAccepted();

areAllConsentsDenied

Returns true if all the consents are denied

const allConsentsDenied = await cmpWebSdk.areAllConsentsDenied();

getIsConsentRequired

Returns true if a user decision is needed

const isConsentRequired = await cmpWebSdk.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();
})();

License