---
title: "Basic configuration"
manual: "LIA Usercentrics"
version: "1.2"
permalink: "https://docs.typo3.org/permalink/lia_ext/lia_usercentrics:basic-configuration@1.2"
source: "Configuration/Basic-configuration.rst"
rendered: "2026-10-16T12:57:53+00:00"
---

# Basic configuration {#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 {#basic-configuration-1}

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 {#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**

```typoscript
plugin.tx_liausercentrics {
  srcUrl = https://web.cmp.usercentrics.eu/ui/loader.js
  settingsId =
  ucQueryParameter =
  settings {
    activate = 0
    async = 0
    tcfEnabled = 0
    useSmartDataProtector = 0
    useConsentIntegration = 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
useSmartDataProtector to 1.
To block iframes and custom integrations without the Smart Data Protector, set
the constant useConsentIntegration to 1, see
[consent integration](https://docs.typo3.org/permalink/lia_ext/lia_usercentrics:consent-integration-configuration@1.2).

> [!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.

### Exclude pages {#exclude-pages}

<!-- TODO: no Markdown rendering for "versionchanged" -->

Before version 1.2.0, excludedPages and ucQueryParameter had no
effect. Check both constants when you update an existing project.

Enter a comma separated list of page UIDs in `excludedPages` to render these
pages without Usercentrics. The pages render YouTube and Vimeo videos as
regular iframes.

Set `ucQueryParameter` to a value to render a page without Usercentrics when
the URL contains the query parameter `uc` with this value, for example
`?uc=my-secret-value`.

Requests with the query parameter `uc` bypass the page cache, whatever its
value. Otherwise a page rendered without Usercentrics would be cached and
delivered to all visitors. Add `uc` to the excluded cHash parameters, so the
URL works without a cHash:

**config/system/settings.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash']['excludedParameters'][] = 'uc';
```

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

```typoscript
plugin.tx_liausercentrics {
  ucQueryParameter = my-secret-value
  settings {
    excludedPages = 12, 34
  }
}
```

### Language {#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**

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

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

### Footer link {#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.

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

### TCF enabled {#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.

> [!NOTE]
> **See also**
>
> [IAB TCF documentation](https://usercentrics.com/knowledge-hub/iab-tcf/) on the Usercentrics website.

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

```typoscript
plugin.tx_liausercentrics {
  settings {
    tcfEnabled = 1
  }
}
```

This renders the following script tag in the page header:

```html
<script id="usercentrics-cmp" src="..." data-settings-id="..." data-language="..." data-tcf-enabled></script>
```