Connect Matomo¶
Connecting Matomo gives Squoosh a source to calibrate your synthetic shoppers against. Squoosh reads your recorded traffic and shapes the shopper pool to match your real visitors, so experiment results reflect your actual audience. This page covers what the connection does and how to set it up from the Integrations page.
Beta
Matomo is a newly added connector. It calibrates device, geography, and traffic-source mix from real visit counts, plus a conversion rate when your site has goals configured. Works with both self-hosted Matomo and Matomo Cloud.
What the connection does¶
Matomo is a calibration source. Once connected, Squoosh reads your recorded visit traffic and builds synthetic shoppers whose mix of device, traffic source, and geography matches your real visitors — the same role Google Analytics or Shopify Analytics plays. Squoosh also reads your site's goal conversions to ground shopper behavior against, when goals are configured.
The connection is not required to run a test — Squoosh can build a pool from a general e-commerce mix without it. For how the calibrated pool behaves and how the match is measured, see Synthetic shoppers.
Connect Matomo¶
You'll need a Matomo API token (in Matomo, under Administration → Personal → Security → Auth tokens), your instance's URL, and your site ID.
- In the sidebar, click Integrations.
- In the Matomo row, click Connect.
- Enter:
- API token — kept private; Squoosh never shows it again after you save it.
- Matomo URL — your instance's base URL, e.g.
https://analytics.example.com(self-hosted) or your Matomo Cloud URL. - Site ID — the numeric ID of the site to read from.
- Goal ID (optional) — a specific goal to report conversions for. Leave it blank to use all goals configured on the site.
- Click Connect.
Squoosh verifies the token and site live before saving. The row shows Connected — syncing while the first calibration read runs, then Calibrating shoppers from Matomo once real data is grounding your shopper pool.
What it grounds¶
| Dimension | Source | Notes |
|---|---|---|
| Device | DevicesDetection.getType |
|
| Geography | UserCountry.getCountry |
|
| Traffic source | Referrers.getReferrerType |
Matomo's "Campaigns" referrer type is mapped to Paid Search — Matomo doesn't split organic vs. paid search on its own. Traffic Matomo attributes to an AI assistant (e.g. ChatGPT, Perplexity) is folded into Referral. |
| Conversion rate | Goals.get conversions vs. VisitsSummary.get visits |
A true visit-based rate. A genuine zero (a goal exists but had no conversions this window) is reported honestly, not hidden. |
A dimension needs a reasonable amount of traffic before Squoosh treats it as real signal — a handful of visits doesn't become a fabricated distribution. Below that floor, Squoosh leaves the dimension out of calibration rather than guessing.
Limits and caveats¶
- No goals configured on the site means no conversion rate. Squoosh never invents one.
- "Campaigns" traffic is folded into Paid Search as the closest approximation, since Matomo's referrer-type taxonomy has no organic/paid split within campaigns.
- Works identically for self-hosted Matomo and Matomo Cloud — just point Matomo URL at your instance.
Troubleshooting¶
| Problem | What to do |
|---|---|
| Connection fails immediately | Confirm the API token is still valid and that the Matomo URL and site ID are correct. |
| "Missing Matomo instance URL" or "site ID" | Both are required — reopen Connect and fill them in. |
| No conversion rate shows up | Your site needs at least one goal configured in Matomo. Set one up, then reconnect or wait for the next sync. |
Related¶
- Synthetic shoppers — how the calibrated pool behaves and how the match is read.
- Connect Google Analytics and Connect Shopify — the original calibration sources.
- Connect a CSV import — an alternative if you'd rather export numbers from another tool.