How-To

Target group: Developers, Integrators

TrackingObjects

What are TrackingObjects?

A TrackingObject is an array which includes one or more tracking items (usually cookies). For example, the TrackingObject GoogleAnalytics contains five cookies which are used by this service. They are listed inside the show array.

Depending on the purpose a TrackingObject has, you need to inject HTML code after the user has given his consent (see next section).

How to load tracking code only after user consent?

A web analytics service like Matomo or Google Analytics needs the user's active consent before the website starts with tracking. Therefore, you'll need to ensure that the tracking code is not executed automatically at page load.

You need to remove all existing tracking codes from your website and let Cookieman manage them. Cookieman will inject the tracking codes after user consent with the inject configuration.

Example:

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>
        )
    }
}

Adding a preconfigured TrackingObject

Cookieman already provides some preconfigured TrackingObjects.

You can add selected TrackingObjects with two (or three) steps in TypoScript:

Import the provided definitions.
Add the key (name) of the TrackingObject.

# 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
        }
    }
}

If a TrackingObject needs to inject HTML code, you'll have to add this in a third step:

# 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>
        )
    }
}

Attention

If your website sets the HTTP header Content-Security-Policy, you'll need to use <script> with external sources (see below).

Only add the used tracking items (cookies)

The provided TrackingObject definitions contain commonly used cookies of a service. You'll need to check it your website really uses all these cookies!

For example, Matomo will only use the _pk_hsr cookie if the Heatmap & Session recording plugin is enabled!

You can remove any default tracking item like this:

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

Important

It's important that you only list cookies in the consent popup which your website really sets.

Adding a new custom TrackingObject

A new TrackingObject of course needs some additional configuration:

Configure the new TrackingObject.
Add the new TrackingObject to a group.
Provide necessary localization labels which are shown in the consent popup.

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).
        }
    }
}

Important

If you provide a Regular Expression in the htmlCookieRemovalPattern option, please be aware of Catastrophic Backtracking and make sure that your pattern is safe. Otherwise your page might slow down or even crash the users browser.

Groups

What are Groups?

TrackingObjects can be arranged in groups that fit their purpose (technically necessary, statistics, marketing, …).

You can configure that a group is mandatory (and therefore preselected and disabled) or that the "Do-not-track" setting of your browser is respected.

Adding a new custom group

A new group needs the following configuration:

Add the new group.
Add the desired TrackingObjects to the group.
Add settings to the group (optional).
Provide necessary localization labels.

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.
        }
    }
}

Tip

Whether Google Analytics can be considered a statistics or marketing TrackingObject depends on its individual configuration.

In case of doubt, ask your Data Security Officer.

Other topics

Content Security Policy

If your website sets the HTTP header Content-Security-Policy (without the unrecommended option 'unsafe-inline'), it will block all inline code – including your tracking codes.

In order to use tracking within such an environment, you have to move your tracking codes to external files and load them from there.

Important

Some tracking codes have to be adjusted to work from within external files, e.g. Matomo.

Cookieman allows to add external sources with the inject configuration:

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>
            )
        }
    }
}

Tip

Read more about the Content Security Policy on the Mozilla Developer Network.

Configuration of the cookie used by the extension itself

There are a few typoscript options to configure the cookie which is required by the exension.

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

Tip

If you have multiple TYPO3 sites running on one instance with multiple subdomains you propably do not want to have multiple cookieman cookies. This would also mean that the cookieman banner is displayed on both domains and that every website user has to configure it for every subdomain again. To avoid this just set the domain setting to the domain with a starting dot.

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