@kntnt/engagement-metrics-matomo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kntnt Sweden AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @kntnt/engagement-metrics-matomo
+
+Matomo Analytics add-on for [`@kntnt/engagement-metrics`](https://www.npmjs.com/package/@kntnt/engagement-metrics). Sends reading and scanning progress events to Matomo at configurable thresholds.
+
+## Installation
+
+```bash
+npm install @kntnt/engagement-metrics @kntnt/engagement-metrics-matomo
+```
+
+## Usage
+
+### ESM (bundler)
+
+```js
+import { createMeasurer } from '@kntnt/engagement-metrics'
+import { registerMatomo } from '@kntnt/engagement-metrics-matomo'
+
+const measurer = createMeasurer({ selector: 'article p' })
+registerMatomo(measurer, {
+  readingThresholds: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
+  scanningThresholds: [25, 50, 75, 100],
+})
+measurer.start()
+```
+
+### IIFE (script tag)
+
+```html
+<script src="https://unpkg.com/@kntnt/engagement-metrics/dist/kntnt-engagement-metrics.min.js"></script>
+<script src="https://unpkg.com/@kntnt/engagement-metrics-matomo/dist/kntnt-engagement-metrics-matomo.min.js"></script>
+<script>
+  KntntEngagementMetrics.measurer = KntntEngagementMetrics.start({ selector: 'article p' })
+  KntntEngagementMetrics.matomo.register()
+</script>
+```
+
+## Documentation
+
+See the [main repository](https://github.com/Kntnt/kntnt-engagement-metrics) for full documentation, including how to set up Matomo custom dimensions and view engagement data in your Matomo dashboard.
+
+## License
+
+[MIT](https://github.com/Kntnt/kntnt-engagement-metrics/blob/main/LICENSE) — Copyright (c) 2026 Kntnt Sweden AB

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/listener.ts
+class MatomoListener {
+  #config;
+  #reportedReadingThresholds = new Set;
+  #reportedScanningThresholds = new Set;
+  constructor(config) {
+    this.#config = config;
+  }
+  update(metrics) {
+    this.#checkReadingThresholds(metrics);
+    this.#checkScanningThresholds(metrics);
+  }
+  #checkReadingThresholds(metrics) {
+    const readingPct = metrics.readingRatio * 100;
+    for (const threshold of this.#config.readingThresholds) {
+      if (readingPct >= threshold && !this.#reportedReadingThresholds.has(threshold)) {
+        this.#reportedReadingThresholds.add(threshold);
+        this.#trackEvent("Engagement", "Reading", `${threshold}%`, Math.round(metrics.readingTime));
+      }
+    }
+  }
+  #checkScanningThresholds(metrics) {
+    const scanningPct = metrics.scanningRatio * 100;
+    for (const threshold of this.#config.scanningThresholds) {
+      if (scanningPct >= threshold && !this.#reportedScanningThresholds.has(threshold)) {
+        this.#reportedScanningThresholds.add(threshold);
+        this.#trackEvent("Engagement", "Scanning", `${threshold}%`, Math.round(metrics.scanningDepth));
+      }
+    }
+  }
+  #trackEvent(category, action, name, value) {
+    try {
+      const _paq = window._paq;
+      if (_paq) {
+        _paq.push(["trackEvent", category, action, name, value]);
+      } else {
+        console.warn("[kntnt-engagement-metrics-matomo] Matomo tracker (_paq) not found");
+      }
+    } catch (e) {
+      console.warn("[kntnt-engagement-metrics-matomo] Failed to send event:", e);
+    }
+  }
+}
+
+// src/index.ts
+var DEFAULTS = {
+  bounceThreshold: 0.1,
+  readingThresholds: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
+  scanningThresholds: [25, 50, 75, 100],
+  trackerMode: "auto"
+};
+function registerMatomo(measurer, config) {
+  const mergedConfig = { ...DEFAULTS, ...config };
+  const listener = new MatomoListener(mergedConfig);
+  measurer.addListener(listener);
+}
+export {
+  registerMatomo,
+  MatomoListener
+};

package/dist/kntnt-engagement-metrics-matomo.min.js

@@ -0,0 +1 @@
+class y{#w;#n=new Set;#C=new Set;constructor(w){this.#w=w}update(w){this.#y(w),this.#I(w)}#y(w){let C=w.readingRatio*100;for(let n of this.#w.readingThresholds)if(C>=n&&!this.#n.has(n))this.#n.add(n),this.#k("Engagement","Reading",`${n}%`,Math.round(w.readingTime))}#I(w){let C=w.scanningRatio*100;for(let n of this.#w.scanningThresholds)if(C>=n&&!this.#C.has(n))this.#C.add(n),this.#k("Engagement","Scanning",`${n}%`,Math.round(w.scanningDepth))}#k(w,C,n,K){try{let k=window._paq;if(k)k.push(["trackEvent",w,C,n,K]);else console.warn("[kntnt-engagement-metrics-matomo] Matomo tracker (_paq) not found")}catch(k){console.warn("[kntnt-engagement-metrics-matomo] Failed to send event:",k)}}}var E={bounceThreshold:0.1,readingThresholds:[10,20,30,40,50,60,70,80,90,100],scanningThresholds:[25,50,75,100],trackerMode:"auto"};function b(w,C){let n={...E,...C},K=new y(n);w.addListener(K)}var I=window.KntntEngagementMetrics;if(I)if(I.matomo)console.warn("[kntnt-engagement-metrics-matomo] Already loaded, skipping");else{let w=window.kntntEngagementMetricsMatomoConfig??{};I.matomo={register:(C)=>b(I.measurer,C??w)}}else console.warn("[kntnt-engagement-metrics-matomo] Core library not loaded");

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kntnt/engagement-metrics-matomo",
+  "version": "1.0.0",
+  "description": "Matomo Analytics add-on for @kntnt/engagement-metrics.",
+  "license": "MIT",
+  "author": "Thomas Barregren",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kntnt/kntnt-engagement-metrics.git",
+    "directory": "packages/matomo"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./iife": {
+      "default": "./dist/kntnt-engagement-metrics-matomo.min.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target browser --format esm && bun build src/iife.ts --outfile dist/kntnt-engagement-metrics-matomo.min.js --target browser --minify",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@kntnt/engagement-metrics": ">=1.0.0"
+  },
+  "keywords": [
+    "engagement",
+    "metrics",
+    "matomo",
+    "analytics"
+  ]
+}