README

Analytics Lite (multi-backend, GDPR-first)

Multi-backend analytics for Shopware 6. Ships a TrackerInterface abstraction plus two production-ready adapters (Matomo + Plausible); plug in any other backend by implementing the interface. Cookieless by default. GDPR-first defaults.

License: MIT · Shopware: 6.7.x · PHP: 8.1 / 8.2

🇬🇧 English · 🇳🇱 Nederlands · 🇩🇪 Deutsch

📖 More context: Why we built this · How it compares

Lite tier

This is the free Lite tier in the new Lite / Pro split for the TenBruggencate Suite. Lite ships the full multi-backend tracker abstraction (Matomo + Plausible adapters), cookieless mode, GPC respect, sales-channel-scoped configuration, and the basic multi-brand custom-dimension wiring — everything you need to run a privacy-first analytics setup in production.

A Pro tier is coming under tenbruggencate/analytics-pro (distributed via the Shopware Store, not public Packagist) with: e-commerce conversion tracking (cart + order events), advanced multi-brand custom-dimension orchestration, native consent-mode integration, ready-made Looker Studio / Grafana dashboard templates, and a server-side fallback path for ad-blocked visitors. Pro will be installable side-by-side with Lite — no migration needed at upgrade time.

Screenshots

The plugin emits invisible tracker scripts on the storefront — there's nothing for visitors to see. The visible surface is the admin config card, captured here after the v1.4.0 polish (sharper labels, focus rings on every control, cookielessMode helpText fix).

Admin config panel — Getting started intro card explaining the three-step setup, then the Sales Channel selector for per-SC configuration.

_{Getting started + per-SC scope}

Admin config panel — Matomo URL, Matomo site ID, Enable Matomo tracking toggle, Cookieless mode (GDPR-safe, no banner needed), IP anonymisation, Respect Do Not Track. v1.4.0 polish: disambiguated labels and focus-rings on every control.

_{Matomo backend fields (v1.4.0 polished labels)}

What it does

Most analytics plugins for Shopware are single-backend ("Matomo plugin", "GA plugin", "Plausible plugin"), which forces a lock-in: switching backend means uninstalling one plugin and learning another. This plugin separates "what to track" from "where to send it":

TrackerInterface — stable contract (emitHeadScript(), emitBodyEnd(), trackEvent(...)) that any backend implements
TrackerRegistry — admin picks the active backend from a list; switching is a config change, not a reinstall
Bundled adapters — Matomo (was formerly its own plugin, folded in so shop owners install one thing) and Plausible
Cookieless by default — no cookies set unless the admin explicitly opts in
Global Privacy Control respect (v1.3+) — when a visitor's browser sends Sec-GPC: 1 and the new respectGpc config is on (default), no analytics script is rendered for that request. No Matomo loader, no Plausible script, no third-party origin call. GPC is the W3C-standard successor to Do-Not-Track, with regulatory teeth (CCPA already binds operators to honour it). Server-side detection via the request header — the cleanest possible privacy story

Install

composer require tenbruggencate/analytics-lite
bin/console plugin:refresh
bin/console plugin:install --activate TenBruggencateAnalytics
bin/console cache:clear

Configuration

Configurable per sales channel from Settings → System → Plugins → Analytics.

Field	Default	Purpose
`enabled`	`true`	Kill switch for all tracker emission
`trackerType`	`matomo`	`matomo` or `plausible` (or any custom tracker registered via services.xml)
`matomoUrl`	—	Your Matomo endpoint (when `trackerType=matomo`)
`siteId`	—	Matomo site ID
`cookielessMode`	`true`	Matomo `disableCookies` toggle
`ipAnonymization`	`true`	Drop last octet before storage
`respectDoNotTrack`	`true`	Honour the browser's DNT header
`trackAdminUsers`	`false`	Don't pollute stats with admin browsing
`brandDimensionId`	`0`	Matomo custom-dimension ID to record `brandKey` (when used with TenBruggencateMultiBrand)
`pageTypeDimensionId`	`0`	Dimension ID for page-type labels (home / plp / pdp / checkout)
`stoneSlugDimensionId`	`0`	Example of how to wire a further custom dimension — rename / repurpose as needed

Usage

The tracker renders itself into every storefront page. No template work needed.

Adding a new backend — implement TrackerInterface:

final class UmamiTracker implements TrackerInterface
{
    public function getKey(): string { return 'umami'; }
    public function emitHeadScript(SalesChannelContext $ctx): string { /* ... */ }
    public function emitBodyEnd(SalesChannelContext $ctx): string { return ''; }
    public function trackEvent(string $event, array $properties): void { /* ... */ }
}

Register it in your plugin's services.xml with the ten_bruggencate_analytics.tracker tag and it appears in the admin dropdown.

Standards

Performance — single inline script in <head>, ~1.5 KB when Matomo is configured, ~0.4 KB for Plausible. No external library fetch until the user has interacted (cookieless flow).
SEO — tracker emission does not touch meta tags, URLs, canonicals, or sitemaps.
GDPR — cookieless / DNT-respecting / IP-anonymised defaults ship true. Track-admin-users defaults to false. Includes a Migration<ts>CopyMatomoConfig that forward-migrates existing settings from the deprecated standalone Matomo plugin (see TEN-159). Full data-flow + subject-rights documentation in GDPR.md.
WCAG — tracker output is an inline script; no visual or interaction surface. Rationale + structural guarantees documented in docs/ACCESSIBILITY.md.
Security — all configured URLs are validated as HTTPS in the admin config form. No eval, no dynamic script injection, no third-party CDN fetch until the admin turns off cookieless mode.
Uninstall — plugin:uninstall --keep-user-data preserves tracker config (Matomo URL, site IDs, dimensions); plugin:uninstall without the flag also drops any legacy TenBruggencateMatomo.config.* rows from the old standalone plugin (TEN-159). No owned tables — analytics data lives on the configured backend, not in this shop.

Production-readiness checklist

A deliberately short list of things to verify before enabling the plugin on a customer-facing storefront. Not legal cover — the MIT license already disclaims warranty — but practical guidance an experienced operator would want anyway.

[ ] Don't accept the default siteId=1 blindly. Especially on a Matomo instance that already has unrelated sites — sending shop traffic to siteId 1 will pollute someone else's stats. Get the right ID from your Matomo admin first.
[ ] Set matomoUrl (or plausibleDomain / plausibleScriptUrl) before enabling. With enabled=true but the URL field empty, shouldRender() correctly returns false and no script is emitted — but the admin sees no warning either, just zero data flowing in.
[ ] Test with Sec-GPC: 1 on staging. v1.3+ short-circuits when the header is present and respectGpc is on (default). Easiest way: curl -H "Sec-GPC: 1" https://shop.tld/ and grep for setSiteId / data-domain — should be empty. If you see the script, GPC isn't being respected.
[ ] Review the per-SC config for multi-store shops. analytics_tracker_config() reads per-sales-channel — if you've configured Matomo for SC A and Plausible for SC B, the backends genuinely are different per domain. Verify the right script appears on each.
[ ] trackAdminUsers=false is the right default. Don't flip it to true to "see admin sessions" — admin browsing skews funnel + session metrics. If you specifically want to test the storefront without polluting stats, use Matomo's "Opt out of tracking" link or a separate browser profile.

Compatibility

Core platform

Shopware	PHP	Status
6.7.x — tested against 6.7.8, 6.7.9	8.1, 8.2	Stable
6.6.x	—	Not supported
6.5.x and earlier	—	Not supported

Database

Engine	Version	Notes
MySQL	8.0+	Primary target; JSON functions used for config-row manipulation in migrations
MariaDB	10.11+	Tested end-to-end; earlier versions lack some JSON operator support

Browsers (storefront)

Evergreen browsers only — the two most recent stable releases of each:

Browser	Desktop	Mobile
Chrome / Chromium	✅	✅
Firefox	✅	✅
Safari	✅ (macOS)	✅ (iOS 16+)
Edge	✅	—

Internet Explorer and legacy Edge are not supported. The plugin emits no runtime JS (where applicable) so graceful degradation on older browsers usually still renders content, just without progressive enhancements.

Admin browsers

Same evergreen matrix — the Shopware admin is Vue-based and has its own compatibility baseline that this plugin doesn't extend or narrow.

Development

Tool	Version	Scope
PHP	≥ 8.1	Runtime + test suite
Composer	2.x	Dependency management
Node.js	≥ 18	Only needed if you edit SCSS and re-run the theme compile
Python	≥ 3.9	Only needed for the repo's asset-pipeline scripts (`scripts/*.py`)

Accessibility

WCAG 2.2 level A + AA — see docs/ACCESSIBILITY.md for axe-core audit output and per-page violations.

What we test before each release

Full PHPUnit unit suite against PHP 8.1 + 8.2 (source-inspection tests don't need a kernel)
PHPStan level 8 + PHP-CS-Fixer (@PSR12 + @Symfony)
Composer validate on every plugin
Live-DB smoke tests (plugin install → activate → route render → uninstall cycle)
axe-core audit on the primary storefront surfaces (see ACCESSIBILITY.md)

Related plugins

Part of the TenBruggencate Suite — small, focused plugins that play well together:

MultiBrand — provides the brandKey that brandDimensionId records, so Matomo reports can slice by brand without needing separate site IDs.
Maintenance — maintenance page renders with tracker disabled (no analytics noise during downtime).
LegalPages — Dutch / German / English legal page templates. Privacy page is the natural target for the Cookie Notice / DPA reference.
NewsletterLite — GDPR-safe newsletter signup that pairs naturally with privacy-first analytics.

Migration from the standalone Matomo plugin

If you previously used tenbruggencate/shopware-matomo, upgrade is automatic. Two migrations run on plugin:install --activate TenBruggencateAnalytics:

Migration1713225600CopyMatomoConfig — mirrors TenBruggencateMatomo.config.* rows into TenBruggencateAnalytics.config.*
Migration1776530000RemoveOrphanedMatomoPlugin — defensive cleanup of the now-unused plugin registry row

No admin reconfiguration needed; tracking continues uninterrupted.

Support

Email: guy@tenbruggencatedevelopment.nl
Docs & news: tenbruggencatedevelopment.nl
Source / issues: Bitbucket repo
Security vulnerabilities: see SECURITY.md — email first, no public issues, 72-hour acknowledgement SLA

tenbruggencate / analytics-lite

Maintainers

Package info

Statistics

Security