Matomo Analytics: Erweiterbarkeit

Matomo Analytics in eigene Templates einbinden: Twig-Funktionen für Tracking-Code, Status-Abfragen und Opt-Out-iFrame, Template-Block und Seiten-Erweiterung für E-Commerce-Code.

English Version

Zurück zur Übersicht

Matomo Analytics: Erweiterbarkeit

Twig-Funktionen

Das Plugin registriert fünf Twig-Funktionen. Alle akzeptieren die ID eines Verkaufskanals und berücksichtigen dessen Einstellungen. Ohne ID gelten die kanalunabhängigen Einstellungen.

Funktion	Rückgabe
`matomo_is_enabled(salesChannelId)`	`true`, wenn Tracking an ist und Matomo URL (HTTPS) und Site ID gültig sind
`matomo_ecommerce_enabled(salesChannelId)`	`true`, wenn zusätzlich E-Commerce Tracking aktivieren an ist
`matomo_tracking_code(salesChannelId)`	Das Tracking-JavaScript ohne `<script>`-Tags, bei ungültiger Konfiguration leer. Nicht als sicheres HTML markiert, bei direkter Ausgabe ist `\\|raw` nötig
`matomo_tracking_script(salesChannelId)`	Dasselbe Script, in `<script>`-Tags eingefasst und bereits als sicheres HTML markiert
`matomo_opt_out_iframe(salesChannelId, language, backgroundColor, fontColor)`	Der Opt-Out-iFrame von Matomo, bei ungültiger Konfiguration leer. Standardwerte: `de`, `ffffff`, `000000`

matomo_tracking_code ist nicht mehr als sicheres HTML markiert, Twig maskiert die Ausgabe daher automatisch. Im <script>-Element brauchst du deshalb |raw, sonst zerstören HTML-Entities die Syntax. matomo_tracking_script liefert das fertige Element als sicheres HTML und kommt ohne |raw aus.

{% if matomo_is_enabled(context.salesChannel.id) %}
    {# Matomo ist aktiv #}
{% endif %}

{% if matomo_ecommerce_enabled(context.salesChannel.id) %}
    {# E-Commerce-Tracking ist aktiv #}
{% endif %}

{{ matomo_opt_out_iframe(
    context.salesChannel.id,
    app.request.locale,
    'ffffff',
    '000000'
)|raw }}

{# matomo_tracking_code ist nicht als sicheres HTML markiert, daher |raw beim direkten Einbinden #}
<script>
    {{ matomo_tracking_code(context.salesChannel.id)|raw }}
</script>

{# matomo_tracking_script liefert das fertige <script>-Element bereits sicher, kein |raw nötig #}
{{ matomo_tracking_script(context.salesChannel.id) }}

Das Plugin gibt das Tracking-Script bereits automatisch aus. Mit matomo_tracking_code und matomo_tracking_script rendert die Funktion das Script zusätzlich, ohne die Prüfungen auf Do-Not-Track und Einwilligung, die das Plugin vor der automatischen Ausgabe durchführt. Nutze sie nur, wenn du genau weißt, wo das Script erscheinen soll.

Der iFrame zeigt die Opt-Out-Seite der Matomo-Instanz mit der Schriftgröße 16px und übernimmt die Schriftart der Umgebung.

Fertige Opt-Out-Komponente

Für den Opt-Out gibt es eine fertige Twig-Komponente @MmdMatomoAnalytics/storefront/component/matomo-opt-out.html.twig, siehe Storefront.

Eigene Templates

Das Plugin erweitert den Block base_body_script der Storefront-Vorlage base.html.twig. Überschreibst du diesen Block in deinem Theme, ohne parent() aufzurufen, entfällt die automatische Ausgabe.
Dem Seitenobjekt hängt das Plugin die Erweiterung matomoEcommerce an. Sie hat die Methoden getType() (productView, cartUpdate oder orderCompleted) und getTrackingCode().
Der Seiten-Render bekommt die Variablen matomoTrackingCode und matomoConfig (Schlüssel enabled, ecommerceEnabled, matomoUrl, siteId, useKlaroConsent, klaroServiceName).

Events und Service-Tags

Das Plugin definiert keine eigenen Events und keine eigenen Service-Tags.