Browser UI integration¶

Add the JavaScript Tag¶

To get started, simply add the Usercentrics script to the <head> section of your website, making sure it comes before any third-party scripts that require user consent.

If you're using a Geolocation Ruleset (specifically a Ruleset-ID instead of a Settings-ID), just replace the data-settings-id with data-ruleset-id. You can learn more about Geolocation Rules here.

Settings-IDRuleset-ID

Settings-ID Javascript tag

<script
    id="usercentrics-cmp"
    data-settings-id="YOUR_SETTINGS_ID"
    src="https://web.cmp.usercentrics.eu/ui/loader.js"
>
</script>

Ruleset-ID Javascript tag

<script
    id="usercentrics-cmp"
    data-ruleset-id="YOUR_RULESET_ID"
    src="https://web.cmp.usercentrics.eu/ui/loader.js"
>
</script>

Note

You can find the script implementation with the Settings-ID for your specific account in the Usercentrics Admin Interface, within the Implementation section.

Script tag attribute reference¶

You can refine the behavior of the CMP by adding any of the following data-* attributes to the script tag, alongside data-settings-id (or data-ruleset-id).

Attribute	Type	Default	Description	Example
`data-controller-id`	String	Auto-generated if omitted	Encrypted key that identifies a specific user's consent record. Used to restore a user's consent across devices/domains. See Cross Device Consent Sharing.	`data-controller-id="YOUR_CONTROLLER_ID"`
`data-language`	String (language code)	Resolved via the Language Hierarchy if omitted	Forces the CMP to render in a specific language, overriding automatic document/browser language detection.	`data-language="en"`
`data-user-location`	String — `country[,region[,city]]`	Detected automatically	Manually sets the user's location instead of relying on automatic geolocation. Used together with Geolocation Rulesets.	`data-user-location="US,CA"`
`data-theme`	String — one of `uc`, `tv`, `cb`, `wix`, `shopify`	`uc`	Sets the UI theme used to render the CMP. Any unrecognized value falls back to the default.	`data-theme="uc"`
`data-draft`	Boolean — literal string `"true"`	`false`	Loads the unpublished draft configuration saved in the Admin Interface, so you can preview changes before publishing. Any value other than the exact string `"true"` is treated as `false`.	`data-draft="true"`
`data-sandbox`	Boolean (presence-based)	`false`	Routes all API calls to the sandbox environment (`usercentrics-sandbox.eu`) instead of production. Enabled by the attribute simply being present, so avoid writing `data-sandbox="false"` — that string is still truthy and will enable it.	`data-sandbox="true"`
`data-eu-mode`	Boolean (presence-based)	`false`	Forces all CMP API and tracking calls through EU-based endpoints. Like `data-sandbox`, it is enabled by the attribute's presence rather than its value.	`data-eu-mode="true"`
`data-disable-tracking`	Boolean — literal string `"true"`	`false`	Disables collection of interaction analytics data, for example while running in draft mode. Must be set to the exact string `"true"`.	`data-disable-tracking="true"`
`data-exclude-accept-all-vendors`	JSON-encoded array of numbers	`[]`	TCF only. A JSON array of TCF vendor IDs to exclude when the user clicks "Accept All".	`data-exclude-accept-all-vendors="[1,2,3]"`
`data-ab-variant`	String	Random variant selected from the configured A/B test	Forces a specific A/B test variant instead of random selection. The value must match one of the variant keys configured for the setting's A/B test (e.g. `variant0`, `variant1`), otherwise it is ignored.	`data-ab-variant="variant1"`
`data-legislation-view`	String — one of `gdpr`, `tcf`, `tcf2`, `uk_gdpr`, `uk_tcf2`, `ccpa`, `cpra`, `vcdpa`, `cpa`, `ctdpa`, `ucpa`, `pipeda`	Resolved automatically from the user's location	Forces the CMP to use a specific legislation's configuration instead of the one automatically resolved from location, useful for testing.	`data-legislation-view="gdpr"`

Some attributes only take effect once a value is provided — for example, data-language needs the desired language code to have any effect.

Using The Transparency & Consent Framework (TCF)

If you are using TCF, please go through the configuration for TCF before implementing the script tag on your website. Read more here.

Adjust third-party scripts¶

After successfully integrating the Usercentrics script into your website, you will need to make two specific adjustments to all third-party scripts that rely on consent for implementation.

1. Change the script type¶

First, modify the type attribute on all scripts that necessitate consent, changing it from type="text/javascript" to type="text/plain". This adjustment ensures that these scripts do not execute upon the page's initial load.

Additionally, if certain third-party scripts lack an explicit type="text/javascript" attribute, it's essential to include type="text/plain" to prevent their execution by default within the browser.

2. Assign a data attribute¶

Furthermore, each third-party script must be assigned a custom data-usercentrics attribute. This attribute serves the purpose of associating the script with the services you create in the Usercentrics Admin Interface.

The syntax for this data attribute is data-usercentrics="Name of Data Processing Service" where "Name of Data Processing Service" should precisely match the name of the Data Processing Service you've defined.

Illustration - Example of Data Processing Service in Admin Interface

Case sensitivity

Please ensure strict attention to uppercase and lowercase distinctions, as well as the presence of spaces within these service names, as the CMP takes all of these nuances into account.

Example¶

For illustrative purposes, here is how to modify the Facebook Pixel script.

Before adjustmentsAfter adjustments

<!-- Facebook Pixel Code -->
<script>
    !function(f,b,e,v,n,t,s)
    {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
    n.callMethod.apply(n,arguments):n.queue.push(arguments)};
    if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
    n.queue=[];t=b.createElement(e);t.async=!0;
    t.src=v;s=b.getElementsByTagName(e)[0];
    s.parentNode.insertBefore(t,s)}(window, document,'script',
    'https://connect.facebook.net/en_US/fbevents.js');
    fbq('init', '{your-pixel-id-goes-here}');
    fbq('track', 'PageView');
</script>
<!-- End Facebook Pixel Code -->

<!-- Facebook Pixel Code -->
<script type="text/plain" data-usercentrics="Facebook Pixel">
    !function(f,b,e,v,n,t,s)
    {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
    n.callMethod.apply(n,arguments):n.queue.push(arguments)};
    if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
    n.queue=[];t=b.createElement(e);t.async=!0;
    t.src=v;s=b.getElementsByTagName(e)[0];
    s.parentNode.insertBefore(t,s)}(window, document,'script',
    'https://connect.facebook.net/en_US/fbevents.js');
    fbq('init', '{your-pixel-id-goes-here}');
    fbq('track', 'PageView');
</script>
<!-- End Facebook Pixel Code -->

After these modifications, the Facebook Pixel script will only run on page load if it has received the necessary consent.

When consent is withdrawn

In the event that a user withdraws their consent after a service has already been loaded, it is crucial to deactivate or stop the use of that service. One approach to achieve this is to initiate a page reload, effectively halting the execution of third-party scripts that lack consent.

Scripts that require a specific type¶

In certain cases, scripts may require a different type attribute than "text/javascript". To accommodate such scripts, an additional JavaScript wrapper can be employed to integrate them into your webpage. This wrapper must then be adjusted following the steps outlined in the Adjust existing scripts section, and also include the relevant data attribute for your data processing service to enable or disable it through the CMP.

For instance, a scenario may arise where a third-party script must be configured with type="module" for proper execution. If this specific configuration is necessary, the following is an example of how to implement the JavaScript wrapper, which allows you to work with such a service:

Example¶

<script type="text/plain" data-usercentrics="Name Data Processing Service">
    var customScript = document.createElement('script');
    customScript.src = 'your source'; // Add source to your script
    customScript.type = 'module'; // Add type of your script
    document.head.appendChild(customScript); // or document.body.appendChild(customScript);
</script>

Language Hierarchy¶

Usercentrics follows a certain hierarchy to determine which language value should be used to display your CMP. The hierarchy is as follows:

Data attribute on the CMP's script tag: <script id="usercentrics-cmp" data-settings-id="YOUR_SETTINGS_ID" src="https://web.cmp.usercentrics.eu/ui/loader.js" data-language="en">
Consent Language: If the user has already visited the website and made a decision the language set at that time will be used as the default one
Document language: lang-attribute on <html> tag (e.g. <html lang="language_code"> is integrated on the website)
User’s browser language (e.g. navigator.languages)
Default Visible Language set up in the Admin-Interface if the user’s browser language is not part of the preselected language set.

The language that the CMP chooses will be written into the local storage of the website and any Usercentrics element will be displayed to the user in that language during future visits.