Check this page with an assistantOpens a chat asking it to summarise this article and name the evidence behind each claim.
Claude opens with the prompt on your clipboard: Anthropic does not support prefilled prompts on the web, and we would rather copy it than ship a button that drops it.
Decisions first
Send only governed events to Matomo's HTTP Tracking API with idsite, rec=1, the real page URL and action name, a random request value, and a stable pseudonymous visitor ID only when policy permits. Forward source IP and user agent only under an approved privacy design. Mark server-originated events, prevent the browser tracker from sending the same event, and validate both the Live Visitors log and Reporting API before using the data for SEO decisions.
- Server-side transport does not remove consent, retention, or identity obligations.
- Every event class needs exactly one owner: browser, server, or a documented reconciliation rule.
- Matomo cannot recover the individual Google query hidden from analytics; bridge aggregate Search Console data separately.
Write an event-ownership contract
List each pageview and conversion event, its authoritative sender, identity rule, source fields, consent gate, and deduplication key.
A common safe pattern keeps ordinary pageviews in the JavaScript tracker and sends only confirmed backend outcomes—such as an accepted signup or paid invoice—from the server. If pageviews also move server-side, the server must reconstruct URL, referrer, campaign, device context, visitor identity, and timing deliberately rather than inheriting them from the browser.
Create an event matrix before implementation. A form submit captured in JavaScript and the resulting lead creation captured on the server may be two useful stages; sending the same conversion name from both without a unique event key is duplicate measurement.
| Event | Owner | Identity | Duplicate rule |
|---|---|---|---|
| Pageview | Browser or server | Policy-approved visitor key | One sender per navigation |
| Form accepted | Server | Submission ID | Upsert once |
| Purchase | Server | Order ID | Reject repeat revenue |
| SPA route | Browser | Route transition | One event per committed route |
Construct the Tracking API request explicitly
Use Matomo's documented tracking endpoint and parameters, then add only metadata the governance contract allows.
The endpoint is matomo.php. A basic request includes idsite and rec=1; useful fields include url, action_name, apiv, rand, a 16-character hexadecimal visitor ID when appropriate, and goal or ecommerce fields for documented outcomes. Send over HTTPS and keep authentication material out of logs.
A backend request otherwise describes the server, not necessarily the visitor. User agent, IP, referrer, language, campaign values, and timestamps need an explicit source and privacy rationale. Never copy arbitrary request headers or sensitive URL parameters into analytics.
- Site ID
- Canonical page URL
- Action name
- Event or order ID
- Consent state
- Sender marker
- Random cache-buster
- Approved client context
Preserve consent and data minimization at the server
A first-party server endpoint can make tracking less visible to the browser, but it does not make the collection exempt from policy or law.
Apply the site's consent decision before enqueueing the event, not after it reaches Matomo. Minimize URL parameters, custom dimensions, IP handling, user IDs, and log retention. Document how opt-out, deletion, and data-subject requests reach both the application and Matomo records.
Use a pseudonymous identifier only for the shortest justified scope. Do not repurpose account IDs, emails, or CRM record IDs as analytics visitor IDs unless an approved design explicitly requires it and visitors receive the corresponding disclosure and controls.
Validate raw events, reports, and search boundaries
Prove one event through capture, Matomo ingestion, deduplication, report availability, and downstream decision before scaling the tracker.
Run fixtures for refreshes, back-button navigation, SPA routes, bots, retries, rejected consent, repeated orders, and clock skew. Compare the Live Visitors view with Reporting API aggregates and label processing delays. Use HTTPS for Reporting API calls and protect token_auth as a secret.
For SEO, map Matomo landing pages and outcomes to canonical page IDs. Add aggregate Search Console query-page metrics in a separate table or view. Server-side tracking cannot reveal the hidden query for an individual organic visitor and should never be sold as if it can.
Decide what creates a visit before choosing an identifier
A server can send Matomo a valid request while still creating the wrong visit model. Define when a visit begins, which actions belong to it, and whether any stable visitor identifier is justified before setting _id, cid, or uid.
Matomo recommends a unique 16-character hexadecimal visitor ID for stable visitor measurement, but generating a technically valid value does not answer the privacy question. Decide whether the use case needs anonymous action counts, pseudonymous visit continuity, or logged-in user analysis. If pageviews remain browser-owned and only confirmed conversions arrive from the server, reuse identity only through an approved, short-lived bridge. Otherwise the conversion may open a new server-shaped visit and receive misleading source attribution.
Document the session boundary for delayed backend outcomes. A payment webhook may arrive minutes or days after the landing session; forcing it into a recent visit because an identifier matches can overstate direct influence. Preserve order ID, landing evidence, and the application event time, then report the conversion under a stated attribution rule. Do not use email addresses, CRM IDs, or raw account identifiers as convenient analytics keys. Hashing a stable personal identifier does not make the linkage anonymous.
| Use case | Identity approach | Main risk |
|---|---|---|
| Anonymous pageview | Browser-generated visitor state | Server duplicates the navigation |
| Accepted form | Immutable submission ID | Counting submit and acceptance as one event |
| Logged-in journey | Governed uid or pseudonymous mapping | Unnecessary cross-session profiling |
| Delayed purchase | Order ID plus explicit attribution rule | Attaching revenue to the wrong visit |
Make delivery observable and retries harmless
Treat the Matomo request as a delivery job with a stable event identity, bounded retry policy, and response evidence; a 2xx response proves acceptance at the endpoint, not correct reporting or unique counting.
Build a canonical server event first, then translate it to Matomo parameters. Save its event or order ID, event time, sender, consent decision, destination site ID, attempt count, and terminal outcome. Encode string parameters, send over HTTPS, and use send_image=0 when the integration expects an HTTP 204 rather than a tracking pixel response. Redact token_auth and personal fields from request logs. If an override requires authentication, use a dedicated Matomo user with only the documented write access.
Retry network failures and documented transient responses with backoff, but do not assign a new logical event ID on every attempt. Ecommerce orders have an explicit order identifier; application events need an equivalent deduplication contract in the sender or processing layer. For batches, keep each request independently identifiable so one malformed item does not become an invisible hole. Record dead-lettered events and reconcile them rather than silently dropping data or replaying an unbounded queue after an outage.
- Immutable application event or order ID
- URL-encoded documented parameters
- HTTPS destination and secret-safe logs
- Bounded exponential retry
- No new identity on retry
- Dead-letter review and replay owner
Keep human analytics and bot telemetry in separate datasets
Matomo's current Tracking API can record selected user-triggered AI assistants through bot-specific modes, but those requests must not be mixed into ordinary human visits or presented as search traffic.
The current API documents recMode values for visit-only, bot-only, and automatic routing, with bot records requiring a user agent plus a URL or download. That can support a separate operational question—whether selected user-triggered assistants reached a document—but it does not measure citations, answer visibility, or a person's subsequent decision. Traditional crawlers may still be detected and discarded. Define the eligible bot set and limitations before sending edge or server logs into Matomo.
If the site already records request logs at the CDN or origin, decide which system is authoritative for bot reach. Forwarding the same request from both layers creates duplicates just as it does for human events. Keep bot dashboards, retention, filters, and alerts separate from visitor acquisition reports. A ChatGPT-User request to a page is evidence of retrieval, not evidence that ChatGPT recommended the brand, quoted the page, or sent a visitor.
Run a control window before replacing browser collection
Compare browser and server observations for a fixed cohort without summing them. The purpose is to explain differences and choose ownership, not to make the new number match the old one.
Select ten canonical landing pages and a seven- or twenty-eight-day window. For each source, record the event definition, consent eligibility, bot filtering, timezone, canonicalization, campaign handling, and processing delay. Reconcile representative sessions and conversions by event ID where policy permits. Separate expected gaps—blockers, rejected consent, backend-only outcomes—from defects such as duplicate pageviews, malformed URLs, or purchases recorded twice.
Do not switch ownership until refresh, back-forward navigation, SPA transitions, retries, clock skew, delayed webhooks, and rejected consent all have passing fixtures. After the cutover, keep the old sender disabled rather than merely hidden and monitor event volume, unique visitors, channel mix, and revenue for discontinuities. Annotate the reporting date so later analysis does not interpret a measurement change as an SEO win or loss.
| Difference | Likely explanation | Decision |
|---|---|---|
| Server higher | Blockers or duplicate server sends | Reconcile event IDs |
| Browser higher | Rejected server events or missing bridge | Inspect delivery outcomes |
| Revenue doubled | Two event owners | Disable one sender immediately |
| Organic shifted | URL/referrer reconstruction | Audit canonical and source fields |
Read the event back through the same report used for decisions
A request visible in an ingestion log is not finished until the expected action, visit, source, and conversion appear in the production reporting view with the documented delay and filters.
Create a non-production site or clearly labelled test cohort and send one fixture for every event owner. Save the outbound event ID, Matomo response, expected visitor or order identity, event timestamp, canonical URL, referrer class, and consent state. Then query the Reporting API using the same timezone, segment, archive period, and filters the SEO dashboard will use. Compare action counts, visits, unique visitors, goals, and revenue separately; one passing total does not prove the other scopes are correct.
Repeat the read-back after Matomo upgrades, tracker configuration changes, consent-banner releases, reverse-proxy changes, and new custom dimensions. Include a late event, a retried event, and a deliberately rejected event. If a fixture appears in Live Visitors but not the decision report, investigate archiving and report filters before replaying it. If it appears twice, stop the competing sender or repair deduplication before collecting more data. The acceptance criterion is a traceable measurement contract, not merely a successful HTTP request.
Continue the workflow
Instrument one server-confirmed conversion in a non-production Matomo site and test consent denial, retries, duplicate browser events, identity, and report read-back.
- Matomo and Search Console SEO: build the aggregate page-level bridge after tracking is trustworthy
- organic attribution scopes: compare how analytics scope changes the claim
- SEO reporting framework: label measured outcomes and confidence
Questions teams ask
- Does Matomo require JavaScript for tracking?
No. Matomo documents an HTTP Tracking API and server-side clients, but the implementation must supply context, consent, identity, and duplicate controls that browser tracking would otherwise handle.
- How do I stop browser and server events from double-counting?
Assign one sender to each event class or use a shared immutable event ID with an explicit reconciliation rule. Test retries, SPA navigation, and confirmed backend outcomes.
- Can server-side Matomo tracking reveal Google keywords?
No. Use Search Console's aggregate query-page reporting for Google visibility and bridge it to Matomo only at governed page and time-window levels.
Primary sources
The SearchHandled Editorial Team prefers first-party documentation and names the limits of each source. Links were checked on the access date.
- Matomo Developer Documentation: HTTP Tracking API referenceAccessed August 29, 2026
- Matomo Developer Documentation: Tracking API clientsAccessed August 29, 2026
- Matomo Developer Documentation: Querying the Reporting APIAccessed August 29, 2026 · Reporting tokens should be sent only over HTTPS and kept out of client code and logs.
- Matomo Developer Documentation: JavaScript tracking guideAccessed August 29, 2026
- Google Search Console Help: Performance report: clicks, impressions, CTR, and positionAccessed August 29, 2026 · Defines Search Console metrics; it does not create a user-level analytics join.
