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

Adding a preconfigured TrackingObject 

Cookieman already provides some preconfigured TrackingObjects.

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

  1. Import the provided definitions.
  2. 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
        }
    }
}
Copied!
  1. 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 {
            insertData = 1
            value = (
              <script nonce="{request : nonce | value}">
                  (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>
            )
        }
    }
}
Copied!

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 >
Copied!

Adding a new custom TrackingObject 

A new TrackingObject of course needs some additional configuration:

  1. Configure the new TrackingObject.
  2. Add the new TrackingObject to a group.
  3. 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).
        }
    }
}
Copied!

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:

  1. Add the new group.
  2. Add the desired TrackingObjects to the group.
  3. Add settings to the group (optional).
  4. 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.
        }
    }
}
Copied!

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.

Cookieman allows to add external sources with the inject configuration:

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