Cookie Opt-In Extension for TYPO3

When importing, you must ensure that at least the default language is present in the exported file, or that the original configuration contains the main language of the page into which the file is to be imported. If other languages do not match completely, this is not a problem. If there are too many languages in the file, they will simply not be included in the new instance. In the opposite case, if languages (other than the default language) are missing, you just need to add a new translation for the cookie opt-in in this instance.

You will be informed during the import process if the default language is missing or if the number of cookies and scripts does not match in the translations. The latter can lead to the translations not being adapted correctly. Problems that occur as a result can be fixed afterwards.

Proceed as follows when exporting & importing:

1. In the backend of the instance from which you want to export the configurations, go to the Tracking / Cookies module, click on the Export Configuration button at the top and save the exported file.
2. To import the file, switch to a different TYPO3 instance and go to the Tracking / Cookies module in the backend here as well.
3. Now use the Import configuration button. Select the exported file and upload it.
4. You will now see an overview of all existing translations and which of them will be uploaded to the instance. Click Next to complete the import.

If you have already created an entry in this instance, you must delete it in order to use the imported configurations. To delete an entry, go to the Tracking / Cookies module and use the Paper Bin icon to remove the entry you don't need.

The TYPO3 extension can be easily obtained from the TER or installed via Composer. To install the extension with Composer, you need to execute composer require sgalinski/sg-cookie-optin. In both cases, the extension must then be added using the Template module and configured via the Tracking / Cookies module. Both steps are described below.

In order for the integration to work without problems, you must configure a so-called siteroot. You can see whether you have already configured a siteroot for your website by the small globe icon next to the name of the page in the page tree. If you do not see a globe there, it means you have not defined a root site yet. To configure a siteroot, proceed as follows.

1. Open the page properties of the desired page by right-clicking on the page. Select Edit from the menu that appears.
2. Go to the Behaviour tab and activate the checkbox 'Use as root page'.

Enter the licence key in the backend module Settings under Extension Configuration at sg_cookie_optin. Alternatively, you can also test our Cookie OptIn Extension for 24 hours in demo mode.

Tab 3: External Content

To activate the Cookie Consent for Iframes, simply check the box in the External Content tab and fill in the Title or Description fields and specify the text for the button labels.

Similar to essential cookies you can specify all cookies coming from external scripts under the field Description. The information can be seen in the cookie information part of the Opt-In field in the frontend.

In the Text fields you define the button labels for external content. Furthermore, you can assign an additional text under the button to load the external content (see screenshot below).

Edit Colors

The column Colors is located under the column Texts (button labels). Here you can adjust the color of the box and the buttons.

iFrame Replacement Background Image

This option is available from version 5 of the Cookie Opt-In Extension. In this field, you can enter a URL path to an image that will be used as a background for the iFrame Replacement box. If you set it, it will be used per default for all external content elements. If you would like to set a specific image just for one element, you can make use of the HTML attribute data-sg-cookie-optin-background-image in the element’s source code. Setting it to a path to image would override the default background image for this element. If you would like more than one elements to share the same image, or want to make more complex adjustments to the iFrame Replacement design, please refer to the section of the Services tab.

The list automatically includes reCAPTCHA, a service that allows distinguishing humans from bots. You can add more external content (IFrame, objects, audio and video HTML tags), it will be excluded from external protection.

Change the button text for a specific external content element

Just add the data attribute data-consent-button-text to an iframe HTML tag, like in the example below.

External Content – iFrame Description

You can insert a description to the external content. To do so, you need to add a corresponding attribute to the HTML code of the iFrame: data-consent-description. The iFrame tag in the HTML content element may then look like this:

Extra Layer of External Content Protection

When you turn the external content protection option on, we automatically block any requests to the external servers and replace those page elements with the opt-in element.
However there are traces in the browser that such requests have been attempted. If you want to remain on the safe side, you can edit the HTML of these elements and replace the src attribute with data-content-replace-src.

For example <iframe src="https://external.website.com"> can be changed to <iframe data-src="https://external.website.com">. This way no request will be attempted in the initial load and our Cookie Opt-In will take care of the rest automatically. This only works for <iframe> and <object> tags.

Please bear in mind that this will not automatically work for content that you have loaded after the initial page load, for example with AJAX. In those cases you need to implement the protection manually. We strongly encourage you to make use of our API for this purpose.

If iFrame is not accepted

When a user does not accept external content, Iframes are not loaded and are displayed as a box. The visitor now has the option to load only one iframe. When clicking on the Open settings button, a small Cookie Consent window appears (see screenshot below), where all external content or only one iframe can be accepted.

To do this, first create a new record under Services using the Create new button.

Identifier

When we create a new service, first we have to give it an unique name. It’s called the identifier. The identifier must be unique for each service, otherwise the functionality might break, as the script wouldn’t know which service to use exactly.

Template

By default the services use the default iFrame Replacement Template Code. You may choose to overwrite and change it for your Service. To achieve that you have to mark the box Overwrite Template and then provide a custom iFrame Replacement Template Code.

Background Image

In the field iFrame Replacement Background Image you can set a specific background image for this Service. This would override the default background image set in the tab External Content. However, it would not override a background image set in the HTML attribute data-sg-cookie-optin-background-image. The HTML attribute in the element itself is considered the most specific description of the element and thus has the highest priority.

Assigning the Service to an Element

Now we have to somehow tell the SG Cookie Optin that a given element belongs to this Service. We can achieve that in two ways.

• The straightforward way is to add an HTML attribute to the external content data-sg-cookie-optin-service and set it to the identifier. For example: data-sg-cookie-optin-service="youtube" would try to find a service with identifier 'youtube' and, if successful, would load the settings from that Service.
• The other possibility is to use the lowest field in the services. In this field you can enter regular expressions (one per each line) that would try to match the source of the element. For example, if you want to have one special template for all the external videos in your website, you can add a regular expression that would match the URL of the different video platforms that you use – YouTube, Vimeo, Dailymotion, etc. If any of the regular expressions match the source – the Service automatically gets assigned to this element.

Adding Additional Behavior to your Services

You could even go the extra mile and execute custom JavaScript code any time your Service matches. To do that you must add an EventListener to our event externalContentReplaced. It will fire once the content is replaced and in the event.detail you will be able to see which Service (if any) had been matched. It will also contain a reference to the replacement element. The sky is the limit on what you can do from there.

You can refer to our Demo page (section 'Edit External Content after Loading') to see how we made a dynamic template, that automatically replaced the background image of the replacement box with the corresponding YouTube video thumbnail!

Tab 5: Banner

Cookie name

The Name field is a regular expression. These are used to check if a given text matches a certain pattern. The value you enter in the text field is the pattern against which each cookie name is checked. Cookies that match this pattern will be deleted if a user does not agree to the cookie group. You can test the syntax, for example, on the page: regex101.com. After saving, you should clear the cache and reload your page in the frontend. Then try to give consent for a cookie and remove it. Check the browser console to see if cookies are being deleted or if JavaScript errors are occurring.

Procedure for a multi-domain environment

In a multi-domain system, the method described above can lead to complications that you can avoid with the procedures presented below. Among other things, these alternatives allow you to set the ID (variable) directly in TypoScript.

For the first variant, enter the following code in the HTML field (again, the Google Tag Manager is used as an example):

The ID/variable is then set via TypoScript in the TS template of the instance and can be overwritten with conditions:

Alternatively you can integrate the script completely via TypoScript:

The parameter settings.gtm.id can then be set dynamically via TypoScript Conditions. You then only have to enter the line addTagManager(); in the extension.

With the latter variant the variable/ID can be set via TypoScript and at the same time it is no longer necessary to copy the code to the different domains.

Tab 8: Settings

Overwrite Base-URL

You can use this field to overwrite the URL from which the files are loaded in your website. If it is on another (sub)domain, please make sure to include it in your CORS policy header.

Minify Generated Files

All CSS and JavaScript files are compressed. If you don't want this, you have to uncheck the box Minify generated files.

Activate TEST mode

You should activate the test mode if you are still setting up the cookie consent on an existing page. If you enable this mode, the Cookie Opt-In window will not be displayed to the site visitors. To check the appearance and functionality, the dialog can be opened at any time with ?showOptin=1 at the end of the address bar in the frontend.

Disable OptIn for this language

Not all users of your site come from the EU area? - Then they also do not have to deal with a cookie banner. Put a check mark in the appropriate translation to remove the banner there.

If you use the Google Tag Manager (GTM) you have to make adjustments in the GTM after integration & configuration of the Cookie Consent Extension.

The first requirement is to create the tracking groups in the Cookie OptIn Extension and add the GTM script in all relevant groups. This avoids double loading. Also note alternative procedures when using multi-domain systems.

The following explanations are based on the exemplary script and cookie groups Analytics and Marketing. The corresponding group keys, which you enter in the tab General of a group, are marketing and analytics in our example.

The script for the Google Tag Manager and the tab Scripts is shown in the figures below.

After the configuration of the Cookies Consent on your website, you must now carry out several actions in the GTM for a complete and successful integration.

The function opens the Cookie OptIn dialog.

Parameter

• contentElement {dom} (optional) – If the parameter is specified, the dialog is appended as child of the specified content element, if not, it is appended to the <body> tag.
• options (optional) – You can pass other options as JSON. The supported option is:
  • {boolean} hideBanner: Hides the cookie banner if it has been enabled in the settings.

This parameter adds a trigger function to all protected elements. It is triggered if the respective element has received the approval. You can filter the elements by a CSS selector.

This is very handy if you want to apply a special logic after adding an element to the DOM (e.g. resizing the element or using a highlight effect).

Parameter

• callback {function} – Represents the callback function that is triggered in case of the event.

• selector {string} (optional) – A CSS selector is used to filter unaccepted external content elements. Please note that at this point in the runtime, these elements are extracted from the DOM and replaced by the consent elements. So you cannot use parent selectors in this string. These selectors can only be used to check the external element itself for attributes – id, class, src etc.

With this function you can programmatically replace each element on the page with a consent box. Try to execute the command below in the developer tools for testing purposes.

This function can be used for external elements that are loaded with AJAX.

Parameter

• externalContent {dom}: Represents the DOM element to be replaced.

Example

SgCookieOptin.replaceExternalContentWithConsent(document.getElementById('c20534'));

We have introduced some JavaScript events to give developers more ways to programmatically influence the behavior of the Cookie OptIn. These are bubbling events that can be attached to the document.body or any other DOM element that is at a higher level than the element itself. The elements are JavaScript CustomEvent objects that you can work with just like any other JavaScript event. The following events are available.

cookieOptinShown

The event can be used to add additional logic and scripts that will be run after the Cookie OptIn dialog is displayed.
Fired when: The Cookie OptIn Dialog has been displayed.
Event target: document.body
Event detail: {}

cookieOptinHidden

The event can be used to add additional logic and scripts that will be run after the Cookie OptIn dialog is hidden or closed.
Fired when: The Cookie Optin Dialog has been hidden or closed.
Event Target: the parent of the cookie optin
Event Detail: {}

externalContentConsentDisplayed

The event can be used to add additional logic and scripts that will be run after the OptIn dialog for external content is displayed.
Fired when: The details for an external content have been displayed.
Event Target: the wrapper element of the external content itself
Event Detail: {}

consentCookieSet

The event helps to read users' settings and add additional custom logic. It can be used when you want to add your own statistics tracking or set the cookie on other domains and subdomains, etc.
Fired when: The user has selected his preferences and the cookie has been set (Accept or Accept all).
Event Target: document.body
Event Detail: {cookieValue: String}

Tip: To extract the cookieValue information, you can then pass it to the method SgCookieOptin.readCookieValues(event.detail.cookieValue).

addedLoadingHTML

With this event you can change this HTML or add more HTML in specific cases.
Fired when: A custom script’s loadingHTML has been added.
Event Target: document.head
Event Detail: {src: String}

Name: addedLoadingScript

The event can be used to add more logic to the JavaScript or change it in some particular context.
Fired when: A custom script’s loadingScript has been added.
Event Target: the script itself
Event Detail: {src: String}

externalContentReplaced

This event can be used to modify the replacement box or the replaced element after it has been replaced.
Event Target: The replacement container
Event Detail: {externalContent: HTMLElement, container: HTMLElement}

beforeExternalContentReplaced

This event can be used to modify the replacement box or the replaced element before it has been replaced and after the service template has (or has not) been matched.
Event Target: The replacement container
Event Detail: {externalContent: HTMLElement, container: HTMLElement, service: service}

Example

document.body.addEventListener('cookieOptinShown', function() {

console.log(‘We just opened the cookie optin dialog! We can now change the styling of some elements dynamically at this point.’);

});
 

document.body.addEventListener('cookieOptinHidden', function() {

console.log(‘We just closed the optin dialog! We can now revert those stylings back to how they were initially.’);

});

Below is a list of commands that you can use on your web server or add as scheduler tasks. You use them in your shell as follows.

./vendor/bin/typo3 sg_cookie_optin:command_name arg1 arg2 ...

• sg_cookie_optin:generate_static_files [siteRootId] – Generates the static JavaScript, JSON and CSS files in your fileadmin directory. It replicates the same function as when you save your configuration. It comes in handy, for example, for deployment, unit tests or similar CI/CD tasks.
  • Arguments:
    • int siteRootId is required – This is the PID of the site root. If you are in a (inconsistent) state that contains more than one configuration entry for the site root, note that the script will export only the first one it finds, assuming it is the correct one.

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';
    };