Matomo Analytics: Technische Details

Technischer Aufbau von Matomo Analytics für Shopware 6.7: Ablauf der Script-Ausgabe, Klassen und Subscriber, Konfigurationsschlüssel, Template-Erweiterung, Migration und Tests.

English Version

Zurück zur Übersicht

Matomo Analytics: Technische Details

Paket

Eigenschaft	Wert
Composer-Paket	`mmd/sw67-matomo-analytics`
Plugin-Klasse	`Mmd\MatomoAnalytics\MmdMatomoAnalytics`
Namespace	`Mmd\MatomoAnalytics`
Anforderungen	PHP >=8.2, `shopware/core` ~6.7.0
Konfigurationsschlüssel	`MmdMatomoAnalytics.config.<name>`

Plugin-Lifecycle

Die Plugin-Klasse MmdMatomoAnalytics überschreibt nur activate() und uninstall().

activate() ruft Service\KlaroServiceInstaller::installIfNeeded() auf. Das deckt den Fall ab, dass das Klaro-Plugin erst nach Matomo installiert wurde, denn dann konnte die Migration Migration1738800001CreateMatomoKlaroService den Service beim Installieren noch nicht anlegen.
uninstall() löscht, sofern keine Nutzerdaten erhalten bleiben sollen, den Klaro-Service matomo inklusive Übersetzungen aus mmd_klaro_cookie_service und mmd_klaro_cookie_service_translation (falls die Tabelle existiert) sowie alle system_config-Einträge mit dem Schlüssel MmdMatomoAnalytics.config.%.

graph TD
    A["Migration beim Installieren"] --> C{"Klaro-Tabelle vorhanden und kein Service matomo?"}
    B["Plugin aktivieren"] --> C
    C -->|"Ja"| D["Service, Übersetzungen und Zuordnung zu Storefront-Verkaufskanälen anlegen"]
    C -->|"Nein"| E["Keine Änderung"]

Ablauf der Script-Ausgabe

graph TD
    A["StorefrontRenderEvent"] --> B["MatomoConfigFactory liest Einstellungen des Verkaufskanals"]
    B --> C{"Tracking aktiv, URL und Site ID gültig?"}
    C -->|"Nein"| X["Kein Script"]
    C -->|"Ja"| D{"Klaro aktiv?"}
    D -->|"Ja"| F["Script mit type text/plain und data-name"]
    D -->|"Nein"| E{"ConsentChecker erlaubt Tracking?"}
    E -->|"Nein"| X
    E -->|"Ja"| G["Script im Block base_body_script"]

Komponenten

Klasse	Aufgabe
`Configuration\MatomoConfigFactory`	Liest die Einstellungen pro Verkaufskanal über den `SystemConfigService`
`Configuration\MatomoConfig`	Wertobjekt. `isValid()` verlangt aktives Tracking, eine gültige `https://`-URL ohne `<`, `>`, `"`, `'`, `\` und eine Site ID größer als 0
`Service\TrackingCodeRenderer`	Erzeugt das Tracking-JavaScript
`Service\ConsentChecker`	Serverseitige Prüfung von DNT-Header und Einwilligungs-Cookies (nur ohne Klaro)
`Service\EcommerceTracker`	Erzeugt die JavaScript-Zeilen für Produktansicht, Warenkorb und Bestellung
`Service\KlaroServiceInstaller`	Legt den Klaro-Service `matomo` an, falls die Tabelle `mmd_klaro_cookie_service` existiert und noch kein Service mit diesem technischen Namen vorhanden ist: Zweck `analytics`, standardmäßig deaktiviert, Cookie-Muster `/^_pk_id/`, `/^_pk_ses/`, `/^_pk_ref/` mit Pfad `/`, DE-/EN-Übersetzungen (Titel „Matomo Analytics“) für vorhandene Sprachen und Zuordnung zu allen Storefront-Verkaufskanälen; aufgerufen aus `activate()`, siehe Installation
`Subscriber\StorefrontRenderSubscriber`	Reagiert auf `StorefrontRenderEvent` (Priorität -100), setzt `matomoTrackingCode` und `matomoConfig`
`Subscriber\ProductPageSubscriber`	Reagiert auf `ProductPageLoadedEvent`
`Subscriber\CheckoutSubscriber`	Reagiert auf `CheckoutCartPageLoadedEvent` und `CheckoutConfirmPageLoadedEvent`
`Subscriber\OrderCompletedSubscriber`	Reagiert auf `CheckoutFinishPageLoadedEvent`, lädt die Bestellung bei Bedarf mit Positionen und Versandkosten nach
`Struct\MatomoEcommerceStruct`	Trägt Typ und Code als Seiten-Erweiterung `matomoEcommerce`
`Twig\MatomoExtension`	Registriert die Twig-Funktionen, siehe Erweiterbarkeit
`Storefront\Controller\MatomoOptOutController`	Route `/matomo/opt-out` (`frontend.matomo.optout`, GET)
`Migration\Migration1738800001CreateMatomoKlaroService`	Legt den Klaro-Service an, siehe Installation

Templates

Datei	Zweck
`storefront/base.html.twig`	Erweitert `@Storefront/storefront/base.html.twig`, gibt im Block `base_body_script` Tracking- und E-Commerce-Script aus. Mit Klaro zusätzlich ein Script für die Weitergabe der Einwilligung an Matomo
`storefront/page/matomo-opt-out.html.twig`	Opt-Out-Seite
`storefront/component/matomo-opt-out.html.twig`	Einbindbare Opt-Out-Komponente

Snippets

Die Opt-Out-Texte liegen unter dem Schlüssel mmd-matomo.optOut.* in den Dateien für de-DE und en-GB.

Hinweise zum Verhalten

Der Matomo-Tracker erhält die Tracker-URL <Matomo URL>/matomo.php und lädt <Matomo URL>/matomo.js.
Das Script gibt trackPageView vor dem Laden von matomo.js in die Warteschlange _paq.
EcommerceTracker::trackAddToCart() existiert, wird aber von keinem Subscriber aufgerufen.

Tests

Das Repository enthält PHPUnit-Tests unter tests/Unit für Konfiguration, Services, Subscriber, Controller und die Twig-Erweiterung.