@faststats/web 0.12.1 → 0.13.0

package/README.md

@@ -48,8 +48,8 @@ Consent remains client-local: use `"anonymous"` for cookieless collection,
 
 ### Visit duration
 
-`page_leave.properties.time_on_page` is the accumulated time in milliseconds
-that the page was visible and its document had focus. It pauses when the tab is
+`properties.time_on_page` on `page_ping` and `page_leave` is the accumulated
+time in milliseconds that the page was visible and its document had focus. It pauses when the tab is
 hidden, the window loses focus, or the page enters the back-forward cache, and
 resets on navigation, logout, or session rotation. A monotonic clock keeps
 system-clock changes from affecting this duration. It also pauses after 60
@@ -60,11 +60,24 @@ the device spent asleep or the tab frozen is not counted.
 Pageviews wait until the page becomes visible. Pages replaced or closed before
 being shown do not emit pageviews or page-leave events.
 
-The SDK sends cumulative `page_leave` checkpoints every 15 seconds while active
-and when activity pauses or the visit ends. Unchanged checkpoints are suppressed.
-Pageviews and their checkpoints share `properties.visit_id`; consumers should use
-the maximum `time_on_page` per visit, never sum its checkpoints. The existing
-session-duration and bounce-rate queries already use maximum values.
+The SDK sends a cumulative `page_ping` when activity pauses and periodically
+while active: after 15 and 45 seconds, then every 60 seconds. A ping that adds no
+time is suppressed. A visit ends with
+exactly one `page_leave`, on navigation, a terminal `pagehide`, logout, a consent
+change, or session rotation. A page the browser discards without notice never
+sends one, so its last ping holds its duration. A pageview, its pings, and its
+leave share `properties.visit_id`; consumers should use the maximum
+`time_on_page` per visit across both events, never sum them.
+
+Before 0.13 the pings were sent as `page_leave` every 15 seconds. The collector
+and dashboards read both shapes; deploy them before releasing this SDK.
+
+### Default context
+
+Every event carries `timezone` (IANA name), `language`, and `screen`
+(`1920x1080`, CSS pixels) beside the page context, separate from its properties.
+Custom events and outbound links also carry the `visit_id` of the page view they
+happened during.
 
 Each visit retains its original identity, session, and page metadata. A session
 or identity change starts a new visit, even on the same route. Both persistent
@@ -76,7 +89,7 @@ session, so it is separate from active time on the page. An idle visitor stops
 extending the session, which then expires after 30 minutes like any other.
 
 Delivery is best effort: a sudden process kill or network failure can lose time
-since the last delivered checkpoint. The collector must accept successive events
+since the last delivered ping. The collector must accept successive events
 for the same visitor and URL; deploy the removal of its five-second debounce
 before releasing this SDK.
 

package/dist/chunks/{send-data-gBIF6DTb.js → send-data-C76HbZ8d.js}

@@ -31,6 +31,19 @@ function getReferrer() {
 	} catch {}
 	return sanitizeUrl(raw);
 }
+/** Visitor environment sent with every event; unavailable values are omitted. */
+function getClientContext() {
+	let timezone;
+	try {
+		timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+	} catch {}
+	const { width, height } = globalThis.screen ?? {};
+	return {
+		timezone,
+		language: globalThis.navigator?.language,
+		screen: width && height ? `${width}x${height}` : void 0
+	};
+}
 function getPageContext(includeHash = false) {
 	const hash = includeHash ? location.hash : "";
 	const ctx = {
@@ -80,4 +93,4 @@ async function sendData(options) {
 	}
 }
 //#endregion
-export { sanitizeUrl as a, resolveBaseUrl as i, URLS as n, getPageContext as r, sendData as t };
+export { resolveBaseUrl as a, getPageContext as i, URLS as n, sanitizeUrl as o, getClientContext as r, sendData as t };

package/dist/error.js

@@ -1,9 +1,9 @@
-import { i as resolveBaseUrl, n as URLS, r as getPageContext, t as sendData } from "./chunks/send-data-gBIF6DTb.js";
+import { a as resolveBaseUrl, i as getPageContext, n as URLS, t as sendData } from "./chunks/send-data-C76HbZ8d.js";
 import { n as getSessionContext } from "./chunks/session-manager-DUpF3mi3.js";
 import { t as getAnonymousId } from "./chunks/identifiers-DOtve3E5.js";
 //#region src/error.ts
 const SDK_NAME = "@faststats/web";
-const SDK_VERSION = "0.12.1";
+const SDK_VERSION = "0.13.0";
 function errorTracking(options = {}) {
 	return {
 		name: "error-tracking",

package/dist/index.d.ts

@@ -69,6 +69,10 @@ export declare class WebAnalytics {
   private readonly onActivity;
   private isIdle;
   private leavePage;
+  /**
+   * Reports the visit's running totals: as a `page_ping` while it may still
+   * continue, and as its single `page_leave` once it has ended.
+   */
   private checkpoint;
   private pauseVisit;
   private resumeVisit;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as sanitizeUrl, i as resolveBaseUrl, n as URLS, r as getPageContext, t as sendData } from "./chunks/send-data-gBIF6DTb.js";
+import { a as resolveBaseUrl, i as getPageContext, n as URLS, o as sanitizeUrl, r as getClientContext, t as sendData } from "./chunks/send-data-C76HbZ8d.js";
 import { a as touchActivity, i as resetSession, n as getSessionContext, t as createId } from "./chunks/session-manager-DUpF3mi3.js";
 import { n as resetAnonymousId, t as getAnonymousId } from "./chunks/identifiers-DOtve3E5.js";
 //#region src/extensions.ts
@@ -125,6 +125,7 @@ function observeHistory(listener) {
 }
 const RESERVED_EVENTS = /* @__PURE__ */ new Set([
 	"pageview",
+	"page_ping",
 	"page_leave",
 	"error",
 	"outbound_link"
@@ -190,7 +191,9 @@ var WebAnalytics = class {
 			duration: 0,
 			startedAt: null,
 			checkedAt: Date.now(),
-			reportedDuration: -1
+			activeAt: Date.now(),
+			reportedDuration: -1,
+			beats: 0
 		};
 		this.send("pageview", {
 			...properties,
@@ -291,6 +294,7 @@ var WebAnalytics = class {
 	}
 	context(session = this.session()) {
 		return {
+			...getClientContext(),
 			...getPageContext(this.options.trackHash),
 			userId: this.getAnonymousId() || void 0,
 			sessionId: session.sessionId,
@@ -355,12 +359,12 @@ var WebAnalytics = class {
 	onPageHide = (event) => {
 		if (!this.canTrack()) return;
 		const persisted = event.persisted;
-		this.pauseVisit();
+		if (persisted) this.pauseVisit();
+		else this.leavePage();
 		this.extensions?.emit("pageHide", {
 			persisted,
 			terminal: !persisted
 		});
-		if (!persisted) this.leavePage();
 	};
 	onPageShow = (event) => {
 		if (!this.canTrack()) return;
@@ -383,36 +387,40 @@ var WebAnalytics = class {
 		return !playing;
 	}
 	leavePage() {
-		this.pauseVisit();
+		this.pauseVisit(true);
 		this.visit = null;
 	}
-	checkpoint() {
+	/**
+	* Reports the visit's running totals: as a `page_ping` while it may still
+	* continue, and as its single `page_leave` once it has ended.
+	*/
+	checkpoint(leaving = false, periodic = false) {
 		const visit = this.visit;
 		if (!visit || !this.isActive()) return;
-		let activeAt = visit.checkedAt;
 		if (visit.startedAt !== null) {
 			const now = performance.now();
 			if (now - visit.startedAt < IDLE_MS) {
 				const active = Math.min(now, this.lastInputAt + IDLE_MS) - visit.startedAt;
 				visit.duration += active;
-				activeAt += active;
+				visit.activeAt = visit.checkedAt + active;
 			}
 			visit.startedAt = now;
 			visit.checkedAt = Date.now();
 		}
+		if (periodic && ++visit.beats !== 1 && visit.beats % 4 !== 3) return;
 		const duration = Math.round(visit.duration);
-		if (duration === visit.reportedDuration) return;
+		if (!leaving && duration === visit.reportedDuration) return;
 		visit.reportedDuration = duration;
-		this.send("page_leave", {
+		this.send(leaving ? "page_leave" : "page_ping", {
 			visit_id: visit.id,
 			time_on_page: duration,
-			session_duration: Math.max(0, activeAt - visit.session.sessionStart)
+			session_duration: Math.max(0, visit.activeAt - visit.session.sessionStart)
 		}, visit.context);
 	}
-	pauseVisit() {
+	pauseVisit(leaving = false) {
 		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
 		this.heartbeatTimer = null;
-		this.checkpoint();
+		this.checkpoint(leaving);
 		if (this.visit) this.visit.startedAt = null;
 	}
 	resumeVisit() {
@@ -426,12 +434,15 @@ var WebAnalytics = class {
 			}
 			const visit = this.visit;
 			this.pageview({ trigger: "session" });
-			if (this.visit === visit) this.checkpoint();
+			if (this.visit === visit) this.checkpoint(false, true);
 		}, 15e3);
 	}
 	send(event, properties = {}, context) {
 		if (!this.isActive()) return;
-		context ??= this.context();
+		context ??= {
+			...this.context(),
+			visit_id: this.visit?.id
+		};
 		let data;
 		try {
 			data = JSON.stringify({

package/dist/replay.js

@@ -1,4 +1,4 @@
-import { a as sanitizeUrl, i as resolveBaseUrl, n as URLS, t as sendData } from "./chunks/send-data-gBIF6DTb.js";
+import { a as resolveBaseUrl, n as URLS, o as sanitizeUrl, t as sendData } from "./chunks/send-data-C76HbZ8d.js";
 import { a as touchActivity, c as setStorageItem, n as getSessionContext, o as getStorageItem, r as onSessionRotated, t as createId } from "./chunks/session-manager-DUpF3mi3.js";
 import { t as getAnonymousId } from "./chunks/identifiers-DOtve3E5.js";
 import { record } from "@rrweb/record";

package/dist/web-vitals.js

@@ -1,4 +1,4 @@
-import { a as sanitizeUrl, i as resolveBaseUrl, n as URLS, t as sendData } from "./chunks/send-data-gBIF6DTb.js";
+import { a as resolveBaseUrl, n as URLS, o as sanitizeUrl, t as sendData } from "./chunks/send-data-C76HbZ8d.js";
 import { n as getSessionContext, r as onSessionRotated } from "./chunks/session-manager-DUpF3mi3.js";
 import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals/attribution";
 //#region src/utils/web-vitals-collector.ts

package/package.json

@@ -42,7 +42,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"scripts": {
 		"build": "tsdown && bun run check-size",
 		"dev": "bun run build",