Optional Steps

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>

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>

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.

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: '',
    }
}

Our Endpoints¶

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.

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

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:

window.ucCmpConfig = {
    uetConfig: {
        disabled: true,
    },
    acsConfig: {
        disabled: true,
    },
    clarityConfig: {
        disabled: true,
    },
};