Track chat, search, auth, and dataplayer events in Matomo - #143
Merged
Merged
Conversation
The chat and dataplayer flows had no instrumentation at all, and search recorded only that a query was submitted, never its outcome. Adds: - Chat: message_sent, tool_call, run_latency_ms, results_returned, run_error - Search: results_returned, latency_ms, zero_results, error - Auth: login_completed, closing the funnel opened by gate_triggered - Dataplayer: tool_selected, run_submitted, run_succeeded, run_failed - FilePreview: opened, downloaded, failed - Error: react_boundary and route_error, so client crashes are counted Moves the _paq push into lib/analytics.ts so the class-based ErrorBoundary can reach it, leaving useMatomo a thin wrapper. Fixes a positional bug there: a value passed without a name landed in the name column. Also enables Matomo's heartbeat timer. Without it time-on-page is derived from the gap between pageviews, so the last page of every visit counted as zero seconds.
ritwikshanker
force-pushed
the
update-matomo
branch
from
August 20, 2026 11:32
f534b77 to
456caf0
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Adds comprehensive Matomo instrumentation across key user flows (chat, search, auth, dataplayer, file preview) and centralizes event pushing into a shared analytics helper so both hooks and class-based boundaries can track events consistently. Also enables Matomo heartbeat tracking to improve time-on-page accuracy.
Changes:
- Introduces
src/lib/analytics.ts(trackEvent,errorKind) and updatesuseMatomoto wrap the shared helper. - Adds new events for Chat, Search, Auth, Dataplayer, FilePreview, and client crash tracking (React error boundary + route error boundary).
- Enables Matomo
enableHeartBeatTimerto improve engagement metrics.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/root.tsx | Adds route-level error tracking via Matomo in the router ErrorBoundary. |
| src/pages/DataplayerPage.tsx | Tracks dataplayer tool selection and run outcomes (submitted/succeeded/failed) with latency. |
| src/pages/ChatPage.tsx | Adds chat funnel instrumentation: message sent, tool calls, run latency, results count, and errors. |
| src/lib/analytics.ts | New module-level Matomo helper (trackEvent) plus stable error labeling (errorKind). |
| src/lib/analytics.test.ts | Adds unit tests for Matomo positional args and errorKind classification. |
| src/hooks/useSearchResults.ts | Tracks search outcomes (results count, latency, zero results, error) in addition to submission. |
| src/hooks/useMatomo.ts | Refactors hook into a thin wrapper around the shared trackEvent helper. |
| src/hooks/useAuth.ts | Tracks Auth/login_completed to close the gate-triggered funnel without leaking query strings. |
| src/components/MatomoTracker.tsx | Enables Matomo heartbeat timer for better time-on-page measurement. |
| src/components/ErrorBoundary.tsx | Adds tracking for React render crashes from the class-based boundary. |
| src/components/dataplayer/FilePreviewModal.tsx | Tracks preview opens, downloads, and failures with status classification. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Site search is already enabled on site id 10 and Matomo auto-detects the `q` parameter, so /search?q=... is counted as a search today — this is where the 693 searches in the last report came from. What it cannot know that way is how many results came back, which is why "Search Keywords with No Results" is empty. useSearchResults now reports the search explicitly with its hit count, and MatomoTracker holds back the pageview for that navigation, since Matomo counts a site search instead of a pageview rather than as well as one. The action count per visit is unchanged. The suppression is keyed on the keyword, not the route, because filtering is client-side: the URL changes but useSearchResults does not re-run, so suppressing on every /search URL would lose those actions entirely. A filter change still sends the pageview and is still detected as a search from `q`, which is how it has always been counted. A failed search falls back to the pageview rather than reporting zero hits, which would otherwise file it under no-result keywords.
Addresses review on #143. Both error boundaries were sending error.message as the event name. Messages from this app can carry a dataset title, a file path or a query the user typed, and every distinct one becomes its own row in the Events report. Both now send the constructor name, with route responses still reported by status code. Full detail stays in the console via logError. Also drops an unsound cast in the analytics push helper. The helper does need to accept booleans — trackSiteSearch passes `false` for an omitted category — so rather than narrowing the parameter, the _paq global is widened to match Matomo's actual command vocabulary and the cast goes away. Narrowing instead fails to compile on the trackSiteSearch call.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request significantly enhances analytics and event tracking throughout the application, focusing on improved Matomo integration, more granular event reporting, and robust testing. The changes introduce event tracking for user actions like file previews, downloads, authentication flows, error boundaries, and search result interactions, while also adding comprehensive tests for the analytics utilities.
Analytics and Event Tracking Improvements
Testing and Utility Enhancements
MatomoTrackercomponent to verify correct event dispatching in various navigation and search scenarios.Codebase and Dependency Updates
useMatomohook to provide a stable, module-leveltrackEventfunction for safe use in dependency arrays.These changes collectively provide more actionable analytics, improve the accuracy of event reporting, and ensure the analytics layer is robustly tested and easier to maintain.The chat and dataplayer flows had no instrumentation at all, and search recorded only that a query was submitted, never its outcome. Adds:
Moves the _paq push into lib/analytics.ts so the class-based ErrorBoundary can reach it, leaving useMatomo a thin wrapper. Fixes a positional bug there: a value passed without a name landed in the name column.
Also enables Matomo's heartbeat timer. Without it time-on-page is derived from the gap between pageviews, so the last page of every visit counted as zero seconds.