Usage¶

The foundation of the Usercentrics for TYPO3 Integration is the TYPO3’s Asset Collector. This extensions offers multiple entry points to integrate external scripts and inline scripts guarded by Usercentrics.

Important

Each include requires an identifier which must match the data processing service name as configured in Usercentrics.

TypoScript¶

In TypoScript, all scripts are configured within the plugin.tx_usercentrics namespace, which is divided into two sections.

External script files are configured within plugin.tx_usercentrics.jsFiles, whereas inline scripts are configured in plugin.tx_usercentrics.jsInline.

The following arguments are accepted:

dataServiceProcessor (string) mandatory - the data processing service name as configured in Usercentrics
file (string) mandatory for external files - the path to the script file
value (string) mandatory for inline scripts - the JavaScript being rendered inline
attributes (array) - a key / value dictionary with attributes to be rendered in the :html:`<script>` tag
priority (bool) - defines whether an include is rendered in :html:`<head>` or at the bottom of :html:`<body>`

Example:

plugin.tx_usercentrics {
    jsFiles {
        10 {
            dataServiceProcessor = Google Analytics
            file = https://www.google-analytics.com/analytics.js
            attributes {
                async = async
            }
        }
    }

    jsInline {
        10 {
            dataServiceProcessor = Google Analytics
            value (
                window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
                ga('create', 'UA-XXXXX-Y', 'auto');
                ga('send', 'pageview');
            )
        }
    }
}

Warning

In case Usercentrics is included into an existing project, all usages of page.includeJS and alike must be checked and migrated.

Fluid¶

Scripts that need consent may be loaded via Fluid if necessary, e.g a content element needs another third party library. The extension ships the ViewHelper T3G\AgencyPack\Usercentrics\ViewHelpers\ScriptViewHelper whose namespace may need to be imported.

The following arguments are accepted:

src (string) mandatory for external files - the path to the script file
dataServiceProcessor (string) mandatory - the data processing service name as configured in Usercentrics
attributes (array) - a key / value dictionary with attributes to be rendered in the :html:`<script>` tag
priority (bool) - defines whether an include is rendered in :html:`<head>` or at the bottom of :html:`<body>`

If inline scripts are used, the JavaScript must be written as content of the ViewHelper.

Example:

<html xmlns:usercentrics="http://typo3.org/ns/T3G/AgencyPack/Usercentrics/ViewHelpers">
  <usercentrics:script dataServiceProcessor="Google Analytics" src="https://www.google-analytics.com/analytics.js" />
  <usercentrics:script dataServiceProcessor="Google Analytics">
     window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
     ga('create', 'UA-XXXXX-Y', 'auto');
     ga('send', 'pageview');
  </usercentrics:script>
</html>

PHP¶

Since this extension uses TYPO3’s Asset Collector it’s fairly easy to use Usercentrics within PHP code.

Example:

$dataServiceProcessor = 'Google Analytics';
$assetCollector = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Page\AssetCollector::class);

$identifier = \TYPO3\CMS\Core\Utility\StringUtility::getUniqueId($dataServiceProcessor . '-');
$file = 'https://www.google-analytics.com/analytics.js';
$attributes = [
    'type' => 'text/plain',
    'data-usercentrics' => $dataServiceProcessor
];
$assetCollector->addJavaScript($identifier, $file, $attributes);

$identifier = \TYPO3\CMS\Core\Utility\StringUtility::getUniqueId($dataServiceProcessor . '-');
$source = 'window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;'
    . 'ga(\'create\', \'UA-XXXXX-Y\', \'auto\');'
    . 'ga(\'send\', \'pageview\');';
$attributes = [
    'type' => 'text/plain',
    'data-usercentrics' => $consentName
];
$assetCollector->addInlineJavaScript($identifier, $file, $attributes);

Important

A different internal $identifier must be used per include in the same script group.

Warning

In case Usercentrics is included into an existing project, all usages of PageRenderer->addJsLibrary() and alike must be checked and migrated.