Skip to main content
Vulpy Commerce ships self-hosted Matomo as the behavioral analytics stack for your storefront. It is consent-gated at the storefront edge, optional locally, and required to go live. Order lifecycle reporting is separate and runs through Medusa without visitor consent.
Ask Fox to check Matomo. Fox can tell you if it’s up, add events, and diff dev vs. staging tracking.Try prompts like:
  • “Is Matomo running on dev?”
  • “Add a Matomo event for the newsletter signup CTA.”
  • “Which events are firing on the homepage right now?”

​
Environments

pnpm vulpy env golive live will refuse if Matomo is not up. Self-hosting is not a consent exemption; you still need consent to track visitors.

​
Start Matomo locally

Local Matomo lives at http://localhost:8081 by default. On a VPS with a domain, it is served at https://analytics.<domain>; on Tailscale-only installs, at https://<magicdns>:8081.
On NTFS or exFAT hosts, Matomo application files and its MariaDB fall back to ~/.local/share/<project>/matomo and ~/.local/share/<project>/matomo-db instead of .data/.

​
Production setup and verification

The production install runs Matomo setup automatically, but you can run the two operational scripts on demand:
deploy:matomo:verify checks the privacy and legal gates that gate env golive live.

​
Two analytics lanes

Vulpy Commerce separates behavioral analytics from operational reporting. Each has different consent requirements and a different destination.
Purchase events send Matomo a pseudonymized order id. If you have also configured GTM/GA4 via NEXT_PUBLIC_GTM_ID, GTM gets the merchant display_id. Logged-in user_id is a hashed customer id only.
  • No Matomo script, request, or _pk_* cookie is loaded before the visitor opts in on the storefront.
  • Withdrawing consent clears cookies and stops requests.
  • GPC (Global Privacy Control) is treated as denial.
  • Payloads never contain email, name, address, raw customer or order IDs, JWTs, card data, or unrestricted query strings.
  • Purchases are only reported on the order confirmation page, deduped, so payment-return polling does not double-count.

​
Add events for a new feature

When you build storefront UX that affects funnel or engagement (forms, CTAs, filters, drawers, auth outcomes, promotions, new checkout steps), instrument Matomo in the same change. Reuse the helpers in apps/storefront/src/lib/analytics/:
  • trackCustomEvent(category, action, name?, value?) for custom events
  • trackProductImpression and trackSelectItem for catalog interactions
  • Cart mutations flow through applyCartResult on CartContext
Gate every event with useHasAnalyticsConsent(), or rely on pushMatomoCommand, which no-ops without consent and configuration.

Go live

The go-live checklist, including Matomo gates.

Manage orders

Operational reporting is separate from Matomo.