Skip to main content
Matomo is the default behavioural analytics for Vulpy Commerce. You can optionally layer Google Tag Manager and GA4 on top by setting a single environment variable. This page explains the setup, the data flow, and the consent and PII rules that apply to both pipelines.
Ask Fox to wire GTM. Fox knows which env vars are bake-time and which containers rebuild when you change them.Try prompts like:
  • “Explain how GTM coexists with Matomo.”
  • “Draft the GTM tag setup for GA4.”
  • “What has to rebuild if I change NEXT_PUBLIC_GTM_ID?”

​
Setup

1

Set your GTM ID

Add NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX to environments/<name>/.env for the target environment.
2

Rebuild the storefront

Because NEXT_PUBLIC_* variables are baked at build time in Next.js, you must rebuild the storefront image after changing the value.
3

Configure your GTM container

Open the Google Tag Manager UI for that container and create your tags, triggers, and variables. If you use GA4, add a GA4 configuration tag and any event tags you need.

​
Data flow

The same storefront events that feed Matomo can also feed GTM. The pipelines differ in one field:
  • Matomo receives a pseudonymized order id for purchase events.
  • GTM receives the merchant-facing display_id via NEXT_PUBLIC_GTM_ID.
Everything else follows the same PII rules. See Events Reference for the full list of built-in events and helper APIs. GTM should load only after the visitor opts into analytics. Vulpy exposes useHasAnalyticsConsent() in the storefront so you can gate GTM injection the same way Matomo is gated. If the visitor withdraws consent or sends a Global Privacy Control signal, both Matomo and GTM must stop. Any custom vendor tags you add inside GTM are your responsibility to gate on consent.

​
Vendor responsibility

You can use GTM without GA4, for example to load a Meta pixel or another third-party script. Any vendor you add is your responsibility to:
  • Gate loading on the same analytics consent state.
  • Keep PII out of payloads (no emails, names, raw ids, or card data).
  • Respect withdrawal and GPC signals.

​
Important: bake-time variable

NEXT_PUBLIC_GTM_ID is a bake-time environment variable in Next.js. Changing it requires rebuilding the storefront Docker image and redeploying the environment. It is not enough to restart the container.
For a full list of environment variables and their bake-time vs runtime behaviour, see Environment Variables.

​
Reference

Storefront analytics

Overview of the Matomo integration, consent banner, and dashboard setup in Vulpy Commerce.

Events Reference

Matomo event helpers, built-in categories, PII rules, and how to add custom events safely.