Migrate to the latest version

Introduction

The latest version of the web CMP introduces breaking changes that will require manual updates if you have an existing codebase with a custom implementation.

This guide covers what you should be changing in order to be able to use the latest version.

For each step, this guide is designed to:

• help you understand the differences between the two versions

• help you resolve any breaking changes

• provide you, whenever possible, with code examples and starting points in order to migrate.

Info

For a broader understanding of the latest version, please read the following document.

Getting started

Script tag

Let's start the migration by updating the Usercentrics <script> tag on your website.

The main difference will be the src URL. To start using the latest version, update the src to: "https://web.cmp.usercentrics.eu/ui/loader.js.

bundle and bundle-legacy users

Only loader.js is available on the latest version

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

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

<script
  id="usercentrics-cmp"
  data-settings-id="XXXXXXXX"
  src="https://app.usercentrics.eu/browser-ui/latest/loader.js" 
  async>
</script>

<script
  id="usercentrics-cmp"
  data-settings-id="XXXXXXXX"
  src="https://app.usercentrics.eu/browser-ui/latest/loader.js"
  data-tcf-enabled
>
</script>

Browser UI API

We recommend taking a look at our new Browser UI API after you resolve the breaking changes

Renamed methods

With the introduction of the new version, the following Browser UI API methods were renamed:

Renamed methods with functional changes

The following methods, besides being renamed also got functional changes

updateServicesConsents

In order to simplify the services consent updates, the acceptServices and rejectServices have been unified into one method updateServicesConsents which now accepts the following parameters:

const serviceConsents = [
    {id: 'HkocEodjb7', consent: true}, // Google Analytics
    {id: 'S1_9Vsuj-Q', consent: false}, // Google Ads
]

await __ucCmp.updateServicesConsents(serviceConsents);
await __ucCmp.saveConsents();

updateTcfConsents

const vendorConsents = [
    {id: 6, consent: true}, // AdSpirit GmbH
    {id: 11, legitimateInterestConsent: false}, // Quantcast
];

const decision = {
    vendors: vendorConsents
};

await updateTcfVendorConsents({ decision });

Methods functional changes

All new methods are now async. Apart from that, denyAllConsents, acceptAllConsents, updateServicesConsents and updateTcfConsents will only update the consent status. In order to save consents, you need to call saveConsents('EXPLICIT' | 'IMPLICIT') after updating consents.

Removed methods

With the introduction of the new version, the following Browser UI API methods were removed:

• acceptService

• areAllConsentsAccepted

• denyAndCloseCcpa

• rejectService

• getServicesBaseInfo

• getServicesFullInfo

• restartCMP

• restartEmbeddings

• getSettings

• getSettingsCore

• getSettingsUI

• getSettingsLabels

• getTCFVendors

Content Security Policy

For best security you should add a Content-Security-Policy meta tag. It's important to replace the nonce.

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https://*.usercentrics.eu 'nonce-SomeRandomString'; connect-src 'self' https://*.usercentrics.eu; img-src 'self' data: https://*.usercentrics.eu;">
<script nonce="SomeRandomString" src="https://web.cmp.usercentrics.eu/ui/loader.js" id="usercentrics-cmp" data-settings-id="YOUR_SETTINGS_ID"></script>

Missing features (not implemented yet)

Whereas most of the features of the earlier version have been implemented, consent injection via window variable is not available yet.

Styling changes (Brand Color deprecation)

In V2, the “Brand Color” field in the Admin Interface acted as a fallback color.

If specific UI elements such as Tabs or Toggle buttons did not have individual colors defined, the Brand Color was automatically applied.

In V3, the Brand Color field has been deprecated and removed from the Admin Interface.

If no individual colors (e.g. Tab Color, Toggle Color) are defined under Appearance → Styling, the CMP will apply a default blue color as a fallback.

Important

After migrating to V3, your CMP may appear blue if individual colors are not explicitly configured. This is expected behavior and not a product issue.

To preserve your branding, make sure to define all relevant color fields individually under Appearance → Styling in the Admin Interface.

Custom CSS

Since the structure of the CMP changed, the custom css is not backwards compatible and needs updating.

Please read more about the new custom css entry points.

Embeddings

To simplify the usage of embeddings, they will be a reflection of the CMP itself. This means that all the information present in the CMP will also be present in the Embeddings.

Setup options

For the div possible class names remain the same: "uc-embed" and "uc-embed-tcf" for GDPR and TCF, respectively.

For more insights, please refer to the Embeddings documentation

Structure

Since embeddings are a reflection of the CMP in the latest version, the structure of these have been simplified. The previous way of configuring embeddings is no longer required because of this.

Deprecated attributes

uc-data

As mentioned above, all the information present in the CMP will be displayed in the embeddings with no option to filter out specific information.

uc-styling

All embeddings will have the same styling as the CMP, so no further styling is required.

uc-consent-name

This attribute has been deprecated in favor of using the uc-embed-type value service-specific with the uc-embed-service-id.

Example on how to migrate

<div 
  class="uc-embed"
  uc-consent-name="Youtube Video"
  uc-data="all">
</div>

<div 
  class="uc-embed"
  uc-embed-type="service-specific"
  uc-embed-service-id="BJz7qNsdj-7">
</div>

uc-embedding-vendors

Since we now reflect the same labels and styling as the CMP, this option is no longer available.

uc-embedding-non-iab-vendors

Since we now reflect the same labels and styling as the CMP, this option is no longer available.

uc-embedding-atp-vendors

Since we now reflect the same labels and styling as the CMP, this option is no longer available.

Renamed attributes

uc-embedding-type

Was renamed to uc-embed-type.

The values for purpose and vendor were renamed to purposes and vendors, respectively.

uc-show-toggle

Was renamed to uc-embed-show-toggle.

Following the same philosophy as uc-styling is no longer possible to change the toggle colors, they will keep the same color as selected for the CMP.

In that case, .uc-embed-toggle-button.toggle-on, .uc-embed-toggle-button.toggle-off, .uc-embed-toggle-button.toggle-disabled are no longer supported.

uc-embedding-show-hidden-categories

Was renamed to uc-embed-show-all-categories. All other functionality and properties remain the same.

uc-embedding-title

Was renamed to uc-embed-title.