Matomo Analytics: Technical Details

Technical details of Matomo Analytics for OXID eShop 7: architecture, classes, generated tracking code, e-commerce calls, session variables and metadata.php.

Deutsche Version

Back to overview

Matomo Analytics: Technical Details

Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net

Architecture

graph TD
    A["Template oViewConf"] --> B["ViewConfigExtension"]
    B --> C["MatomoConfigFactory"]
    C --> D["MatomoConfig"]
    B --> E["ConsentChecker"]
    B --> F["TrackingCodeRenderer"]
    B --> G["EcommerceTracker"]
    H["OrderSubscriber"] --> M["MatomoEcommerceData"]
    H --> I["Session matomoOrderTracking"]
    J["ThankYouControllerExtension"] --> I
    J --> G

Flow: ViewConfigExtension reads the settings through MatomoConfigFactory as an immutable MatomoConfig, asks the ConsentChecker, and renders the JavaScript via TrackingCodeRenderer and EcommerceTracker. When an order is saved, the OrderSubscriber builds a MatomoEcommerceData object and stores it in the session. On the confirmation page, the ThankYouControllerExtension reads it from the session and generates the JavaScript with the EcommerceTracker.

Module structure (excerpt)

├── metadata.php
├── services.yaml
├── composer.json
├── src/
│   ├── Config/
│   │   ├── MatomoConfig.php
│   │   └── MatomoConfigFactory.php
│   ├── Controller/
│   │   └── MatomoOptOutController.php
│   ├── DataTransfer/
│   │   └── MatomoEcommerceData.php
│   ├── EventSubscriber/
│   │   └── OrderSubscriber.php
│   ├── Extension/
│   │   ├── Application/Controller/ThankYouControllerExtension.php
│   │   └── Core/ViewConfigExtension.php
│   └── Service/
│       ├── ConsentChecker.php
│       ├── EcommerceTracker.php
│       └── TrackingCodeRenderer.php
└── views/
    ├── admin_twig/{de,en}/mmd_matomo_analytics_lang.php
    └── twig/
        ├── {de,en}/mmd_matomo_analytics_lang.php
        ├── page/matomo_optout.html.twig
        ├── widget/matomo_optout.html.twig
        └── extensions/themes/apex/
            ├── layout/base.html.twig
            └── page/checkout/thankyou.html.twig

metadata.php

Entry	Value
Module ID	`mmd_matomo_analytics`
Extended classes	`ViewConfig` (`ViewConfigExtension`), `ThankYouController` (`ThankYouControllerExtension`)
Controller	`matomo_optout` (`MatomoOptOutController`)
Templates	`@mmd_matomo_analytics/page/matomo_optout.html.twig`, `@mmd_matomo_analytics/widget/matomo_optout.html.twig`
Setting groups	`mmd_matomo_basic`, `mmd_matomo_privacy`, `mmd_matomo_ecommerce`, `mmd_matomo_advanced`
PHP namespace	`Mmd\MatomoAnalytics\`

Classes

Class	Responsibility
`MatomoConfigFactory`	Reads the settings of the current shop and creates `MatomoConfig`
`MatomoConfig`	Immutable value object, checks `isValid()` and the HTTPS URL
`ConsentChecker`	Server-side check of the DNT header and consent cookies
`TrackingCodeRenderer`	Generates the tracking code
`EcommerceTracker`	Generates the e-commerce calls for product view, cart and order
`MatomoEcommerceData`	Data object for product view, cart update and order
`OrderSubscriber`	Reacts to `AfterModelUpdateEvent`; only processes `Order` models with an order number (`oxordernr`) and stores the order data in the session
`ViewConfigExtension`	Extends `ViewConfig` with the template methods (see Storefront and Templates)
`ThankYouControllerExtension`	Extends the `ThankYouController` with `getMatomoOrderTracking()`
`MatomoOptOutController`	Opt-out page, controller ID `matomo_optout`

Generated tracking code

With the defaults (tracking on, Matomo URL and site ID set), this code is generated. The order is fixed: privacy calls, heartbeat, trackPageView, link tracking, tracker initialization.

var _paq = window._paq = window._paq || [];
_paq.push(["disableCookies"]);
_paq.push(["setDoNotTrack", true]);
_paq.push(["trackPageView"]);
_paq.push(["enableLinkTracking"]);
(function() {
var u="https://analytics.example.com/";
_paq.push(["setTrackerUrl", u+"matomo.php"]);
_paq.push(["setSiteId", 1]);
var d=document, g=d.createElement("script"), s=d.getElementsByTagName("script")[0];
g.async=true; g.src=u+"matomo.js"; s.parentNode.insertBefore(g,s);
})();

Depending on the settings, requireConsent (after the other privacy calls) and enableHeartBeatTimer (before trackPageView) are added.

E-Commerce calls

Type	Calls
Product view	`setEcommerceView(sku, name, category, price)`
Cart	`addEcommerceItem(sku, name, "", price, quantity)` per line, then `trackEcommerceCartUpdate(total)`
Order	`addEcommerceItem(...)` per line, then `trackEcommerceOrder(orderId, revenue, subTotal, tax, shipping)`

Prices are output with two decimal places and a dot as decimal separator. The category path of the product view is built from the category titles joined with >. The lines of cart and order pass an empty string as category.

Session variables

Variable	Content
`matomoOrderTracking`	Order data until it is output on the confirmation page, deleted afterwards
`matomoTrackedOrders`	List of already registered order numbers, prevents double registration within a session

Settings in code

The settings are read per shop. The site ID and the heartbeat interval are stored as text and converted to numbers. An empty Klaro service name becomes matomo, a heartbeat interval of 0 becomes 15.