.. include:: ../../Includes.txt


.. _configuration-howto:

======
How-To
======

Target group: **Developers, Integrators**


.. _howto-trackingobjects:

TrackingObjects
===============


.. _what-are-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 :ref:`next section <load-tracking-code-after-consent>`).


.. _load-tracking-code-after-consent:

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
:ref:`inject <trackingObjects.‹tracking-object-key›.inject>` configuration.

**Example:**

.. code-block:: typoscript

   plugin.tx_cookieman.settings.trackingObjects {
       Matomo {
           inject = TEXT
           inject {
               insertData = 1
               value = (
                  <script nonce="{request : nonce | value}">
                    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>
              )
           }
       }
   }


.. _add-preconfigured-trackingobject:

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.

.. code-block:: typoscript

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

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

.. code-block:: typoscript

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

.. attention::

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


.. _only-add-used-tracking-items:

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:

.. code-block:: typoscript

   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.


.. _add-new-trackingobject:

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.

.. code-block:: typoscript

   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 <https://www.rexegg.com/regex-explosive-quantifiers.html>`__ and make sure that your pattern is safe. Otherwise your page might slow down or even crash the users browser.

.. _howto-groups:

Groups
======


.. _what-are-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 :ref:`preselected <groups.‹group-key›.preselected>`
and :ref:`disabled <groups.‹group-key›.disabled>`) or that the `"Do-not-track" setting of your browser <https://en.wikipedia.org/wiki/Do_Not_Track>`__
is :ref:`respected <groups.‹group-key›.respectDnt>`.


.. _add-new-group:

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.

.. code-block:: typoscript

   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:

Other topics
============


.. _content-security-policy:

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 <https://matomo.org/faq/general/faq_20904/>`__.

Cookieman allows to add external sources with the :ref:`inject <trackingObjects.‹tracking-object-key›.inject>` configuration:

.. code-block:: typoscript

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

.. tip::

   Read more about the Content Security Policy on the `Mozilla Developer Network <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>`__.



.. _extension-cookie-settings:

Configuration of the cookie used by the extension itself
--------------------------------------------------------

There are a few TypoScript constants to configure the cookie which is required by the exension
(see :ref:`typoscript-constants`).

.. code-block:: typoscript

    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: Strict)
                sameSite =

                # send the cookie via https only (default: on). Cookieman sets it only on https pages.
                secure =
            }
        }
    }

.. note::

   Before cookieman 5.0.0 the default for ``sameSite`` was ``Lax``. Set
   ``sameSite = Lax`` to keep that behaviour.
   The `SameSite attribute on the Mozilla Developer Network <https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value>`__
   explains what the values do.

.. note::

   ``secure`` is on. It is safe to leave it on, also for an http website: cookieman
   sets the attribute only when the page is served via https.
   The `Secure attribute on the Mozilla Developer Network <https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#secure>`__
   explains what it does.

   Set ``secure = 0`` only if you have http/https subdomains that must be covered by the cookie
   (see the tip on ``domain`` below). This is the only reason to switch it off.

   Browsers also discard a cookie with ``sameSite = None`` if it is not ``secure``.

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

.. code-block:: typoscript

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


.. _show-the-popup-again:

Show the consent popup again after a configuration change
---------------------------------------------------------

A user who gave consent does not see the popup again. If you add a tracking object or
change your groups, that user keeps the old consent and does not see the new
configuration.

Change :ref:`consentConfigurationVersion` every time you change your cookie
configuration. The default is ``1``, so your first change sets it to ``2``:

.. code-block:: typoscript

   plugin.tx_cookieman.settings.consentConfigurationVersion = 2

Cookieman writes the version into the consent cookie. If the version in the cookie of a
user is not the same as the configured one, cookieman shows the popup again. The
selections of the user stay in the checkboxes, so they only must confirm them.

You can use any value, for example a date or the number of your release.

.. important::

   Until the user saves again, the old consent does not count: cookieman injects no
   tracking objects. This makes sure that a new tracking object does not start before
   the user consented to it.

.. note::

   Consent that cookieman before 5.0.0 saved holds no version. Cookieman adds the
   current version to such a cookie without a change for the user ("silent upgrade").
   Nobody is asked again because of the upgrade to 5.0.0. Only your next change of the
   version shows the popup again.