@usercentrics/cmp-browser-sdk

Usercentrics CMP Browser SDK

With the Usercentrics CMP Browser SDK our aim is to provide a lightweight library which enables you to build your own fully customized Consent Solution while still leveraging the Usercentrics service database and tools.

We also offer collaboration possibilities with Usercentrics Partners who are able to support you in building your own customized solution. Contact our sales team for more information.

Installing the dependency

npm install @usercentrics/cmp-browser-sdk --save

Default (non-TCF) initialization

import Usercentrics, { UI_LAYER, UI_VARIANT } from '@usercentrics/cmp-browser-sdk';

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');
const initialUIValues = await UC.init();

// getSettingsCore() and getSettingsLabels() returns all Usercentrics settings you need for your custom solution
const settings = UC.getSettingsCore();
const labels = UC.getSettingsLabels();
// getCategories() returns all categories' and data processing services' information
const categories = UC.getCategories();

if (initialUIValues.variant === UI_VARIANT.DEFAULT) {
  switch (initialUIValues.initialLayer) {
    case UI_LAYER.FIRST_LAYER:
      // Show first layer (i.e. privacy banner)
      return;
    case UI_LAYER.PRIVACY_BUTTON:
      // Show privacy button
      return;
    case UI_LAYER.NONE:
    default:
      // Show nothing
      return;
  }
}

The constructor also supports an optional Options parameter.

Geolocation initialization

In order to provide geolocation feature we introduced a Ruleset ID property which will point to an existing geolocation config settingsIds mapping. This will allow you to get a banner based on your specific rules, having different banners in different locations.

const UC = new Usercentrics('YOUR_USERCENTRICS_RULESET_ID', {
  rulesetId: 'YOUR_USERCENTRICS_RULESET_ID',
  useRulesetId: true,
});

Accept / deny / update services in the default (non-TCF) context

import Usercentrics, { UserDecision } from '@usercentrics/cmp-browser-sdk';

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID', { createTcfApiStub: true });
const initialUIValues = await UC.init();

const categories = UC.getCategories();
const settings = UC.getSettingsCore();

/**
 * ...
 */

const onAcceptAllHandler = (): void => {
  UC.acceptAllServices().then(() => {
    // Remember to fetch the now updated categories
    const categories = UC.getCategories();
  });
};

const onDenyAllHandler = (): void => {
  UC.denyAllServices().then(() => {
    // Remember to fetch the now updated categories
    const categories = UC.getCategories();
  });
};

const onSaveHandler = (userDecisions: UserDecision[]): void => {
  // UserDecisions needs to include all the user choices for each service that were made in your UI
  UC.updateServices(userDecisions).then(() => {
    // Remember to fetch the now updated categories
    const categories = UC.getCategories();
  });
};

TCF initialization

First, make sure TCF is enabled in your settings.

import Usercentrics, { UI_LAYER, UI_VARIANT } from '@usercentrics/cmp-browser-sdk';

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID', { createTcfApiStub: true });
const initialUIValues = await UC.init();

// getSettingsCore() and getSettingsLabels() returns all Usercentrics settings you need for your custom solution
// NOTE: If TCF is enabled, the ui property of the settings object will always be of type TCFUISettings, not DefaultUISettings.
const settings = UC.getSettingsCore();
const labels = UC.getSettingsLabels();
// getTCFData() returns all TCF related data (vendors, purposes, special features etc.)
const tcfData = UC.getTCFData();

if (initialUIValues.variant === UI_VARIANT.TCF) {
  switch (initialUIValues.initialLayer) {
    case UI_LAYER.FIRST_LAYER:
      // NOTE: Remember to call setTCFUIAsOpen()!
      UC.setTCFUIAsOpen();
      // Show TCF first layer
      return;
    case UI_LAYER.PRIVACY_BUTTON:
      // Show privacy button
      return;
    case UI_LAYER.NONE:
    default:
      // Show nothing
      return;
  }
}

The constructor also supports an optional Options parameter.

For TCF, the createTcfApiStub option needs to be set to true in order for the __tcfapi queue to initialize right away (we cannot wait for the settings request to finish).

Accept / deny / update vendors, purposes, special features in the TCF context

Note that both features and special purposes are for disclosing only and do not require any user decision. They cannot be updated.

Note that if TCF is enabled, the default (non-TCF) data is still available (e.g. getCategories()). A hybrid UI can be built if both sets of methods (TCF and default (non-TCF)) are called.

import Usercentrics, { TCF_DECISION_UI_LAYER } from '@usercentrics/cmp-browser-sdk';

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID', { createTcfApiStub: true });
const initialUIValues = await UC.init();

const settings = UC.getSettingsCore();
const tcfData = UC.getTCFData();

/**
 * ...
 */

// The fromLayer parameter needs to identify the layer from which the acceptAll button was triggered.
const onAcceptAllHandler = (fromLayer: TCF_DECISION_UI_LAYER): void => {
  UC.acceptAllForTCF(fromLayer).then(() => {
    // Remember to fetch the new (updated) tcfData
    const tcfData = UC.getTCFData();
  });
};

// The fromLayer parameter needs to identify the layer from which the denyAll button was triggered.
const onDenyAllHandler = (fromLayer: TCF_DECISION_UI_LAYER): void => {
  UC.denyAllForTCF(fromLayer).then(() => {
    // Remember to fetch the new (updated) tcfData
    const tcfData = UC.getTCFData();
  });
};

// The fromLayer parameter needs to identify the layer from which the save button was triggered.
const onSaveHandler = (tcfUserDecisions: TCFUserDecisions, fromLayer: TCF_DECISION_UI_LAYER): void => {
  // TCFUserDecisions needs to include all the user choices for each vendor, purpose, special feature that were made in your UI
  UC.updateChoicesForTCF(tcfUserDecisions, fromLayer).then(() => {
    // Remember to fetch the new (updated) tcfData
    const tcfData = UC.getTCFData();
  });
};

// Special handler for closing the TCF UI without any user changes (e.g. for any close button / click-away handler)
const onTCFUICloseHandler = (): void => {
  UC.setTCFUIAsClosed();
};

Changing the language

After UC is initialized you can change the language by calling:

UC.changeLanguage('NEW_LANGUAGE').then(() => {
  // Remember to fetch new (translated) settings
  const settings = UC.getSettingsCore();

  // If you use the default (non-TCF) setup, make sure to fetch new (translated) categories / settings
  const categories = UC.getCategories();

  // If you use the TCF setup, make sure to fetch new (translated) tcfData
  const tcfData = UC.getTCFData();
});

Changing the view

After UC is initialized you have to update the SDK after every view change:

const enum UI_LAYER {
  FIRST_LAYER,
  NONE,
  PRIVACY_BUTTON,
  SECOND_LAYER,
}

UC.updateLayer(UI_LAYER.FIRST_LAYER).then(() => {
  // Remember to fetch new (translated) settings
  const settings = UC.getSettingsCore();

  // If you use the default (non-TCF) setup, make sure to fetch new (translated) categories / settings
  const categories = UC.getCategories();

  // If you use the TCF setup, make sure to fetch new (translated) tcfData
  const tcfData = UC.getTCFData();
});

Getting Services Information

After UC is initialized you can retrieve the services information, by using one of the following methods: getServicesBaseInfo or getServicesFullInfo. The method getServices was deprecated in the version 2.2.0-beta.3 and it will be deleted in version 3.0, so we advise you to update to these new methods, based in your needs:

• getServicesBaseInfo retrieve all services with their base information, without fetching the aggregator.
  • Returns BaseService[]

const initialUIValues = await UC.init();
// getServicesBaseInfo() returns all the services with their base information
const servicesBase = UC.getServicesBaseInfo();
console.log("BASE INFO", servicesBase);

• getServicesFullInfo retrieves all services with their complete information, fetching the aggregator if necessary.
  • Returns Promise<Service[]>

const initialUIValues = await UC.init();
// getServicesFullInfo() returns all services with their complete information
const servicesFull = UC.getServicesFullInfo()
servicesFull.then(info => {
  console.log("FULL INFO", info);
});

Getting Categories Information

After UC is initialized you can retrieve the categories information, by using one of the following methods: getCategoriesBaseInfo or getCategoriesFullInfo. The method getCategories was deprecated in the version 2.2.0-beta.3 and it will be deleted in version 3.0, so we advise you to update to these new methods, based in your needs:

• getCategoriesBaseInfo retrieves the categories and their base services info to display this information in your UI.
  • Returns BaseCategory[]

const initialUIValues = await UC.init();
// getCategoriesBaseInfo() returns the categories and their base services info to display this information in your UI.
const categoriesBase = UC.getCategoriesBaseInfo();
console.log("BASE CATEGORIES INFO", categoriesBase);

• getCategoriesFullInfo retrieves the categories and their full services info to display this information in your UI.
  • Returns Promise<Category[]>

const initialUIValues = await UC.init();
// getCategoriesFullInfo() returns the categories and their full services info to display this information in your UI.
const categoriesFull = UC.getCategoriesFullInfo();
categoriesFull.then(info => {
  console.log("FULL INFO", info);
});

Cross-Device Consent Sharing

NOTE: If the given controllerId returns no history from the Usercentrics backend, that controllerId will not be updated for the end user.

controllerId is known before init

import Usercentrics from '@usercentrics/cmp-browser-sdk';

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID', { controllerId: 'CONTROLLER_ID_FOR_END_USER' });
const initialUIValues = await UC.init();

controllerId is known after init

import Usercentrics from '@usercentrics/cmp-browser-sdk';

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');
const initialUIValues = await UC.init();

UC.restoreUserSession('CONTROLLER_ID_FOR_END_USER').then(() => {
  /**
   * ...
   */
});

IE11 compatibility

If your Consent Solution should work with IE11 (or other legacy browsers), then there's a few extra steps you need to do:

• Include a CustomEvent polyfill
  • https://www.npmjs.com/package/custom-event-polyfill
• Include a fetch polyfill
  • https://www.npmjs.com/package/whatwg-fetch

Also you'll have to have Babel (with core-js) (or similar) in your build setup to make sure, that Symbol etc. get polyfilled.

Script tag support

You can also use the SDK as a script tag on your site:

<script src="https://app.usercentrics.eu/browser-sdk/4.38.4/bundle.js"></script>

You can now access all methods/constants by using them from within the UC_SDK namespace:

const UC = new UC_SDK.default('YOUR_USERCENTRICS_SETTINGS_ID');
const initialUIValues = await UC.init();

// getCategories() returns all categories' and data processing services' information
const categories = UC.getCategories();
// getSettingsCore() and getSettingsLabels() returns all Usercentrics settings you need for your custom solution
const settings = UC.getSettingsCore();
const labels = UC.getSettingsLabels();

if (initialUIValues.variant === UC_SDK.UI_VARIANT.DEFAULT) {
  switch (initialUIValues.initialLayer) {
    case UC_SDK.UI_LAYER.FIRST_LAYER:
      // Show first layer (i.e. privacy banner)
      return;
    case UC_SDK.UI_LAYER.PRIVACY_BUTTON:
      // Show privacy button
      return;
    case UC_SDK.UI_LAYER.NONE:
    default:
      // Show nothing
      return;
  }
}

NOTE: If you need Internet Explorer 11 support, you can point the src attribute to https://app.usercentrics.eu/browser-sdk/4.38.4/bundle_legacy.js.

Considerations for building your custom TCF v2.0 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 v2.0, 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 v2.0 UI it is NOT allowed to use the default Usercentrics cmp-id and cmp-version.

Documentation

Documentation can be found on our documentation website.

License

Commercial - © Usercentrics - see Terms and Conditions.