README

Installation

Install this extension with the Extension Manager, or with composer.
Go to the extension configuration and set your license key and output folder. You must set this folder accordingly in case your TYPO3 installation is in a subdirectory relative to the web server document root.
Add the static TypoScript named "Cookie Consent" to your instance with the "Template" backend module.
- Open up the "Template" module in the backend of TYPO3.
- Go to your root site page within the page tree.
- Choose "Info/Modify" at the select on the top.
- Click on the button "Edit the whole template record."
- Select the tab "Includes."
- Choose the template "Cookie Consent (sg_cookie_optin)" on the multi select box with the name "Include static (from extensions)"
- Save
Go into the "Cookie Consent" backend module, configure it and save it once.

Update from version 6 to version 7

If you update from sg_cookie_optin v6, please follow the instructions in UPGRADE.md.

How to add scripts / How to rewrite the script HTML?

Unfortunately, we can't support HTML code for the cookie scripts, because of security cases. So you need to rewrite the HTML code to javascript. Here's an example for the Google Tag Manager:

HTML:

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
    window.dataLayer = window.dataLayer || [];

    function gtag() {
        dataLayer.push(arguments);
    }

    gtag('js', new Date());
    gtag('config', 'GA_MEASUREMENT_ID');
</script>

JavaScript:

var script = document.createElement('script');
script.setAttribute('type', 'text/javascript');
script.setAttribute('async', true);
script.setAttribute('src', 'https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID');
document.body.appendChild(script);

window.dataLayer = window.dataLayer || [];

function gtag() {
    dataLayer.push(arguments);
}

gtag('js', new Date());
gtag('config', 'GA_MEASUREMENT_ID');

How is the structure of our cookie?

In order for us to know which cookie groups the user has accepted, we must also store an essential cookie. The structure is as follows:

Name: cookie_optin Example data: essential:1|analytics:0|performance:1 Explanation: The user has accepted the essential and performance groups, but not the analytics one.

Additional Features

Open a page without showing the cookie consent

Just add the parameter "?disableOptIn=1" to your URL, so the necessary JavaScript and Css, which shows the dialog, isn't loaded anymore. Here is an example:

https://www.sgalinski.de/?disableOptIn=1

Show the cookie consent, after accepting it

Just add the parameter "?showOptIn=1" to your URL, so the dialog shows up again and the accepted cookies can be modified. Here is an example:

https://www.sgalinski.de/?showOptIn=1

External content

Add an additional description for a iframe on the opt in

Just add the data attribute "data-consent-description" to an iframe HTML tag, like in the example below:


<iframe width="560" height="315" src="https://www.youtube-nocookie.com/XYZ"
        data-consent-description="An additional description about this video!"></iframe>

Change the button text for a specific external content element

Add the data attribute "data-consent-button-text" to an iframe HTML tag, like in the example below:


<iframe width="560" height="315" src="https://www.youtube-nocookie.com/XYZ"
        data-consent-button-text="Custom text here"></iframe>

Whitelist an element for the external content opt in logic

There are three ways to do this, and all of them will result in having this element and all of its children whitelisted for the external content protection:

Just add the data attribute "data-iframe-allow-always" or "data-external-content-no-protection" to an iframe HTML tag, like in the example below:


<iframe width="560" height="315" src="https://www.youtube-nocookie.com/XYZ" data-iframe-allow-always="1"></iframe>

Add the class "frame-external-content-no-protection" to the HTML tag.


<iframe width="560" height="315" src="https://www.youtube-nocookie.com/XYZ"
        class="frame-external-content-no-protection"></iframe>

From the TYPO3 Backend Page module edit the element's appearance and set the Frame Class "Unprotected External Content"

Protect any kind of DOM element with the external content protection (force opt-in)

There are three ways to do this, and all of them will result in replacing this element and all of its contents with the opt-in dialog:

Add the data attribute "data-external-content-protection" to the HTML tag.


<div class="test-content-protection" data-external-content-protection="1">
    Content comes here
</div>

Add the class "frame-external-content-protection" to the HTML tag.


<div class="test-content-protection frame-external-content-protection">
    Content comes here
</div>

From the TYPO3 Backend Page module edit the element's appearance and set the Frame Class "External Content"

Modify the generated JSON file

You can do that by attaching to the hook $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['sg_cookie_optin']['GenerateFilesAfterTcaSave']['preSaveJsonProc']. It sends an array $params with the following entries:

pObj = An instance of the StaticFileGenerationService. It contains the siteRootId as well as a few public methods that can come in handy.
data = A reference to the data array that will be written in the JSON file.
languageUid = The uid of the current language

Example:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['sg_cookie_optin']['GenerateFilesAfterTcaSave']['preSaveJsonProc'][] =
    function ($params) {
        $params['data']['newDataEntry'] = 'newValue';
    };

Extending the Statistics Module

The Statistics.js module in sg-cookie-optin is bundled using Vite to ensure compatibility with TYPO3 v13. This module incorporates dependencies like Chart.js and provides a flexible way to extend or modify its behavior for custom use cases.

Overview of the Bundling Configuration

The Vite configuration ensures that the module is output to:

Resources/Public/JavaScript/Backend/dist/statistics.es.js

This file is optimized for modern browsers (es format) and includes all necessary dependencies, such as Chart.js.

Prerequisites for Extension

To extend or customize the Statistics.js module, ensure you have the following:

Node.js installed (version 16 or later recommended).
Vite installed in your local environment. You can install it globally or as a development dependency:
```
npm install vite --save-dev
```
Familiarity with modern JavaScript and ES Modules.

Extending the Module

Follow these steps to modify or extend the functionality:

Clone the Repository Clone the sg-cookie-optin extension repository or work on your local copy.
Locate the Source File The Statistics.js source file is located at:
```
Resources/Public/JavaScript/Backend/Statistics.js
```
Modify the Code Open Statistics.js and implement your changes. For example, you might want to add a new chart type or extend existing functionality.
Rebuild the Module After modifying the code, rebuild the module using Vite:
```
npm run build
```
This will regenerate the bundled file in:
```
Resources/Public/JavaScript/Backend/dist/statistics.es.js
```
Integrate the Updated Script Ensure the new statistics.es.js file is correctly loaded in your TYPO3 backend module. Clear caches in TYPO3 to reflect the changes.

Content Security Policy (CSP) nonces in sg_cookie_optin

Starting with version 7.1.0, sg_cookie_optin integrates with TYPO3’s CSP nonce mechanism to make the extension work out-of-the-box on installations that enforce a strict Content Security Policy.

What this means

On every frontend request, TYPO3 generates a unique nonce value and sends it in the CSP header (script-src/style-src).
sg_cookie_optin uses that nonce for the assets it renders so that browsers are allowed to execute or apply them when CSP is enabled.

How we add the nonce

We obtain the per-request nonce from $GLOBALS['TYPO3_REQUEST']->getAttribute('nonce') (an instance of TYPO3\CMS\Core\Security\ContentSecurityPolicy\ConsumableNonce).
We then add a nonce attribute to the following elements the extension renders:
- Inline JSON: …
- Inline JavaScript (when assets are rendered inline)
- External JavaScript
- Inline CSS …
- Preload links for JS and CSS: (Note: current CSP enforcers ignore nonce on , but adding it is harmless and future-proof.)

Caching implications (important)

TYPO3 replaces cached nonce placeholders with the request-specific nonce just before sending the response using Frontend NonceValueSubstitution. We use the provided ConsumableNonce->consume() API accordingly, so TYPO3 can safely substitute nonces even when the page content is cached.
Reverse proxies/CDNs: If a reverse proxy caches the fully substituted HTML together with the CSP headers, subsequent users could receive a stale nonce that does not match the CSP header. In most typical TYPO3 setups the substitution happens late enough to avoid proxy caching of placeholders, but please verify your proxy configuration:
- Either bypass proxy caching for pages that set CSP nonces, or
- Ensure the proxy varies/not caches pages that include CSP nonces and their CSP headers, or
- Use TYPO3’s default page caching only (no additional full-page caching at the edge) for pages where CSP is enforced with nonces.

What end-users (integrators) may need to configure

Enable/adjust CSP in your site configuration so the policy allows nonce-based execution and styles:
- script-src: include 'self' and 'nonce-' or generally allow 'nonce-*' via TYPO3’s CSP configuration (TYPO3 emits the concrete nonce value per request).
- style-src: include 'self' and the nonce as above. If you still need inline styles without nonce, you would have to add 'unsafe-inline' (not recommended).
If you previously used hashes ('sha256-…') for inline assets, you can keep them, but the nonce must then be present and match for the sg_cookie_optin rendered tags, otherwise the browser will block them.
If you disabled inline asset rendering in sg_cookie_optin (render_assets_inline = 0), we still add the nonce to the external element. Make sure your CSP allows loading that URL (script-src) from your domain/base URL.</li> </ul> Backwards compatibility <ul> <li>If CSP is not enabled on your site, the nonce attribute is simply omitted and nothing changes for you.</li> <li>The nonce on <link rel="preload"> is ignored by browsers if CSP does not evaluate it; it does not break older setups.</li> </ul> Troubleshooting <ul> <li>Browser blocks cookie opt-in script/style with a CSP error: Check that your CSP header includes a nonce on script-src/style-src and that it matches the one TYPO3 generated. In TYPO3 v13+, the backend module “HTTP headers” or your site YAML can be used to configure CSP.</li> <li>Using a CDN/reverse proxy and seeing random CSP errors: Revisit the proxy caching notes above; ensure dynamic nonce responses are not cached across requests.</li> </ul> References <ul> <li>TYPO3 CSP and nonces: <a href="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Security/ContentSecurityPolicy/Index.html">https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Security/ContentSecurityPolicy/Index.html</a></li> <li>TYPO3 ConsumableNonce API (class source): <a href="https://github.com/TYPO3/typo3/blob/main/typo3/sysext/core/Classes/Security/ContentSecurityPolicy/ConsumableNonce.php">https://github.com/TYPO3/typo3/blob/main/typo3/sysext/core/Classes/Security/ContentSecurityPolicy/ConsumableNonce.php</a></li> <li>TYPO3 Frontend NonceValueSubstitution (class source): <a href="https://github.com/TYPO3/typo3/blob/main/typo3/sysext/frontend/Classes/Cache/NonceValueSubstitution.php">https://github.com/TYPO3/typo3/blob/main/typo3/sysext/frontend/Classes/Cache/NonceValueSubstitution.php</a></li> </ul>

sgalinski / sg-cookie-optin

Maintainers

Details