Migrate to V3¶

Introduction¶

V3 introduces breaking changes that will require manual updates if you have an existing codebase with a custom V2 implementation.

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

For each step, this guide is designed to:

• help you understand the differences between V2 and V3
• help you resolve any breaking changes
• provide you, whenever possible, with code examples and starting points in order to migrate to V3.

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. In order to start using V3, please update the src to: "https://web.cmp.usercentrics.eu/ui/loader.js.

For highest possible performance we also offer the "plus" setup. However, we do not recommend this setup if you can't guarantee to update the script source regularly.

<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¶

Renamed methods¶

With the introduction of V3, 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 V3 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 V3, 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 v2 have been implemented, some are still on the todo list:

• Consent injection via window variable

CustomCSS¶

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¶

Starting with V3, in order to simplify their usage - embeddings will be a reflection of the CMP itself, meaning that all the information present in the CMP will also be present in the Embeddings.

Structure¶

Since embeddings are a reflection of the CMP in V3, 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.

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

<div 
  class="uc-embed"
  uc-consent-name="Youtube Video"
  uc-data="all">
</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.

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.