Connect Matomo

Previous Next

Connect Matomo

Connecting Matomo lets Squoosh calibrate AI shoppers from your recorded traffic. The connector reads visit counts by device, geography, and traffic source from self-hosted Matomo or Matomo Cloud, plus a goal conversion rate when you choose a goal.

Beta: known calibration limits

The connector reads reporting snapshots. A successful connection check proves site access. The optional Goal ID is confirmed against your site's goal configuration on every snapshot sync, not at connect time. Localized device labels and legacy country codes have known limitations described below.

What the connection does

Squoosh reads aggregate reports to shape the AI shopper pool. When a Goal ID is configured and confirmed, it pairs Goals.get.nb_visits_converted (visits that converted) with VisitsSummary.get.nb_visits (all visits) when both metrics are available and visits are positive. It does not use the total number of goal completions as the numerator.

The connector requests aggregate reports, not individual visitor records. It does not change your Matomo configuration. You can also run experiments without a connected analytics source.

Connect Matomo

You'll need a Matomo API token, your instance's URL, and your site ID. Create a token under Administration → Personal → Security → Auth tokens for a user with view access to the site.

  1. Open Integrations and select Connect for Matomo.
  2. Enter your API token. Squoosh sends it in the POST body, never in the request URL.
  3. Enter your Matomo URL, such as https://analytics.example.com, and the site's positive integer Site ID.
  4. Optionally enter a Goal ID. Leave it blank and Squoosh reads traffic only, with no conversion signal and the matomo_goal_not_selected warning. Enter a goal's numeric ID from Goals → Manage goals to use that goal. Two explicit selectors are also accepted: all reads Matomo's overall goal metric, which can include ecommerce orders and goals deleted since the reporting window, and ecommerceOrder (or 0) reads ecommerce orders only. Abandoned-cart selectors are not accepted and leave the goal unvalidated.
  5. Click Connect.

Squoosh checks access with a one-day VisitsSummary.get request before saving. On each snapshot sync it confirms the goal before reading it: a numeric ID must appear in the site's Goals.getGoals list, all needs at least one goal in that list, and ecommerceOrder needs ecommerce enabled for the site in SitesManager.getSiteFromId. If Matomo answers but does not vouch for the goal, Squoosh keeps the traffic results, omits the conversion rate, and records the matomo_goal_unvalidated warning. A 401, 403, 404, 429, 5xx, or timeout on that lookup fails the whole sync rather than saving a snapshot with no conversion figure. Device, geography, traffic-source, and goal reports are read during the snapshot sync. See Matomo's Reporting API reference for authentication and metric definitions.

What it reads

Dimension Report Current interpretation
Device DevicesDetection.getType English Smartphone and Phablet labels become mobile; Desktop and Tablet retain their categories. Other labels are omitted.
Geography UserCountry.getCountry Uses country code, not the display label. Unknown xx is omitted; xk is retained.
Traffic source Referrers.getReferrerType Each row's numeric referrer_type selects the Squoosh channel, so translated labels still map. Direct entry, search engines, websites, social networks, and AI assistants become Direct, Organic Search, Referral, Social, and Referral. Campaign visits stay in an unmapped Campaigns bucket.
Conversion rate Goals.get and VisitsSummary.get Converting visits divided by total visits, only for a confirmed Goal ID. A confirmed goal with no converting visits is reported as zero.

Reports cover the requested number of days including today, relative to the Matomo site's timezone. Squoosh applies its shared minimum-sample floor before using a traffic dimension for calibration.

Limits and caveats

  • A blank or unconfirmed Goal ID means no conversion rate. Squoosh never falls back to overall goal metrics on its own. The snapshot carries the matomo_goal_not_selected warning when the field is blank, and matomo_goal_unvalidated when a goal was chosen but the site's configuration could not validate it: the numeric ID is not in the goal list, ecommerceOrder is set on a site without ecommerce, or the value is not one Squoosh accepts. A zero rate is only reported for a confirmed goal.
  • all reads an archived overall metric. Matomo's overall goal metric can include ecommerce orders and goals that no longer exist. Squoosh does not sum the current goals itself. Use a numeric ID when you need a single goal.
  • Campaigns stay unmapped. Matomo's referrer-type report does not say which medium a campaign used, so Squoosh keeps campaign visits in a Campaigns bucket rather than guessing Paid Search or any other category. Campaign names and keywords are never read as evidence of a medium.
  • Device mapping currently expects English labels. Matomo can localize device-type labels, and a non-English device report can leave device calibration empty. Traffic-source mapping is unaffected because it keys on the numeric referrer_type; English labels are only a fallback for rows without one.
  • Legacy country pseudo-codes can pass through. The connector currently excludes only Matomo's xx unknown-country code.
  • Range reports can require archiving. Goal confirmation and every report read share a single 10-second budget per sync; Matomo does not document a completion-time guarantee. Large instances may need archive preparation. See Matomo's archiving specification.
  • Provider caps are not inferred. The connector requests all breakdown rows with filter_limit=-1. These responses do not expose a reliable provider-cap signal, so Squoosh does not claim to have observed truncation.

Troubleshooting

Problem What to do
Matomo rejected the API token, or its user cannot view Site ID <id> Matomo 5 answers HTTP 401 for both causes, so the message names both. Check whether the token expired or was revoked, then confirm the token's user has view access to that Site ID. Rotating the token does not help when the user lacks site access.
Missing site access Grant the token's user view access to the configured site and confirm its Site ID. A view-access refusal can use HTTP 401 (the row above) or 403.
Site ID rejected Enter the site's positive integer ID, not a site name or URL.
Required plugin missing or deactivated Check that DevicesDetection, UserCountry, Referrers, and Goals are available and enabled on the instance. An HTTP 404 can mean either a missing plugin or a wrong installation URL, so check both.
Installation URL not found Check the base URL and that its index.php Reporting API endpoint is reachable.
Rate limit reached Wait before retrying. See Matomo Cloud API limits.
No conversion rate, with matomo_goal_not_selected Expected. Enter a Goal ID to add a conversion signal.
No conversion rate, with matomo_goal_unvalidated Confirm the Goal ID appears under Goals → Manage goals for this site, or that ecommerce is enabled when using ecommerceOrder. Traffic results remain available.
Sync fails during goal confirmation The goal lookup returned an error instead of an answer. Fix the token, site-access, plugin, or rate-limit problem it reports. Squoosh does not save a snapshot without the conversion figure in that case.
Conversion rate is zero The goal was confirmed but no visits converted in the window. Check the goal's trigger and the reporting window in Matomo.
Missing device calibration Check the language of the token owner's reports and the amount of traffic available.
Traffic source shows a Campaigns bucket Expected. Campaign visits are kept unmapped; see the caveat above.

HTTP status handling follows Matomo's developer changelog. Squoosh returns fixed troubleshooting messages instead of exposing provider error bodies.

Connect Plausible Connect Adobe Analytics