@usercentrics/cmp-browser-sdk - v0.5.0-alpha.0

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 initialization

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

const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');

UC.init().then((initialUIValues) => {
    // 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();

    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.

TCF initialization

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

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

UC.init().then((initialUIValues) => {
    // getCategories() returns all categories' and data processing services' information
    const categories = UC.getCategories();
    // getSettings() returns all Usercentrics settings you need for your custom solution
    // NOTE: The UISettings will now be TCFUISettings, not DefaultUISettings
    const settings = UC.getSettings();

    if (initialUIValues.variant === UI_VARIANT.TCF) {
        // getTCFData() returns all TCF related data (vendors, purposes, special features etc.)
        const tcfData = UC.getTCFData();

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

Accept / deny / update services (and special handler for closing TCF UI with no changes)

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

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

UC.init().then((initialUIValues) => {
    const categories = UC.getCategories();
    const settings = UC.getSettings();
    // tcfData is only relevant for a TCF UI!
    const tcfData = UC.getTCFData();
    /**
     * ...
     */

    const onAcceptAllHandler = (fromLayer: TCF_DECISION_UI_LAYER): void => {
        if (settings.isTcfEnabled) {
            Promise.all([UC.acceptAllServices(), UC.acceptAllForTCF(fromLayer)]).then(() => {
                // Remember to get new categories and tcfData
                const categories = UC.getCategories();
                const tcfData = UC.getTCFData();
            });
        } else {
            UC.acceptAllServices().then(() => {
                // Remember to get new categories
                const categories = UC.getCategories();
            });
        }
    };

    const onDenyAllHandler = (fromLayer: TCF_DECISION_UI_LAYER): void => {
        if (settings.isTcfEnabled) {
            Promise.all([UC.denyAllServices(), UC.denyAllForTCF(fromLayer)]).then(() => {
                // Remember to get new categories and tcfData
                const categories = UC.getCategories();
                const tcfData = UC.getTCFData();
            });
        } else {
            UC.denyAllServices().then(() => {
                // Remember to get new categories
                const categories = UC.getCategories();
            });
        }
    };

    const onSaveHandler = (fromLayer: TCF_DECISION_UI_LAYER): void => {
        const userDecisionOnServices = getUserDecisionsOnServicesFromUI();

        if (settings.isTcfEnabled) {
            const tcfUserDecisions = getTCFUserDecisionsFromUI();

            Promise.all([
                UC.updateServices(userDecisionOnServices),
                UC.updateChoicesForTCF(tcfUserDecisions, fromLayer),
            ]).then(() => {
                // Remember to get new categories and tcfData
                const categories = UC.getCategories();
                const tcfData = UC.getTCFData();
            });
        } else {
            UC.updateServices(userDecisionOnServices).then(() => {
                // Remember to get new categories
                const categories = UC.getCategories();
            });
        }
    };

    // Special handler for closing the TCF UI without any user changes (close button / clickaway handler)
    const onTCFUICloseHandler = (): void => {
        UC.setTCFUIAsClosed().then(() => {
            // Remember to get new tcfData
            const tcfData = UC.getTCFData();
        });
    };
});

Changing the language

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

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

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 (or similar) in your build setup to make sure, that Array.prototype.find 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.5.0-alpha.0/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((initialUIValues) => {
    // 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();

    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/0.5.0-alpha.0/bundle_legacy.js.

Documentation

Documentation can be found on our documentation website.