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.
npm install @usercentrics/cmp-browser-sdk --saveimport Usercentrics, { UI_LAYER, UI_VARIANT } from '@usercentrics/cmp-browser-sdk';
const UC = new Usercentrics('YOUR_USERCENTRICS_SETTINGS_ID');
UC.init().then((initialUIValues) => {
// getSettings() returns all Usercentrics settings you need for your custom solution
const settings = UC.getSettings();
// 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.
import Usercentrics, { UserDecision } 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();
/**
* ...
*/
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();
});
};
});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 });
UC.init().then((initialUIValues) => {
// getSettings() 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.getSettings();
// 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;
}
}
});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 });
UC.init().then((initialUIValues) => {
const settings = UC.getSettings();
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();
};
});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.getSettings();
// 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();
});If your Consent Solution should work with IE11 (or other legacy browsers), then there's a few extra steps you need to do:
CustomEvent polyfill
fetch polyfill
Also you'll have to have Babel (or similar) in your build setup to make sure, that Array.prototype.find etc. get polyfilled.
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.2/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.2/bundle_legacy.js.
Documentation can be found on our documentation website.