What does it do?

It provides a user consent popup. It asks for approval to include tracking objects (cookies, images or any HTML) and includes the objects when consented.

It allows tracking from the very first page (including referrer).

Consents are managed in groups and saved to a cookie.

It provides a stable API to work with in JavaScript.

It removes HTML-cookies of tracking objects after the user has revoked consent.

Demo

You can click around the included demo themes here. Have a look at the JavaScript console to see when tracking gets enabled.

You can also try out the "Do-not-track" setting of your browser which triggers a message inside the popup (in the "marketing" group) when enabled.

Screenshots

(Click on the screenshots to open the full resolution.)

Requirements

• If you reimplement your own theme, it has no requirements at all

• for the example themes:

  • Bootstrap 3/4/5 CSS
  • Bootstrap 3/4/5 JavaScript for collapse and modal
  • jQuery
• we also apreciate new and creative custom themes

Installation

1. Get the extension:

   1. From the Extension Manager: Open the Extension Manager module in the TYPO3 backend and choose 'Get extensions'. Search for the extension key cookieman. Click on the extension title to get a list of all available versions. Import and install the version which is compatible to your TYPO3 version.
   2. From the TYPO3 Extension Repository (TER): You can download ZIP archives of different versions from https://extensions.typo3.org/extension/cookieman. Upload the file afterwards in the Extension Manager.
   3. With composer: Use composer req dmind/cookieman. This will load a compatible version available from Packagist.

2. Integration: Include the static TypoScript "Cookieman" in your root template or reference the necessary files in your site package. This will get you a group mandatory with the tracking object CookieConsent.

   For evaluation purposes: Include the static TypoScript "Cookieman (Example configuration of groups and tracking objects)" to see a full example with multiple groups and tracking objects.

3. Configure the extension with TypoScript constants and setup (see Usage of cookies).

Find out which tracking objects are used

You can check your page with an empty cookie storage with your browser and see which cookies gets inserted in your browser. Or you can use a service like Cookieservice to fetch a page or sign up for services that crawl your whole site regularly for cookies.

There might be connections made to external servers to access tracking pixels or other content that warrant a user consent, too. This applies to YouTube (use youtube-nocookie.com) and CDNs (Google Fonts, Bootstrap and other frontend libraries - recommendation: do not use external connections at all if not necessary).

Also other means for tracking might be used, like HTML5 Web Storage (localStorage). It is a task for the official Data Security Officer of the site to decide what needs to be consented. If done correctly, you should be able to find a note about used tracking services in the Data Privacy Statement of the website.

If you have control over how the tracking object is inserted you can have Cookieman handle that for you. Otherwise you can make the actual inclusion of the tracking object dependent on a Cookieman-API-call or a presence of a certain string in Cookieman's cookie "CookieConsent" - this is recommended if you are managing several tags with Google Tag Manager (set its trigger to "cookie ‹CookieConsent› contains ‹group name, e.g. "marketing"›).

Example

This example configuration is based on the base TypoScript configuration (see Installation) without the example template.

# include definition of TrackingObjects
@import 'EXT:cookieman/Configuration/TypoScript/TrackingObjects/*.typoscript'

plugin.tx_cookieman.settings {
    trackingObjects {
        # extend the existing configuration for 'Matomo'
        Matomo {
            inject >
            inject (
            <script type="text/javascript">
              var _paq = window._paq || [];
              _paq.push(['trackPageView']);
              _paq.push(['enableLinkTracking']);
              (function() {
                var u="//my-piwik-server.my-domain.com/";
                _paq.push(['setTrackerUrl', u+'matomo.php']);
                _paq.push(['setSiteId', 'my site ID']);
                var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
                g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
              })();
            </script>
            )
        }

        # add my own custom tracking solution
        # if you have a useful configuration and want to share, we would be happy if you did a pull request!
        MyOwnTrackingPixel {
            inject = TEXT
            inject {
                insertData = 1
                value = (
                    <div>Here be dragons <img src="/{path : EXT:my_ext/Resources/Public/Image/MyImage.png}?{date : U}"></div>
                    <script>alert('oh la la!')</script>
                )
            }
            show {
                # each element here represents one line of information in the consent popup
                pixelphp {
                    duration = 1
                    durationUnit = months
                    type = pixel
                    provider = My Website Inc.
                }
            }
        }
    }

    groups {
        # my new group
        mygroup {
            trackingObjects {
                0 = Matomo
                1 = MyOwnTrackingPixel
            }

             respectDnt = 1
             showDntMessage = 1

        }
    }
}

plugin.tx_cookieman._LOCAL_LANG {
    en {
        trackingobject\.pixelphp = You can translate the name, but you do not have to.
        trackingobject\.pixelphp\.desc = My own tracking pixel does not really track you. It's just here to cheer you up.
        group\.mygroup = My group is my castle.
        type\.pixel = Tracking pixel
    }
    default < .en
}

Make the consent revokable

It is recommended to include a snippet like the following on your data privacy statement page to allow your users to adjust their cookie preferences:

<button onclick="cookieman.show()">
  Adjust your cookie preferences
</button>

resourcesBasePath

resourcesBasePath

| Data type: data-type-path | Default: EXT:cookieman/Resources | Example: EXT:mysitepackage/Resources |

Path to directory that holds the themes. Default enables the shipped demo themes. See Custom themes how to create a new theme.

theme

theme

| Data type: data-type-string | Default: bootstrap4-modal | Example: my-theme |

Name of the theme. It is used to extend the resourcesBasePath to create the full path to templates and assets.

The shipped default themes are these: Themes directory on Github

You can check them out on our Demo page.

Of course you can use your own custom theme (see Custom themes).

links.dataProtectionDeclarationPid

links.dataProtectionDeclarationPid

| Data type: data-type-page-id | Example: 123 |

page UID of data privacy statement page - the Cookieman modal will not be automatically opened on this page (see When is the popup shown to users?).

links.dataProtectionDeclarationAnchor

links.dataProtectionDeclarationAnchor

| Data type: data-type-string | Example: c456 |

You can set an (optional) anchor (TYPO3-lingua "section") on the data privacy statement page.

links.imprintPid

links.imprintPid

| Data type: data-type-page-id | Example: 123 |

page UID of imprint page - the cookieman modal will not be automatically opened on this page (see When is the popup shown to users?).

links.imprintAnchor

links.imprintAnchor

| Data type: data-type-string | Example: c456 |

You can set an (optional) anchor (TYPO3-lingua "section") on the imprint page.

minify

minify

| Data type: boolean | Default: 1 |

Cookieman comes with both minified and regular stylesheets and JavaScripts for the demo themes.

It set to 1, the minified versions of the .css and .js files are used. You can set it to 0 for debugging purposes.

groups

groups

| Data type: array | Default: mandatory |

Holds the group configurations. A group contains several tracking objects.

By default, it only contains the 'mandatory' group, which includes the CookieConsent settings cookie. See a full TypoScript Configuration example.

groups.<group-key>

groups.<group-key>

| Data type: array | Default: mandatory |

A single group. The group's key (name) should not contain spaces and non-ASCII characters.

It will be saved in the settings cookie and can be checked with JavaScript: hasConsented('‹group-key›')

groups.‹group-key›.preselected

groups.<group-key>.preselected

| Data type: boolean | Default: 0 (not set) |

If enabled (1), the group's consent checkbox will be already checked when the popup opens.

The default group 'mandatory' has this set to 1.

groups.‹group-key›.disabled

groups.<group-key>.disabled

| Data type: boolean | Default: 0 (not set) |

If enabled (1), the group's consent checkbox will be disabled (cannot be changed).

The default group 'mandatory' has this set to 1.

groups.‹group-key›.trackingObjects

groups.<group-key>.trackingObjects

| Data type: array with numeric indices |

Holds a list of tracking object keys (numbered).

Example:

trackingObjects {
  0 = CookieConsent
  1 = fe_typo_user
}

Copied!

groups.‹group-key›.respectDnt

groups.<group-key>.respectDnt

| Data type: boolean | Default: 0 (not set) |

If set to 1, this group respects to the "Do-not-track" setting of your browser.

groups.‹group-key›.showDntMessage

groups.<group-key>.showDntMessage

| Data type: boolean | Default: 0 (not set) |

If set to 1 and the "Do-not-track" setting of your browser is enabled, an additional message about that is shown inside the group.

trackingObjects

trackingObjects

| Data type: array |

This array holds the tracking object configurations.

The Cookieman extension already provides several preconfigured tracking objects in the folder ./Configuration/TypoScript/TrackingObjects/ (link to the Github repository).

Important

If you add a preconfigured tracking object, you must at least adapt the inject code to your needs!

The default group 'mandatory' only contains the tracking object CookieConsent settings cookie.

trackingObjects.‹tracking-object-key›

trackingObjects.‹tracking-object-key›

| Data type: array | Example: fe_typo_user |

A single tracking object configuration.

Example:

plugin.tx_cookieman.settings.trackingObjects {
    // 'Matomo' is the ‹tracking-object-key›:
    Matomo {
        // injected code, if consent is given:
        inject = TEXT
        inject {
            insertData = 1
            value (
                <script data-what="Matomo" src="/{path : EXT:cookieman/Resources/Public/Js/Injects/example-inject.js}?{date : U}"></script>
            )
        }

        show {
            // set cookies, if consent is given:
            _pk_id {
                duration = 13
                durationUnit = months
                type = cookie_http+html
                provider = Matomo
            }

            // etc.
        }
    }
}

Copied!

trackingObjects.‹tracking-object-key›.inject

trackingObjects.‹tracking-object-key›.inject

| Data type: data-type-html-code / data-type-cobject | Example: <script src="/path/to/tracking-code.js"></script> |

Each HTML tag in here will be appended to the page when the respective group is consented. This can be <script>, <img> or anything else.

You can either use inline script or link to an external file (useful if a HTTP header Content-Security-Policy is set).

If you need a local path from your _assets directory, let TYPO3 build it. We currently recommend using TEXT with insertData = 1 and the getText {path : EXT:…}. The preceding root path (/) is necessary for it to work on subpages. We recommend adding ?{date : U} to add a cache-busting parameter. See the example above.

It has shortcomings (namely the missing base and missing cache busting ?parameter. See https://forge.typo3.org/issues/99203#change-507069).

For v13 we can use the {asset : ...}` getText function (https://review.typo3.org/c/Packages/TYPO3.CMS/+/77018).

trackingObjects.‹tracking-object-key›.show

trackingObjects.‹tracking-object-key›.show

| Data type: array |

The actual rows of the table, each representing one "tracking item" (usually a cookie).

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›

| Data type: array | Example: _pk_id |

A single "tracking item" (e.g. the name of a cookie). A cookie that matches this name will be removed when consent for the group in which this tracking object is included is revoked. (see also trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.htmlCookieRemovalPattern)

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.duration

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.duration

| Data type: data-type-positive-integer | Example: 12 |

The lifetime of the tracking object (only the "number" part).

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.durationUnit

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.durationUnit

| Data type: data-type-string | Example: months |

The lifetime of the tracking object (only the "unit" part).

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.type

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.type

| Data type: data-type-string | Example: cookie_http+html |

The type of tracking.

Possible (default) keywords:

• cookie_http+html: an HTML (=HTTP+HTML) cookie, which is also readable from JavaScript. This is the only type that can be removed after consent has been revoked.
• cookie_http: an HTTP cookie
• pixel: a tracking pixel

Note

You can add your own types by adding a localization string type.‹your-type-key›.

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.provider

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.provider

| Data type: data-type-string | Example: Google |

The provider of the cookie or tracking object.

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.htmlCookieRemovalPattern

trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.htmlCookieRemovalPattern

| Data type: data-type-string | Example: ^_gat(?:_UA-d+-d+)?$ |

You can (optionally) set a regex pattern for cookie names here. It will be used during cookie removal. If would remove all matched cookies when consent for the group in which this tracking object is included is revoked. If this is empty, the tracking object key is used for deletion (see trackingObjects.‹tracking-object-key›).

Note

Cookie removal will only work for tracking object type cookie_http+html. See trackingObjects.‹tracking-object-key›.show.‹tracking-item-key›.type.

Adapt an existing theme

If you want to adapt an existing theme, and not necessarily create a new one, you may want to consider adding another path to the default templates via adapting the root paths as so:

page {
  1365499 = FLUIDTEMPLATE
  1365499 {
    templateRootPaths {
      150 = EXT:my-ext/Resources/Private/cookieman/Templates/{$plugin.tx_cookieman.settings.theme}/
    }
    partialRootPaths {
      150 = EXT:my-ext/Resources/Private/cookieman/Partials/
    }
    layoutRootPaths {
      150 = EXT:my-ext/Resources/Private/cookieman/Layouts/
    }
  }
}

This way, you also do not need to add a cookieman-theme.css and cookieman-theme.js file, which are necessary when creating a full custom theme.

Create a new theme

This is a recommendation how to set up your template structure for a custom extension.

1. Set your base path in TypoScript constants:

plugin.tx_cookieman.settings.resourcesBasePath = EXT:your_ext/Extensions/cookieman/Resources

2. Choose a new theme name:

plugin.tx_cookieman.settings.theme = myTheme

3. Create folder EXT:your_ext/Extensions/cookieman/Resources/Private/Themes/myTheme/. Add 3 folders: Templates, Partials, Layouts.
4. These folders will have the highest priority when looking for templates, partials or layouts now. The fallback will be EXT:cookieman/Resources/Private/*.
5. Create folder EXT:your_ext/Extensions/cookieman/Resources/Public/Themes/myTheme. This will hold the files cookieman-theme(.min).css and cookieman-theme(.min).js. Reimplement the methods cookieman.show() and cookieman.hide() in cookieman-theme(.min).js.
6. Copy the .css, .js and .html files as needed from a default theme.
7. Adapt the HTML/CSS/JS as needed.

Storing user consent

These HTML element attributes control the functionality:

Global functionality with data-attributes

TrackingObjects

plugin.tx_cookieman.settings.trackingObjects {
    Matomo {
        inject (
            <script type="text/javascript">
              var _paq = window._paq || [];
              _paq.push(['trackPageView']);
              _paq.push(['enableLinkTracking']);
              (function() {
                var u="//{$PIWIK_URL}/";
                _paq.push(['setTrackerUrl', u+'matomo.php']);
                _paq.push(['setSiteId', {$IDSITE}]);
                var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
                g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
              })();
            </script>
        )
    }
}

# 1. Include provided definitions of TrackingObjects:
@import 'EXT:cookieman/Configuration/TypoScript/TrackingObjects/*.typoscript'

# 2. Add the TrackingObject key to a group:
plugin.tx_cookieman.settings.groups {
    mandatory {
        trackingObjects {
            10 = fe_typo_user
        }
    }
}

# 1. Include provided definitions of TrackingObjects:
@import 'EXT:cookieman/Configuration/TypoScript/TrackingObjects/*.typoscript'

# 2. Add the TrackingObject key to a group (see below how to configure a new group):
plugin.tx_cookieman.settings.groups {
    analytics {
        trackingObjects {
            10 = GoogleAnalytics
        }
    }
}

# 3. Add the tracking code to the TrackingObject:
plugin.tx_cookieman.settings.trackingObjects {
    GoogleAnalytics {
        inject (
        <script>
            (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
            (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
            })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

            ga('create', 'UA-XXXXX-Y', 'auto');
            ga('send', 'pageview');
        </script>
        )
    }
}

plugin.tx_cookieman.settings.trackingObjects.Matomo.show._pk_hsr >

plugin.tx_cookieman {
    settings {
        # 1. Configure the new TrackingObject:
        trackingObjects {
            PHPsession {
                # 1a. Configure the table row information:
                show {
                    PHPSESSID {
                        duration =
                        durationUnit = session
                        type = cookie_http+html
                        provider = Website
                        # 1b. Set a Regular Expression pattern that matches the name of the cookie,
                        #     if the cookie name or parts of it are dynamic, so the cookie can be automatically
                        #     removed in case the user revokes the consent. (optional)
                        #     Please note that you must not provide regex delimiters and can not set options
                        # htmlCookieRemovalPattern = ^regex\.\d+\.[a-fA-F0-9]+$
                    }
                }

                # 1c. Add the tracking code (optional):
                #inject (
                #    <!-- optional HTML tracking code -->
                #)
            }
        }

        # 2. Add the new TrackingObject to a group:
        groups.mandatory.trackingObjects {
            20 = PHPsession
        }
    }

    # 3. Provide necessary localization labels:
    _LOCAL_LANG {
        default {
            trackingobject.PHPSESSID.desc = This temporary cookie is set by PHP to store current session data (e.g. form data).
        }

        de {
            trackingobject.PHPSESSID.desc = Dieser temporäre Cookie wird von PHP gesetzt, um aktuelle Sitzungsdaten zu speichern (z.B. Formulardaten).
        }
    }
}

Groups

plugin.tx_cookieman {
    settings {
        groups {
            # 1. Add the new group:
            statistics {
                # 2. Add TrackingObjects to this group:
                trackingObjects {
                    10 = Matomo
                    20 = GoogleAnalytics
                }

                # 3. Optional settings: respect the 'Do Not Track' browser setting:
                respectDnt = 1
                showDntMessage = 1
            }
        }
    }

    # 4. Provide necessary localization labels:
    _LOCAL_LANG {
        default {
            group.statistics = Statistics
            group.statistics.desc = Explain the general purpose of the cookies here.
        }

        de {
            group.statistics = Statistiken
            group.statistics.desc = Beschreibe hier den allgemeinen Einsatzzweck der Cookies.
        }
    }
}

Other topics

plugin.tx_cookieman.settings.trackingObjects {
    Matomo {
        inject = TEXT
        inject {
            insertData = 1
            value (
                <script src="/{path : EXT:your_sitepackage/Resources/Public/JavaScript/matomo-trackingcode.js}?{date : U}"></script>
                <script src="https://your-matomo-server.com/path/to/matomo.js" async defer></script>
            )
        }
    }
}

plugin.tx_cookieman {
    settings {
        cookie {
            # cookie expire time in days (default: 365)
            cookieLifetimeDays =

            # domain without protocol like www.example.com, .example.com (default: Typo3 site name)
            domain =

            # sameSite Options: Lax, Strict or None (default: lax)
            sameSite = Lax
        }
    }
}

plugin.tx_cookieman.settings.cookie.domain = .example.com

Override translations

You can override translations by registering your .xlf-file as override in your ext_localconf.php (this example uses a configure_cookieman extension that we recommend to hold all your cookieman configuration):

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']['EXT:cookieman/Resources/Private/Language/locallang.xlf'][]
    = 'EXT:configure_cookieman/Resources/Private/Language/locallang_cookieman.xlf';

Add translations for new groups and tracking objects

If you have added groups or tracking objects, you will have to add these translation strings:

group.‹group-key›

Shown as group title.

group.‹group-key›.desc

Shown as introductory text block above the table (optional).

trackingobject.‹tracking-object-key›.desc

Shown in the table column "Purpose".

type.‹your-custom-type-key›

Shown in the table column "Type".

Documentation

You are welcome to help improve this guide. Just click on "Edit me on GitHub" on the top right to submit your improvement via a Pull Request.

Translations

Translations are managed on the official TYPO3 translation platform. See Translation.

Feedback

Any problems? You miss a feature? There is an incompatibility? You have strategic input?

Please open an issue at our Github repository after you have read the documentation.

Code (Templates, JavaScript, PHP)

We are happy to receive pull requests.

cookieman.showOnce()

cookieman.showOnce()

| Data type: void |

Shows the confirmation modal when consent has not been saved yet.

It is automatically called on each page from cookieman-init.js (with an aditional condition, see When is the popup shown to users?)

cookieman.show()

cookieman.show()

| Data type: void |

Shows the confirmation modal.

You can also use the attribute data-cookieman-show on any element to show the modal when clicked.

<button data-cookieman-show>
  Adjust your cookie preferences
</button>

Copied!

cookieman.hide()

cookieman.hide()

| Data type: void |

Hides the confirmation modal.

cookieman.consent(groupKey)

cookieman.consent(groupKey)

| Adds the given group (e.g. 'marketing') to the consented groups, updates the CookieConsent cookie and injects all items given each corresponding trackingObject's inject section.

This is meant as a programmatic way to implement banners before showing content from external sources such as YouTube videos, Google Maps, facebook posts, ... – clicking the "yes, show the content"-button would call this function and a <script> in trackingObject's inject section would take care of actually loading the content.

cookieman.consenteds()

cookieman.consenteds()

| Data type: array | Example: ["mandatory", "ads"] |

Returns all group keys the user has consented to.

cookieman.hasConsented(groupKey)

cookieman.hasConsented(groupKey)

| Data type: boolean |

Returns true if the user has consented to the given group (e.g. 'marketing'), else false.

cookieman.hasConsentedTrackingObject(trackingObjectKey)

cookieman.hasConsentedTrackingObject(trackingObjectKey)

| Data type: boolean |

Returns true if the user has consented to all groups that contain the given trackingObject, else false.

trackingObjectKey is the trackingObjects.‹tracking object key› from TypoScript, e.g. 'Matomo'.

cookieman.onScriptLoaded(String trackingObjectKey, int scriptId, function callback)

cookieman.onScriptLoaded(String trackingObjectKey, int scriptId, function callback)

| Data type: void |

This is a hook to do things after an external script has been loaded. This is useful if you are interacting with external scripts that are loaded by Cookieman.

• trackingObjectKey is the trackingObjects.‹tracking object key› from TypoScript, e.g. 'Matomo'.
• scriptId is the number of the <script> inside your trackingObjects.‹tracking object key›.inject (starting from 0 with the first).
• callback is a function reference. It receives trackingObjectKey and scriptId (see example below). The callback is called immediately if the referred to <script> has already finished loading.

Example:

cookieman.onScriptLoaded(
    'Matomo',
    0, // first script in 'inject'
    function (trackingObjectKey, scriptId) {
        _paq.push(['trackConversion'])
    }
)

Copied!

Contact

For bugs and feature requests use the Github bug tracker.

Pull requests are very welcome.

Made with love @