LIA Usercentrics

This TYPO3 extension integrates a cookie banner for managing consent for external services such as analytics, social media, etc. It ensures that external sources (like YouTube videos, Vimeo, or other integrated services) are blocked by default until the user grants consent for their use.

Installation

Explains how to install this extension in Composer-based and Classic TYPO3 installations.

Configuration

Learn how to setup up and configure this extension.

Frequently Asked Questions (FAQ)

These questions have been frequently asked.

How to get help

Learn where to get help and how to report issues you found.

Installation

Install LIA Usercentrics with Composer

Install the extension via Composer:

composer req lia/lia_usercentrics

Install LIA Usercentrics in Classic Mode

Or download the extension from https://extensions.typo3.org/package/lia_usercentrics and install it in the Extension Manager.

Configuration

Basic Configuration

Here you find the basic configuration to get Usercentrics up and running.

Smart Data Protector

Here you find the configuration for the Smart Data Protector.

JavaScript configuration

Learn how-to block javascript.

Basic configuration

After the extension is installed first you have to load the typoscript into your static template.

Warning

If it is not loaded you will get an exception in your frontend

Basic configuration

After the typoscript is loaded you have to override the constants of this extension and set them to load the usercentrics Library on you page.

Best Practice

Create a Constants.typoscript file in your provider extension to override the default constants. You can create it in subfolder like this: my_extension/Configuration/TypoScript/Extensions/LiaUsercentrics/Constants.typoscript. Make sure that this file is also loaded in your constants.typoscript file. To load this file add an import in it. @import 'EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Constants.typoscript'

Now place this code in it and set the constants to your need.

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Constants.typoscript
    

plugin.tx_liausercentrics {
  srcUrl = https://web.cmp.usercentrics.eu/ui/loader.js
  settingsId =
  ucQueryParameter =
  settings {
    activate = 0
    tcfEnabled = 0
    useSmartDataProtector = 0
    footerLink = 0
    excludedPages =
    whitelistedSDPServices =
    customOverlayIntegration =
  }
}

To load Usercentrics, enter your Usercentrics ID in settingsId and set the constant activate to 1. If you want to use the Smart Data Protector, set the constant the constant useSmartDataProtector to 1.

Note

The Smart Data Protector scans your system for known services and blocks them automatically. It also offers the option of using the overlays from Usercentrics. So you don't have to build your own.

Language

The current language is passed to Usercentrics automatically by getting the language code from the current locale:

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Setup.typoscript
    

plugin.tx_liausercentrics {
  ...
  language = TEXT
  language.data = siteLanguage:locale:languageCode
  ...
}

The language variable accepts plain strings and content objects like TEXT.

Footer link

You can also toggle the banner with a link. All you have to do is add this snippet where you would like it. You can integrate it so that it is dependent on the footerLink constant. This extension adds the constants active and footerLink to the settings of the page object. This means that they are available on all pages in the settings via settings.usercentrics.active or settings.usercentrics.footerLink.

Warning

Please note that when you set the settings of the page object, you must observe the loading order of the TypoScripts. If your configuration is loaded after the setup of this extension, the array with the two constants added by this extension is no longer included.

<f:if condition="{settings.usercentrics.active} && {settings.usercentrics.footerLink}">
    <a href="#" onClick="  window.__ucCmp.showSecondLayer()">Cookie-Management</a>
</f:if>

TCF enabled

Set the constant tcfEnabled to 1 to add the data-tcf-enabled attribute to the Usercentrics script tag. This activates the IAB Transparency & Consent Framework (TCF) mode in Usercentrics.

Smart Data Protector configuration

You can also configure and restrict the Smart Data Protector.

Restrict the Smart Data Protector

The Smart Data Protector scans for integrated services each time a page is called up and blocks them if it recognizes and the cookie for this service is not set. To limit the list of services, you can enter the Template IDs in the constant whitelistedSDPServices separated by a comma.

You can find the template IDs when configuring the services in Usercentrics.

Here you will also find all the services known to the Smart Data Protector.

Note

In this example, the Smart Data Protector is limited to Google Maps, Google Tag Manager, YouTube Video and Vimeo.

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Constants.typoscript
    

plugin.tx_liausercentrics {
  srcUrl = https://web.cmp.usercentrics.eu/ui/loader.js
  settingsId =
  ucQueryParameter =
  settings {
    activate = 0
    useSmartDataProtector = 0
    footerLink = 0
    excludedPages =
    whitelistedSDPServices = S1pcEj_jZX, BJ59EidsWQ, Hko_qNsui-Q, BJz7qNsdj-7, HyEX5Nidi-m
    customOverlayIntegration =
  }
}

Overlay for Custom service integration

If you integrate a service using your own logic, e.g. your own JavaScript, you can add a data attribute to the container where the content of the service is displayed and configure this in the TypoScript. The overlay is then inserted by the Smart Data Protector.

Add this attribute data-uc=“gMaps” to the container and enter the Template Id of the service followed by a colon and the value of the data attribute. S1pcEj_jZX:gMaps. You can add several configurations here. These only need to be separated by a comma.

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Constants.typoscript
    

plugin.tx_liausercentrics {
  srcUrl = https://web.cmp.usercentrics.eu/ui/loader.js
  settingsId =
  ucQueryParameter =
  settings {
    activate = 0
    useSmartDataProtector = 0
    footerLink = 0
    excludedPages =
    whitelistedSDPServices = S1pcEj_jZX, BJ59EidsWQ, Hko_qNsui-Q, BJz7qNsdj-7, HyEX5Nidi-m
    customOverlayIntegration = S1pcEj_jZX:gMaps
  }
}

The container would then look like this.

<div data-uc="gMaps"></div>

Block JavaScript

If you have JavaScript integrations that you need to block, then create a Setup.typoscript in the same folder in which you created the Constants.typoscript. This file is used to configure the various JavaScript, both inline and as a file. This file must also be loaded in the setup.typoscript of your provider extension. To load this file add an import in it. @import 'EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Setup.typoscript'

Blocking of files

In this example you can see a configuration of an inline JavaScript for the integration of the Google tag manager.

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Setup.typoscript
    

plugin.tx_liausercentrics.jsFile {
    10 {
        file = EXT:yourext/Resources/Public/JavaScript/GoogleTagManagerIntegration.js
        dataProcessingService = Google Tag Manager
    }
}

If you already have an inline integration of the GTM at another location, you can also assign this to the value. However, this should also be emptied afterwards so that you do not have a duplicate integration.

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Setup.typoscript
    

plugin.tx_liausercentrics.jsFile {
    10 {
        fiel < page.includeJS.googleTagManager
        dataProcessingService = Google Tag Manager
    }
}

[usercentricsIsActive('{$plugin.tx_liausercentrics.settings.activate}', '{$plugin.tx_liausercentrics.settingsId}')]
    page.includeJS.googleTagManager >
[global]

Blocking of inline JavaScript

In this example you can see a configuration of an inline JavaScript for the integration of the Google tag manager.

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Setup.typoscript
    

plugin.tx_liausercentrics.jsInline {
    10 {
        value (
            // create dataLayer
            window.dataLayer = window.dataLayer || [];
            function gtag() {
                dataLayer.push(arguments);
            }

            // set „denied" as default for both ad and analytics storage, as well as ad_user_data and ad_personalization,
            gtag("consent", "default", {
                ad_user_data: "denied",
                ad_personalization: "denied",
                ad_storage: "denied",
                analytics_storage: "denied",
                wait_for_update: 2000 // milliseconds to wait for update
            });

            // Enable ads data redaction by default [optional]
            gtag("set", "ads_data_redaction", true);

            // Google Tag Manager
            (function(w, d, s, l, i) {
                w[l] = w[l] || [];
                w[l].push({
                    'gtm.start': new Date().getTime(),
                    event: 'gtm.js'
                });
                var f = d.getElementsByTagName(s)[0],
                    j = d.createElement(s),
                    dl = l != 'dataLayer' ? '&l=' + l : '';
                j.async = true;
                j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i + dl;
                f.parentNode.insertBefore(j, f);
            })(window, document, 'script', 'dataLayer', 'GTM-XXXXXXX');
        )
        dataProcessingService = Google Tag Manager
    }
}

        EXT:site_package/Configuration/TypoScript/Extensions/LiaUsercentrics/Setup.typoscript
    

plugin.tx_liausercentrics.jsInline {
    10 {
        value < page.FooterData.googleTagManager.value
        dataProcessingService = Google Tag Manager
    }
}

[usercentricsIsActive('{$plugin.tx_liausercentrics.settings.activate}', '{$plugin.tx_liausercentrics.settingsId}')]
    page.FooterData.googleTagManager >
[global]

Where to get help

You can get help in the TYPO3 Slack https://typo3.org/community/meet/chat-slack, Ask a question in the official TYPO3 forum, https://talk.typo3.org/c/typo3-questions/19 or contact the extension author.

Report Issues

You can report issues at https://github.com/LOUISINTERNET/lia_usercentrics/issues.

Official documentation

For more information on Usercentrics, visit the official documentation.

Here is the link to the Smart Data Protector dokumentation.

Frequently Asked Questions (FAQ)

See chapter Installation.

(1/1) #1741944668 LIA\LiaUsercentrics\Exceptions\LiaUsercentricsException
The Usercentrics settings are not set.

This error occurs when the necessary Usercentrics settings have not been properly configured in your TYPO3 installation. The extension is unable to find the required TypoScript configuration for Usercentrics, which is essential for managing cookie consent and other privacy settings.

Go to the TYPO3 backend.
Navigate to the Site Management > TypoScript module.
Select the page where you want the Usercentrics settings to be applied (typically the root page of your site).
Select Edit TypoScript Record and klick on Edit the whole TypoScript record
In the "Advanced Options" tab, scroll down to find the list of static templates.
Add the necessary static template for Usercentrics, "LIA Usercentrics (lia_usercentrics)".
Save the changes.

This will ensure that the required TypoScript settings are loaded and the extension can properly access the Usercentrics configuration.

LIA Usercentrics

Installation

Configuration

Frequently Asked Questions (FAQ)

How to get help

Installation

Install LIA Usercentrics with Composer

Install LIA Usercentrics in Classic Mode

Configuration

Basic Configuration

Smart Data Protector

JavaScript configuration

Basic configuration

Basic configuration

Best Practice

Language

Footer link

TCF enabled

Smart Data Protector configuration

Restrict the Smart Data Protector

Overlay for Custom service integration

Block JavaScript

Blocking of files

Blocking of inline JavaScript

Where to get help

Report Issues

Official documentation

Frequently Asked Questions (FAQ)

How can I install this extension?

I'm getting an exception!

How to can I include the TypoScript?

Where to get help?