Add matomo integration

bun.lock

@@ -16,7 +16,7 @@
     },
     "integrations/ahrefs": {
       "name": "@gitbook/integration-ahrefs",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -381,9 +381,21 @@
         "esbuild": "^0.15.7",
       },
     },
+    "integrations/matomo": {
+      "name": "@gitbook/integration-matomo",
+      "version": "0.1.0",
+      "dependencies": {
+        "@gitbook/api": "*",
+        "@gitbook/runtime": "*",
+      },
+      "devDependencies": {
+        "@gitbook/cli": "workspace:*",
+        "@gitbook/tsconfig": "workspace:*",
+      },
+    },
     "integrations/mermaid": {
       "name": "@gitbook/integration-mermaid",
-      "version": "0.4.0",
+      "version": "0.4.2",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -433,7 +445,7 @@
     },
     "integrations/plausible": {
       "name": "@gitbook/integration-plausible",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -507,7 +519,7 @@
     },
     "integrations/segment": {
       "name": "@gitbook/integration-segment",
-      "version": "2.1.3",
+      "version": "2.3.0",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -652,7 +664,7 @@
     },
     "packages/api": {
       "name": "@gitbook/api",
-      "version": "0.135.0",
+      "version": "0.136.0",
       "dependencies": {
         "event-iterator": "^2.0.0",
         "eventsource-parser": "^3.0.0",
@@ -1035,6 +1047,8 @@
 
     "@gitbook/integration-marketo": ["@gitbook/integration-marketo@workspace:integrations/marketo"],
 
+    "@gitbook/integration-matomo": ["@gitbook/integration-matomo@workspace:integrations/matomo"],
+
     "@gitbook/integration-mermaid": ["@gitbook/integration-mermaid@workspace:integrations/mermaid"],
 
     "@gitbook/integration-mixpanel": ["@gitbook/integration-mixpanel@workspace:integrations/mixpanel"],

integrations/matomo/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0
+
+- Initial release of the Matomo integration for GitBook. Injects a lightweight tracker using the Matomo Tracking API with SPA navigation support and cookie consent awareness.
+
+## 0.1.1
+
+- Update icon to square, icon-only mark for better marketplace display
+- Add preview image
+- Switch visibility to `public` for marketplace readiness
+- Improve manifest descriptions and validation to meet CLI limits

integrations/matomo/gitbook-manifest.yaml

@@ -0,0 +1,91 @@
+name: matomo
+title: Matomo
+icon: ./assets/icon.png
+previewImages:
+    - ./assets/preview.png
+organization: 2zoWGxtV7bjhbwBdjGPS
+description: Receive GitBook traffic insights directly in your Matomo dashboard.
+visibility: public
+script: ./src/index.ts
+# The following scope(s) are available only to GitBook Staff
+# See https://developer.gitbook.com/integrations/configurations#scopes
+scopes:
+    - site:script:inject
+    - site:script:cookies
+categories:
+    - analytics
+contentSecurityPolicy:
+    # Allow loading Matomo JS tracker and sending beacons to user-provided hosts
+    script-src: |
+        *;
+    img-src: |
+        *;
+    connect-src: |
+        *;
+summary: |
+    # Overview
+
+    Matomo (formerly Piwik) is a powerful open‑source web analytics platform. This integration lets you track visits to your published GitBook spaces directly in your Matomo instance (cloud or self‑hosted).
+
+    # How it works
+
+    The integration injects a lightweight tracking script that respects GitBook's cookie consent. When consent is granted, it sends pageview events to your configured Matomo server using the Matomo Tracking API. Single‑page navigation within GitBook is tracked automatically.
+
+    # Configure
+
+    Install the integration on the GitBook space(s) you want to track, then provide your Matomo server URL and Site ID.
+externalLinks:
+    - label: Matomo developer docs
+      url: https://developer.matomo.org/integration
+configurations:
+    site:
+        properties:
+            server_url:
+                type: string
+                title: Matomo Server URL
+                description: |
+                    Your Matomo server base URL. Examples: https://your-site.matomo.cloud or https://matomo.example.com
+            site_id:
+                type: string
+                title: Site ID
+                description: The numeric site ID configured in your Matomo instance
+            load_js_tracker:
+                type: boolean
+                title: Load Matomo JS tracker
+                description: |
+                    When enabled, loads matomo.js for first‑party cookies and richer tracking.
+                default: true
+            track_referrer:
+                type: boolean
+                title: Track Referrer
+                description: |
+                    Include document.referrer for pageviews/events (recommended)
+                default: true
+            track_outbound_clicks:
+                type: boolean
+                title: Track outbound link clicks
+                description: |
+                    Record clicks on links pointing to external domains
+                default: true
+            click_selectors:
+                type: string
+                title: CSS selectors to track
+                description: |
+                    Comma‑separated CSS selectors to track clicks as events. Example: a[href*="try"],button.book-demo
+                default: ''
+            goal_mappings_json:
+                type: string
+                title: Goal mappings (JSON)
+                description: |
+                    Optional JSON object mapping CSS selectors to Matomo Goal IDs.
+                default: ''
+            user_id_cookie:
+                type: string
+                title: User ID cookie name
+                description: |
+                    Optional cookie name to read and set as Matomo user ID (for retention/cohort analysis)
+                default: ''
+        required:
+            - server_url
+            - site_id
+target: site

integrations/matomo/global.d.ts

@@ -0,0 +1,12 @@
+declare module '*.raw.js' {
+    const content: string;
+    export default content;
+}
+
+// Allow local typechecking without installed workspace deps
+declare module '@gitbook/runtime' {
+    export type FetchPublishScriptEventCallback = any;
+    export type RuntimeContext<T> = any;
+    export type RuntimeEnvironment<A, B> = any;
+    export function createIntegration<T>(...args: any[]): any;
+}

integrations/matomo/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "@gitbook/integration-matomo",
+    "version": "0.1.0",
+    "private": true,
+    "dependencies": {
+        "@gitbook/api": "*",
+        "@gitbook/runtime": "*"
+    },
+    "devDependencies": {
+        "@gitbook/cli": "workspace:*",
+        "@gitbook/tsconfig": "workspace:*"
+    },
+    "scripts": {
+        "typecheck": "tsc --noEmit",
+        "publish-integrations-staging": "gitbook publish .",
+        "check": "gitbook check",
+        "publish-integrations": "gitbook publish ."
+    }
+}

integrations/matomo/src/index.ts

@@ -0,0 +1,58 @@
+import {
+    createIntegration,
+    FetchPublishScriptEventCallback,
+    RuntimeContext,
+    RuntimeEnvironment,
+} from '@gitbook/runtime';
+
+import matomoScript from './matomoScript.raw.js';
+
+type MatomoRuntimeContext = RuntimeContext<
+    RuntimeEnvironment<
+        {},
+        {
+            server_url?: string;
+            site_id?: string;
+            load_js_tracker?: boolean;
+            track_referrer?: boolean;
+            track_outbound_clicks?: boolean;
+            click_selectors?: string;
+            goal_mappings_json?: string;
+            user_id_cookie?: string;
+        }
+    >
+>;
+
+export const handleFetchEvent: FetchPublishScriptEventCallback = async (
+    event: any,
+    { environment }: MatomoRuntimeContext,
+) => {
+    const cfg = environment.siteInstallation?.configuration || {};
+    const serverUrl = cfg.server_url;
+    const siteId = cfg.site_id;
+
+    if (!serverUrl || !siteId) {
+        return;
+    }
+
+    const js = (matomoScript as string)
+        .replace('<MATOMO_SERVER_URL>', serverUrl.replace(/\/$/, ''))
+        .replace('<MATOMO_SITE_ID>', String(siteId))
+        .replace('<LOAD_JS_TRACKER>', String(cfg.load_js_tracker ?? true))
+        .replace('<TRACK_REFERRER>', String(cfg.track_referrer ?? true))
+        .replace('<TRACK_OUTBOUND>', String(cfg.track_outbound_clicks ?? true))
+        .replace('<CLICK_SELECTORS>', String(cfg.click_selectors ?? ''))
+        .replace('<GOAL_MAPPINGS_JSON>', String(cfg.goal_mappings_json ?? ''))
+        .replace('<USER_ID_COOKIE>', String(cfg.user_id_cookie ?? ''));
+
+    return new Response(js, {
+        headers: {
+            'Content-Type': 'application/javascript',
+            'Cache-Control': 'max-age=604800',
+        },
+    });
+};
+
+export default createIntegration<MatomoRuntimeContext>({
+    fetch_published_script: handleFetchEvent,
+});