Draft script
To test new changes within the Admin Interface before releasing them to your live environment, you can save any changes to a draft version. To display this draft version, you will need to add a data-draft="true" attribute to the CMP script tag.
<script
id="usercentrics-cmp"
data-settings-id="YOUR_SETTINGS_ID"
src="https://web.cmp.usercentrics.eu/ui/loader.js"
data-draft="true"
>
</script>Sandbox mode
To test your integration against a non-production backend, without writing to your live consent records or production analytics, you can add a data-sandbox="true" attribute to the CMP script tag. This is intended for customers who want to test changes (e.g. new integrations, AutoBlocker rules, or SDK upgrades) without any risk of affecting production data.
<script
id="usercentrics-cmp"
data-settings-id="YOUR_SETTINGS_ID"
src="https://web.cmp.usercentrics.eu/ui/loader.js"
data-sandbox="true"
>
</script>In sandbox mode, all backend calls (settings/consent API, consent storage, cross-device retrieval, AutoBlocker configuration) are routed to Usercentrics' sandbox domains (
usercentrics-sandbox.eu) instead of the productionusercentrics.eudomains.
Important
The
data-sandboxattribute is enabled by any non-empty value, includingdata-sandbox="false". Usedata-sandbox="true"when you want sandbox mode enabled, and omit the attribute entirely to disable it.
Sandbox mode can be combined with Draft mode (data-draft="true") — draft controls whether unpublished Admin Interface changes are loaded, while sandbox controls which backend environment those requests go to.
If you initialize the SDK programmatically via @usercentrics/cmp-web-sdk instead of the script tag, pass the equivalent sandbox: true init option:
const webSdk = new WebSdk({ sandbox: true });Adding a nonce to the script tag
To add a nonce to your personal script, you can add it like so:
<script
id="usercentrics-cmp"
data-settings-id="YOUR_SETTINGS_ID"
src="https://web.cmp.usercentrics.eu/ui/loader.js"
nonce="YOUR_NONCE_VALUE"
>
</script><script
id="usercentrics-cmp"
data-settings-id="YOUR_SETTINGS_ID"
src="https://web.cmp.usercentrics.eu/ui/loader.js"
data-tcf-enabled
nonce="YOUR_NONCE_VALUE"
>
</script>Improved consent sharing between subdomains
If you're using Usercentrics Cross Domain Consent Sharing (CDCS) your website visitors might still see the CMP again when switching to another subdomain, for example mywebshop.com to checkout.mywebshop.com. Modern browsers are causing this behavior as they block the shared iframe provided by Usercentrics. The following section describes the needed steps to prevent this from happening.
Important
This solution will improve user experience for most browsers, however currently we have some browser related restrictions: CDCS does not work without sharing third-party local storage information across different browser tabs or if the user enabled special privacy settings within the Browser settings.
Safari: CDCS does not work with Safari, since the browser does not share third-party local storage across different browser tabs. Due to this restriction, the feature can not share the iframe's local storage across different tabs
Firefox: If the option "Delete Cookies" is enabled, the feature does not work, since Firefox clears the local storage for every new tab automatically, which prevents saving consents.
Chrome: From Chrome version 115 and going forward, CDCS does not work between different root domains (ex. a.com → b.com) because of restrictions that Google have imposed on third-party storage possibilities. This means, that our current implementation of CDCS now effectively only works between root domains and their subdomains (ex. sub.a.com → a.com → othersub.a.com). Read more about the updates that Google have made to Chrome here.
Download the file cross-domain-bridge.html (right click > Save as ...)
Upload this file to your webserver. It should be reachable from your main domain that is included in all of your subdomains. For example:
https://mywebshop.com/cross-domain-bridge.htmlBefore the Usercentrics CMP script tag, set the new location of the Cross Domain Bridge via the
window.UC_UI_DOMAINS.crossDomainConsentSharingIFrameproperty (this should be added into all the domains, including the main domain).
Example
A complete example might look like this:
<html>
<head>
<script>
window.UC_UI_DOMAINS = {
crossDomainConsentSharingIFrame: 'https://mywebshop.com/cross-domain-bridge.html',
};
</script>
<script id="usercentrics-cmp" data-settings-id="XXXXXXXX" src="https://web.cmp.usercentrics.eu/ui/loader.js" async>
</script>
</head>
<body>
</body>
</html>White labeling URLs
For customers that only allow sources from the same domain on their websites for security reasons, you can now configure from which address all Usercentrics resources (JSON files, JavaScript files etc.) should be loaded.
This should be configured before the UI script from "Add the JavaScript Tag"
In order to configure the domains please define the window variable called ucCmpConfig with the following structure:
window.ucCmpConfig = {
proxy: {
api: '',
consent: '',
crossDevice: '',
logger: '',
cdn: '',
analytics: '',
}
}Endpoints
Important
Your proxy servers should point to the following domains
Regarding Cross Domain Consent Sharing feature you can white label only the domain via app key or provide a full URL to be used for this feature via crossDomainConsentSharingIFrame key.
Name | Purpose | Key | Domain |
|---|---|---|---|
Api | Api to communicate between the UI and the SDK / backend | api | |
Consents | Get the consents data for Cross Domain feature | consent | |
Cross Device Consents | Get the consents data for Cross Device feature | crossDevice | |
GraphQL | Stores all user decisions on server | logger | |
CDN | URL used on Cross Domain Consent Sharing Iframe to get data | cdn | |
Analytics | Sends interaction analytics events (impressions, accept/deny actions, etc.) | analytics |
Other window.ucCmpConfig options
proxy is only one of several keys supported on the window.ucCmpConfig object. All keys below are optional, and window.ucCmpConfig must be set before the CMP script tag runs, since it is only read once during initialization.
Key | Type | Purpose |
|---|---|---|
| object | White label endpoint domains (see above). |
| boolean | Prevent the CMP UI from rendering, while the SDK still initializes normally. |
|
| Supply the visitor's location yourself instead of relying on Usercentrics' IP-based geolocation lookup. |
| string | Alternative way to provide a CSP nonce, instead of (or in addition to) the script tag's |
| object | Provide the full core settings data directly, bypassing |
| object | Provide a local AutoBlocker configuration (blocked script nodes, allow-listed sources/URLs) instead of having AutoBlocker fetch it from Usercentrics' servers. |
|
| Disable the Microsoft UET (Universal Event Tracking) consent mode integration. |
|
| Disable the Amazon Consent Signal (ACS) integration. |
|
| Disable the Microsoft Clarity consent mode v2 integration. |
Suppress the CMP UI
ui.suppress prevents the consent banner/UI from rendering, while the SDK, consent storage, and all other CMP logic still initialize normally. This is the same behavior as setting the legacy window.UC_UI_SUPPRESS_CMP_DISPLAY = true global.
window.ucCmpConfig = {
ui: {
suppress: true,
},
};Location
location is a Promise that resolves to the visitor's location. Use this if your own application already knows (or can look up) the visitor's location and you want to skip Usercentrics' own IP-based geolocation lookup.
window.ucCmpConfig = {
location: Promise.resolve({
country: 'DE',
region: 'BE',
}),
};
regionandcityare optional; onlycountryis required.
Nonce via config
As an alternative to the script tag's nonce/data-nonce attribute, you can supply your CSP nonce via window.ucCmpConfig.nonce. The script tag attribute, when present, takes priority over this value.
window.ucCmpConfig = {
nonce: 'YOUR_NONCE_VALUE',
};Core settings data
core lets you provide the full core settings object directly instead of having the CMP fetch it via data-settings-id or data-ruleset-id. It is only used when neither of those attributes is present on the script tag, and is primarily intended for advanced integrations (such as Usercentrics' own geolocation-based loader) that resolve settings data themselves.
window.ucCmpConfig = {
core: {
id: 'YOUR_SETTINGS_ID',
version: '1.0.0',
languages: ['en', 'de'],
cmp: {
version: '3',
type: 'gdpr',
},
// ...additional fields as returned by the Usercentrics settings API
},
};AutoBlocker configuration
autoBlockerConfig provides a local AutoBlocker configuration (the list of tracked script "nodes", allow-listed custom sources, and allow-listed URLs) instead of having the AutoBlocker script fetch it from Usercentrics' servers. This is mainly useful when testing or debugging AutoBlocker rules locally.
window.ucCmpConfig = {
autoBlockerConfig: {
allowedCustomSources: [],
nodes: [
{
serviceIds: ['SERVICE_ID'],
hash: 'SCRIPT_HASH',
src: 'https://example.com/script.js',
},
],
allowListURLs: [],
},
};Third-party consent mode integrations
Usercentrics can automatically forward the visitor's consent decisions to certain third-party consent APIs. Each integration is enabled by default and can be disabled independently via its own disabled flag:
Key | Third party |
|---|---|
| Microsoft UET (Universal Event Tracking) consent mode |
| Amazon Consent Signal (ACS) |
| Microsoft Clarity consent mode v2 |
window.ucCmpConfig = {
uetConfig: {
disabled: true,
},
acsConfig: {
disabled: true,
},
clarityConfig: {
disabled: true,
},
};