Add matomo integration

[zairro]

Title

Add Matomo analytics integration for GitBook (pageviews, referrers, clicks, goals, SPA)

Overview

Adds a new analytics integration enabling published GitBook sites to send analytics to a Matomo cloud or self‑hosted instance. Consent-aware and SPA-friendly.

• Folder: integrations/matomo
• Target: site
• Consent: respects GitBook cookie consent
• SPA: tracks client-side navigations

Implementation

• integrations/matomo/gitbook-manifest.yaml
  • Scopes: site:script:inject, site:script:cookies
  • Category: analytics
  • CSP: allows script-src, img-src, connect-src to user-provided Matomo hosts (host is configured per site)
  • Configurations:
    • server_url (required): Matomo base URL
    • site_id (required): Matomo site ID
    • load_js_tracker (default true): load matomo.js for richer tracking; beacon fallback when disabled
    • track_referrer (default true)
    • track_outbound_clicks (default true)
    • click_selectors (string): comma-separated CSS selectors for custom click events
    • goal_mappings_json (string): JSON mapping of CSS selectors → Matomo Goal IDs
    • user_id_cookie (string): cookie name to set Matomo uid
• integrations/matomo/src/index.ts: serves configured tracking script
• integrations/matomo/src/matomoScript.raw.js:
  • Pageviews (initial + SPA)
  • Optional matomo.js load (first‑party cookies, enableLinkTracking)
  • Referrer (configurable)
  • Outbound link tracking (configurable)
  • Custom click tracking via selectors
  • Goal triggers from selector mappings
  • Optional uid from cookie
• Supporting files: global.d.ts, package.json, tsconfig.json, CHANGELOG.md, assets/icon.png

Security and privacy

• Honors GitBook consent (no tracking before consent)
• Uses first‑party matomo.js when enabled; otherwise a lightweight Tracking API beacon to the configured host
• CSP is permissive to support user‑defined Matomo hosts (can be narrowed if host-level CSP becomes dynamic)

Testing

• Install CLI and run a dev session for a space:
  • npm i -g @gitbook/cli
  • gitbook auth --token <token>
  • From integrations/matomo: gitbook dev <spaceId>
• Configure in the space: server_url, site_id (+ optional fields)
• Validate requests to <server_url>/matomo.php and, if enabled, <server_url>/matomo.js
• Confirm pageviews (initial + SPA), optional referrers, outbound clicks, configured selector events, and goals

References

• Matomo: Integrate Matomo (developer.matomo.org/integration)
• GitBook: Integrations overview (link), CLI (link), Configurations (link), Runtime (link)

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 135f09623a18a66218940d2232244e4c8425aa78

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[addisonschultz]

Hello @zairro - thank you for building this integration! Can you please reach out to me at addison @ gitbook.com to go through a few more tasks related to developing this integration? Thanks!

[pkg-pr-new[bot]]

Open in StackBlitz

bun add https://pkg.pr.new/GitbookIO/integrations/@gitbook/api@931

commit: 135f096