@kntnt/engagement-metrics-gtag 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-gtag
+
+Google Analytics 4 (gtag.js) add-on for [`@kntnt/engagement-metrics`](https://www.npmjs.com/package/@kntnt/engagement-metrics). Sends reading and scanning progress events to GA4 at configurable thresholds.
+
+## Installation
+
+```bash
+npm install @kntnt/engagement-metrics @kntnt/engagement-metrics-gtag
+```
+
+## Usage
+
+### ESM (bundler)
+
+```js
+import { createMeasurer } from '@kntnt/engagement-metrics'
+import { registerGtag } from '@kntnt/engagement-metrics-gtag'
+
+const measurer = createMeasurer({ selector: 'article p' })
+registerGtag(measurer, {
+  readingThresholds: [10, 25, 50, 75, 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-gtag/dist/kntnt-engagement-metrics-gtag.min.js"></script>
+<script>
+  KntntEngagementMetrics.measurer = KntntEngagementMetrics.start({ selector: 'article p' })
+  KntntEngagementMetrics.gtag.register()
+</script>
+```
+
+## Documentation
+
+See the [main repository](https://github.com/Kntnt/kntnt-engagement-metrics) for full documentation, including how to register custom dimensions in GA4 and view engagement data in your reports.
+
+## 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,69 @@
+// src/listener.ts
+class GtagListener {
+  #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.#sendEvent(this.#config.readingEventName, {
+          percentage: threshold,
+          reading_time: Math.round(metrics.readingTime),
+          reading_ratio: Math.round(metrics.readingRatio * 100)
+        });
+      }
+    }
+  }
+  #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.#sendEvent(this.#config.scanningEventName, {
+          percentage: threshold,
+          scanning_depth: Math.round(metrics.scanningDepth),
+          scanning_ratio: Math.round(metrics.scanningRatio * 100)
+        });
+      }
+    }
+  }
+  #sendEvent(eventName, params) {
+    try {
+      const gtag = window.gtag;
+      if (typeof gtag === "function") {
+        gtag("event", eventName, params);
+      } else {
+        console.warn("[kntnt-engagement-metrics-gtag] gtag function not found");
+      }
+    } catch (e) {
+      console.warn("[kntnt-engagement-metrics-gtag] Failed to send event:", e);
+    }
+  }
+}
+
+// src/index.ts
+var DEFAULTS = {
+  readingEventName: "engagement_reading",
+  scanningEventName: "engagement_scanning",
+  readingThresholds: [10, 25, 50, 75, 90, 100],
+  scanningThresholds: [25, 50, 75, 100],
+  trackerMode: "auto"
+};
+function registerGtag(measurer, config) {
+  const mergedConfig = { ...DEFAULTS, ...config };
+  const listener = new GtagListener(mergedConfig);
+  measurer.addListener(listener);
+}
+export {
+  registerGtag,
+  GtagListener
+};

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

@@ -0,0 +1 @@
+class C{#w;#k=new Set;#y=new Set;constructor(w){this.#w=w}update(w){this.#I(w),this.#K(w)}#I(w){let y=w.readingRatio*100;for(let k of this.#w.readingThresholds)if(y>=k&&!this.#k.has(k))this.#k.add(k),this.#C(this.#w.readingEventName,{percentage:k,reading_time:Math.round(w.readingTime),reading_ratio:Math.round(w.readingRatio*100)})}#K(w){let y=w.scanningRatio*100;for(let k of this.#w.scanningThresholds)if(y>=k&&!this.#y.has(k))this.#y.add(k),this.#C(this.#w.scanningEventName,{percentage:k,scanning_depth:Math.round(w.scanningDepth),scanning_ratio:Math.round(w.scanningRatio*100)})}#C(w,y){try{let k=window.gtag;if(typeof k==="function")k("event",w,y);else console.warn("[kntnt-engagement-metrics-gtag] gtag function not found")}catch(k){console.warn("[kntnt-engagement-metrics-gtag] Failed to send event:",k)}}}var E={readingEventName:"engagement_reading",scanningEventName:"engagement_scanning",readingThresholds:[10,25,50,75,90,100],scanningThresholds:[25,50,75,100],trackerMode:"auto"};function K(w,y){let k={...E,...y},b=new C(k);w.addListener(b)}var I=window.KntntEngagementMetrics;if(I)if(I.gtag)console.warn("[kntnt-engagement-metrics-gtag] Already loaded, skipping");else{let w=window.kntntEngagementMetricsGtagConfig??{};I.gtag={register:(y)=>K(I.measurer,y??w)}}else console.warn("[kntnt-engagement-metrics-gtag] Core library not loaded");

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kntnt/engagement-metrics-gtag",
+  "version": "1.0.0",
+  "description": "Google Analytics 4 (gtag.js) 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/gtag"
+  },
+  "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-gtag.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-gtag.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",
+    "google-analytics",
+    "gtag",
+    "ga4"
+  ]
+}