Matomo Analytics: Technical Details

Technical structure of Matomo Analytics for Shopware 6.7: script output flow, classes and subscribers, configuration keys, template extension, migration and tests.

Deutsche Version

Back to overview

Matomo Analytics: Technical Details

Package

Property	Value
Composer package	`mmd/sw67-matomo-analytics`
Plugin class	`Mmd\MatomoAnalytics\MmdMatomoAnalytics`
Namespace	`Mmd\MatomoAnalytics`
Requirements	PHP >=8.2, `shopware/core` ~6.7.0
Configuration keys	`MmdMatomoAnalytics.config.<name>`

Plugin lifecycle

The plugin class MmdMatomoAnalytics only overrides activate() and uninstall().

activate() calls Service\KlaroServiceInstaller::installIfNeeded(). This covers the case where the Klaro plugin was installed after Matomo, since the migration Migration1738800001CreateMatomoKlaroService could not create the service at install time in that case.
uninstall(), unless user data is kept, deletes the Klaro service matomo including its translations from mmd_klaro_cookie_service and mmd_klaro_cookie_service_translation (if the table exists), and deletes all system_config rows with the key MmdMatomoAnalytics.config.%.

graph TD
    A["Migration on install"] --> C{"Klaro table exists and no service matomo yet?"}
    B["Plugin activation"] --> C
    C -->|"Yes"| D["Create service, translations and assignment to storefront sales channels"]
    C -->|"No"| E["No change"]

Script output flow

graph TD
    A["StorefrontRenderEvent"] --> B["MatomoConfigFactory reads sales channel settings"]
    B --> C{"Tracking on, URL and Site ID valid?"}
    C -->|"No"| X["No script"]
    C -->|"Yes"| D{"Klaro active?"}
    D -->|"Yes"| F["Script with type text/plain and data-name"]
    D -->|"No"| E{"ConsentChecker allows tracking?"}
    E -->|"No"| X
    E -->|"Yes"| G["Script in block base_body_script"]

Components

Class	Responsibility
`Configuration\MatomoConfigFactory`	Reads the settings per sales channel via the `SystemConfigService`
`Configuration\MatomoConfig`	Value object. `isValid()` requires tracking on, a valid `https://` URL without `<`, `>`, `"`, `'`, `\` and a Site ID greater than 0
`Service\TrackingCodeRenderer`	Generates the tracking JavaScript
`Service\ConsentChecker`	Server-side check of DNT header and consent cookies (only without Klaro)
`Service\EcommerceTracker`	Generates the JavaScript lines for product view, cart and order
`Service\KlaroServiceInstaller`	Creates the Klaro service `matomo` if the table `mmd_klaro_cookie_service` exists and no service with that technical name exists yet: purpose `analytics`, disabled by default, cookie patterns `/^_pk_id/`, `/^_pk_ses/`, `/^_pk_ref/` with path `/`, DE/EN translations (title "Matomo Analytics") for existing languages, and assignment to all storefront sales channels; called from `activate()`, see Installation
`Subscriber\StorefrontRenderSubscriber`	Listens to `StorefrontRenderEvent` (priority -100), sets `matomoTrackingCode` and `matomoConfig`
`Subscriber\ProductPageSubscriber`	Listens to `ProductPageLoadedEvent`
`Subscriber\CheckoutSubscriber`	Listens to `CheckoutCartPageLoadedEvent` and `CheckoutConfirmPageLoadedEvent`
`Subscriber\OrderCompletedSubscriber`	Listens to `CheckoutFinishPageLoadedEvent`, reloads the order with line items and shipping costs if needed
`Struct\MatomoEcommerceStruct`	Carries type and code as page extension `matomoEcommerce`
`Twig\MatomoExtension`	Registers the Twig functions, see Extending
`Storefront\Controller\MatomoOptOutController`	Route `/matomo/opt-out` (`frontend.matomo.optout`, GET)
`Migration\Migration1738800001CreateMatomoKlaroService`	Creates the Klaro service, see Installation

Templates

File	Purpose
`storefront/base.html.twig`	Extends `@Storefront/storefront/base.html.twig`, outputs tracking and E-Commerce script in the block `base_body_script`. With Klaro additionally a script that passes consent on to Matomo
`storefront/page/matomo-opt-out.html.twig`	Opt-out page
`storefront/component/matomo-opt-out.html.twig`	Includable opt-out component

Snippets

The opt-out texts live under the key mmd-matomo.optOut.* in the files for de-DE and en-GB.

Behavior notes

The Matomo tracker receives the tracker URL <Matomo URL>/matomo.php and loads <Matomo URL>/matomo.js.
The script queues trackPageView in the _paq queue before matomo.js is loaded.
EcommerceTracker::trackAddToCart() exists but is not called by any subscriber.

Tests

The repository contains PHPUnit tests under tests/Unit for configuration, services, subscribers, controller and the Twig extension.