Skip to content

feat(docs): enhance Matomo analytics tracking - #36743

Merged
rusackas merged 7 commits into
masterfrom
feat/enhanced-matomo-analytics
Dec 18, 2025
Merged

feat(docs): enhance Matomo analytics tracking#36743
rusackas merged 7 commits into
masterfrom
feat/enhanced-matomo-analytics

Conversation

@rusackas

@rusackas rusackas commented Dec 18, 2025

Copy link
Copy Markdown
Member

Summary

Comprehensive enhancement of Matomo analytics on the Superset docs site to capture richer user behavior data. This addresses the observation that our stats are lower than other ASF projects.

New Tracking Features

Feature What it tracks Why it matters
Site search Algolia queries + result counts See what users search for (and don't find)
Scroll depth 25%, 50%, 75%, 100% milestones Identify pages that lose readers
404 errors Not-found page visits Find broken links and missing content
Code copying Copy events on code blocks See which snippets are most useful
External links Clicks by domain (vendor-agnostic) Understand which resources users want
Downloads PDF, ZIP, office docs, data files Track file download engagement
Video plays Homepage video engagement Measure video effectiveness
CTA clicks "Get Started" button clicks Track conversion funnel
Docs version Which version users are reading Segment by version popularity
Color mode Dark/light mode preference + changes Understand user preferences

Implementation Details

  • Zero admin config: All tracking uses events, no custom dimensions needed
  • Vendor-agnostic: External links tracked by hostname, not hardcoded categories (ASF neutral)
  • Privacy-conscious: No PII collected, just behavioral events
  • Performance: Scroll tracking uses passive listeners, copy tracking is lightweight
  • Proper cleanup: All event listeners properly removed on unmount

Test plan

  • Run docs site locally (yarn start) and open browser console
  • Verify page views logged on navigation
  • Test scroll tracking shows 25/50/75/100% events
  • Test Algolia search triggers trackSiteSearch
  • Test clicking external links triggers categorized events
  • Test copying code triggers Code > Copy event
  • Visit a non-existent URL and verify 404 tracking
  • Toggle dark/light mode and verify Color Mode Change event
  • Check no errors in browser console

🤖 Generated with Claude Code

Add comprehensive tracking features to improve analytics data:

- **Site search tracking**: Track Algolia search queries with result counts
- **Download tracking**: Track downloads of common file types (PDF, ZIP, etc.)
- **Event tracking**: Track user interactions including:
  - External link clicks with domain categorization (GitHub, Slack, etc.)
  - CTA button clicks (Get Started buttons)
  - Video plays on homepage
- **Outbound link categorization**: Better insight into which external
  resources users visit most

These improvements will provide better visibility into user behavior
and help identify the most valuable content and resources.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bito-code-review

bito-code-review Bot commented Dec 18, 2025

Copy link
Copy Markdown
Contributor

Code Review Agent Run #942b84

Actionable Suggestions - 0
Additional Suggestions - 1
  • docs/src/theme/Root.js - 1
    • Analytics data inaccuracy · Line 132-132
      When Algolia search returns zero results, this code passes `false` to Matomo instead of `0`, which misrepresents the data. Matomo distinguishes between unknown results (`false`) and no results (`0`).
Review Details
  • Files reviewed - 1 · Commit Range: ed22867..ed22867
    • docs/src/theme/Root.js
  • Files skipped - 0
  • Tools
    • Eslint (Linter) - ✔︎ Successful
    • Whispers (Secret Scanner) - ✔︎ Successful
    • Detect-secrets (Secret Scanner) - ✔︎ Successful

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

  • /review - Manually triggers a full AI review.

  • /pause - Pauses automatic reviews on this pull request.

  • /resume - Resumes automatic reviews.

  • /resolve - Marks all Bito-posted review comments as resolved.

  • /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

AI Code Review powered by Bito Logo

@dosubot dosubot Bot added the doc Namespace | Anything related to documentation label Dec 18, 2025
@codeant-ai-for-open-source codeant-ai-for-open-source Bot added the size:L This PR changes 100-499 lines, ignoring generated files label Dec 18, 2025
@codeant-ai-for-open-source

This comment was marked as outdated.

Comment thread docs/src/theme/Root.js Outdated
Comment thread docs/src/theme/Root.js Outdated
Comment thread docs/src/theme/Root.js
rusackas and others added 2 commits December 18, 2025 09:21
Include 127.0.0.1, ::1, and 0.0.0.0 in addition to localhost
to prevent polluting analytics from local development sessions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Pass results.length directly instead of results.length || false
so Matomo correctly tracks searches with zero results.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@apache apache deleted a comment from codeant-ai-for-open-source Bot Dec 18, 2025
Store handler function references when adding event listeners
so they can be properly removed during cleanup, preventing
memory leaks and duplicate tracking.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@apache apache deleted a comment from codeant-ai-for-open-source Bot Dec 18, 2025
rusackas and others added 3 commits December 18, 2025 09:27
Replace hardcoded vendor categories with hostname-based tracking
to maintain ASF vendor neutrality. All external links are now
categorized by their domain (e.g., github.com, stackoverflow.com)
without showing favoritism to any organization.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Comprehensive Matomo tracking enhancements:

- Scroll depth: Track 25%, 50%, 75%, 100% milestones per page
- 404 tracking: Detect and track not-found pages as Error events
- Copy tracking: Track when users copy from code blocks
- Custom dimensions: Track docs version and color mode preference
- Color mode changes: Track when users toggle dark/light mode

These additions provide deeper insight into user engagement and
help identify content issues (pages users don't finish reading,
broken links leading to 404s, most-copied code snippets).

Note: Custom dimensions require configuration in Matomo admin
(dimension IDs 1 and 2 for docs version and color mode).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace custom dimensions with regular events for color mode
and docs version tracking - no Matomo admin config required.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@rusackas
rusackas merged commit 32435bc into master Dec 18, 2025
61 checks passed
@rusackas
rusackas deleted the feat/enhanced-matomo-analytics branch December 18, 2025 21:52
qfcwell pushed a commit to qfcwell/superset that referenced this pull request May 12, 2026
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Namespace | Anything related to documentation preset-io size/L size:L This PR changes 100-499 lines, ignoring generated files

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants