@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

Initialization

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

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');

UC.init().then((initialView) => {
    // getCategories() returns all categories' and data processing services' information
    const categories = UC.getCategories();
    // getSettings() returns all Usercentrics settings you need for your custom solution
    const settings = UC.getSettings();

    switch (initialView) {
        case INITIAL_VIEW.FIRST_LAYER:
            // Show first layer (i.e. privacy banner)
            return;
        case INITIAL_VIEW.PRIVACY_BUTTON:
            // Show privacy button
            return;
        case INITIAL_VIEW.NONE:
        default:
            // Show nothing
            return;
    }
});

The constructor also supports an optional Options parameter.

Changing the language

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

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');

UC.init().then((initialView) => {
    /**
     * ...
     */

    UC.changeLanguage('NEW_LANGUAGE').then(() => {
        // Remember to fetch new categories and settings
        const categories = UC.getCategories();
        const settings = UC.getSettings();
    });
});

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' });

UC.init().then((initialView) => {
    /**
     * ...
     */
});

controllerId is known after init

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

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');

UC.init().then((initialView) => {
    /**
     * ...
     */

    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 type="application/javascript" src="https://app.usercentrics.eu/browser-sdk/0.4.5/bundle.js"></script>

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

const UC = new UC_SDK.Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');

UC.init().then((initialView) => {
    const categories = UC.getCategories();
    const settings = UC.getSettings();

    switch (initialView) {
        case UC_SDK.INITIAL_VIEW.FIRST_LAYER:
            // Show first layer (i.e. privacy banner)
            return;
        case UC_SDK.INITIAL_VIEW.PRIVACY_BUTTON:
            // Show privacy button
            return;
        case UC_SDK.INITIAL_VIEW.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/0.4.5/bundle_legacy.js.

Documentation

Documentation can be found on our documentation website.