@faststats/web 0.2.13 → 0.2.14

package/src/replay.ts

@@ -7,23 +7,28 @@ import { record } from "rrweb";
 import type { recordOptions } from "rrweb/typings/types";
 import type { SlimDOMOptions } from "rrweb-snapshot";
 import { normalizeAnalyticsBaseUrl, URLS } from "./utils/api-urls";
+import { getAnonymousId } from "./utils/identifiers";
+import { sendData } from "./utils/send-data";
 import {
-	getAnonymousId,
-	getOrCreateSessionId,
+	createId,
+	getSessionContext,
 	getSessionStart,
-} from "./utils/identifiers";
-import { sendData } from "./utils/send-data";
+	onSessionRotated,
+	type SessionContext,
+	touchActivity,
+} from "./utils/session-manager";
 import { normalizeSamplingPercentage } from "./utils/types";
 
-const RRWEB_SEQUENTIAL_ID_KEY = "_faststatsSeqId";
 const MAX_TIMEOUT_MS = 2_147_483_647;
 const DEFAULT_MAX_QUEUE_SIZE_BYTES = 2 * 1024 * 1024;
+const VIEW_META_EVENT_TYPE = 5;
 
 export interface ReplayTrackerOptions {
 	siteKey: string;
 	baseUrl?: string;
 	debug?: boolean;
 	compress?: boolean;
+	cookieless?: boolean;
 	samplingPercentage?: number;
 	flushInterval?: number;
 	maxEvents?: number;
@@ -45,12 +50,16 @@ export interface ReplayTrackerOptions {
 
 type ReplayBatch = {
 	token: string;
-	sessionId: string | undefined;
+	sessionId: string;
+	windowId: string;
+	viewId: string;
+	sessionStart: number;
 	identifier?: string;
 	batchId: string;
 	sequence: number;
 	timestamp: number;
 	url: string;
+	isFinal?: boolean;
 	events: eventWithTime[];
 };
 
@@ -62,17 +71,53 @@ const defaultSampling: recordOptions<eventWithTime>["sampling"] = {
 	input: "last",
 };
 
-const defaultSlimDOMOptions: SlimDOMOptions = {
-	script: true,
-	comment: true,
-	headFavicon: true,
-	headWhitespace: true,
-	headMetaDescKeywords: true,
-	headMetaSocial: true,
-	headMetaRobots: true,
-	headMetaHttpEquiv: true,
-	headMetaAuthorship: true,
-};
+function replaySampledKey(siteKey: string): string {
+	return `faststats_replay_sampled_${siteKey}`;
+}
+
+function hashSessionId(sessionId: string): number {
+	let hash = 0;
+	for (let i = 0; i < sessionId.length; i++) {
+		hash = (hash << 5) - hash + sessionId.charCodeAt(i);
+		hash |= 0;
+	}
+	return Math.abs(hash);
+}
+
+function resolveReplaySampled(
+	siteKey: string,
+	samplingPercentage: number,
+	cookieless: boolean,
+): boolean {
+	const pct = normalizeSamplingPercentage(samplingPercentage);
+	if (pct >= 100) return true;
+	if (pct <= 0) return false;
+
+	const sessionId = getSessionContext(siteKey, cookieless).sessionId;
+	const storageKey = replaySampledKey(siteKey);
+	const storedKey = `${sessionId}:${pct}`;
+
+	try {
+		const session = sessionStorage;
+		if (session) {
+			const stored = session.getItem(storageKey);
+			if (stored === storedKey) return true;
+			if (stored?.startsWith(`${sessionId}:`)) return false;
+		}
+	} catch {}
+
+	const bucket = hashSessionId(sessionId) % 100;
+	const sampled = bucket < pct;
+
+	try {
+		sessionStorage?.setItem(
+			storageKey,
+			sampled ? storedKey : `${sessionId}:out`,
+		);
+	} catch {}
+
+	return sampled;
+}
 
 export default class ReplayTracker {
 	private readonly endpoint: string;
@@ -84,7 +129,8 @@ export default class ReplayTracker {
 	private readonly pending: ReplayBatch[] = [];
 	private pendingSizeBytes = 0;
 
-	private sessionId: string | undefined;
+	private viewId = createId();
+	private readonly windowId = createId();
 	private started = false;
 	private startTime = 0;
 	private sequence = 0;
@@ -94,12 +140,19 @@ export default class ReplayTracker {
 	private minLengthFlushTask: ReturnType<typeof setTimeout> | null = null;
 	private stopRecording?: listenerHandler;
 	private sending = false;
+	private unsubscribeRotation?: () => void;
 
 	constructor(private readonly options: ReplayTrackerOptions) {
 		this.endpoint = `${normalizeAnalyticsBaseUrl(options.baseUrl)}${URLS.replay}`;
-		this.sampled =
-			Math.random() * 100 <
-			normalizeSamplingPercentage(options.samplingPercentage);
+		this.sampled = resolveReplaySampled(
+			options.siteKey,
+			options.samplingPercentage ?? 100,
+			options.cookieless ?? false,
+		);
+	}
+
+	private get cookieless(): boolean {
+		return this.options.cookieless ?? false;
 	}
 
 	private get debug(): boolean {
@@ -134,12 +187,20 @@ export default class ReplayTracker {
 		if (this.debug) console.log("[Replay]", ...args);
 	}
 
+	private sessionContext(): SessionContext {
+		return getSessionContext(this.options.siteKey, this.cookieless);
+	}
+
 	start(): void {
 		if (this.started || typeof window === "undefined" || !this.sampled) return;
 
 		this.started = true;
-		this.sessionId = getOrCreateSessionId();
-		this.startTime = getSessionStart();
+		this.viewId = createId();
+		this.startTime = getSessionStart(this.cookieless);
+
+		this.unsubscribeRotation = onSessionRotated((prev) => {
+			this.onSessionRotated(prev);
+		});
 
 		void this.beginRecording();
 
@@ -152,22 +213,31 @@ export default class ReplayTracker {
 		this.log("Recording started");
 	}
 
+	trackPageChange(url?: string): void {
+		if (!this.started) return;
+		const href = url ?? window.location.href;
+		this.viewId = createId();
+		const metaEvent = {
+			type: VIEW_META_EVENT_TYPE,
+			timestamp: Date.now(),
+			data: {
+				tag: "faststats:view",
+				payload: { href, viewId: this.viewId },
+			},
+		} as eventWithTime;
+		this.onEvent(metaEvent, false);
+	}
+
 	private async beginRecording(): Promise<void> {
 		const wantsConsole = this.options.recordConsole ?? true;
 
-		const [{ getRecordSequentialIdPlugin }, consolePluginModule] =
-			await Promise.all([
-				import("@rrweb/rrweb-plugin-sequential-id-record"),
-				wantsConsole
-					? import("@rrweb/rrweb-plugin-console-record")
-					: Promise.resolve(null),
-			]);
+		const consolePluginModule = wantsConsole
+			? await import("@rrweb/rrweb-plugin-console-record")
+			: null;
 
 		if (!this.started) return;
 
-		const plugins = [
-			getRecordSequentialIdPlugin({ key: RRWEB_SEQUENTIAL_ID_KEY }),
-		];
+		const plugins = [];
 		if (consolePluginModule) {
 			plugins.push(consolePluginModule.getRecordConsolePlugin());
 		}
@@ -175,7 +245,17 @@ export default class ReplayTracker {
 		this.stopRecording = record({
 			emit: this.onEvent,
 			sampling: this.options.sampling ?? defaultSampling,
-			slimDOMOptions: this.options.slimDOMOptions ?? defaultSlimDOMOptions,
+			slimDOMOptions: this.options.slimDOMOptions ?? {
+				script: true,
+				comment: true,
+				headFavicon: true,
+				headWhitespace: true,
+				headMetaDescKeywords: true,
+				headMetaSocial: true,
+				headMetaRobots: true,
+				headMetaHttpEquiv: true,
+				headMetaAuthorship: true,
+			},
 			maskAllInputs: this.options.maskAllInputs ?? true,
 			maskInputOptions: this.options.maskInputOptions ?? {
 				password: true,
@@ -196,6 +276,9 @@ export default class ReplayTracker {
 		if (!this.started) return;
 		this.started = false;
 
+		this.unsubscribeRotation?.();
+		this.unsubscribeRotation = undefined;
+
 		this.stopRecording?.();
 		this.stopRecording = undefined;
 
@@ -215,20 +298,37 @@ export default class ReplayTracker {
 
 		if (!this.hasReachedMinLength()) {
 			this.events.length = 0;
-			this.sessionId = undefined;
 			this.log(
 				`Session too short (${Date.now() - this.startTime}ms), discarding events`,
 			);
 			return;
 		}
 
-		void this.flush(true);
-		this.sessionId = undefined;
+		void this.flush(true, undefined, true);
 		this.log("Recording stopped");
 	}
 
-	getSessionId(): string | undefined {
-		return this.sessionId ?? getOrCreateSessionId();
+	getSessionId(): string {
+		return this.sessionContext().sessionId;
+	}
+
+	getWindowId(): string {
+		return this.sessionContext().windowId;
+	}
+
+	private onSessionRotated(prev: SessionContext): void {
+		if (!this.started) return;
+		if (this.events.length > 0) {
+			if (!this.hasReachedMinLength()) {
+				this.scheduleMinLengthFlush();
+			} else {
+				const batch = this.createBatch(this.events.splice(0), prev, true);
+				this.enqueueBatch(batch);
+			}
+		}
+		if (this.pending.length > 0) {
+			queueMicrotask(() => void this.flush(false));
+		}
 	}
 
 	private onEvent = (event: eventWithTime, isCheckout?: boolean): void => {
@@ -247,12 +347,12 @@ export default class ReplayTracker {
 	};
 
 	private onUnload = (): void => {
-		void this.flush(true);
+		void this.flush(true, undefined, true);
 	};
 
 	private onVisibilityChange = (): void => {
 		if (document.visibilityState === "hidden") {
-			void this.flush(true);
+			void this.flush(true, undefined, true);
 		}
 	};
 
@@ -298,28 +398,36 @@ export default class ReplayTracker {
 		}, timeoutMs);
 	}
 
-	private createBatch(events: eventWithTime[]): ReplayBatch {
-		const identifier = getAnonymousId();
+	private createBatch(
+		events: eventWithTime[],
+		context: SessionContext,
+		isFinal?: boolean,
+	): ReplayBatch {
+		const identifier = getAnonymousId(this.cookieless);
 		const sequence = this.sequence++;
 
 		return {
 			token: this.options.siteKey,
-			sessionId: this.getSessionId(),
+			sessionId: context.sessionId,
+			windowId: this.windowId,
+			viewId: this.viewId,
+			sessionStart: context.sessionStart,
 			...(identifier ? { identifier } : {}),
-			batchId: this.createBatchId(sequence),
+			batchId: this.createBatchId(context.sessionId, sequence),
 			sequence,
 			timestamp: Date.now(),
 			url: window.location.href,
+			...(isFinal ? { isFinal: true } : {}),
 			events,
 		};
 	}
 
-	private createBatchId(sequence: number): string {
+	private createBatchId(sessionId: string, sequence: number): string {
 		const random =
 			typeof crypto !== "undefined" && "randomUUID" in crypto
 				? crypto.randomUUID()
 				: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
-		return `${this.getSessionId() ?? "unknown"}-${sequence}-${random}`;
+		return `${sessionId}-${sequence}-${random}`;
 	}
 
 	private getBatchSizeBytes(batch: ReplayBatch): number {
@@ -392,14 +500,33 @@ export default class ReplayTracker {
 		}
 	}
 
-	private async flush(lowLatency: boolean): Promise<void> {
+	private async flush(
+		lowLatency: boolean,
+		contextOverride?: SessionContext,
+		isFinal?: boolean,
+	): Promise<void> {
 		if (this.sending) return;
 
+		const rotation = contextOverride ? null : touchActivity(this.cookieless);
+		if (rotation && this.events.length > 0) {
+			if (!this.hasReachedMinLength()) {
+				this.scheduleMinLengthFlush();
+			} else {
+				const batch = this.createBatch(
+					this.events.splice(0),
+					rotation.prev,
+					true,
+				);
+				this.enqueueBatch(batch);
+			}
+		}
+		const context = contextOverride ?? this.sessionContext();
+
 		if (this.events.length > 0) {
 			if (!this.hasReachedMinLength()) {
 				this.scheduleMinLengthFlush();
 			} else {
-				const batch = this.createBatch(this.events.splice(0));
+				const batch = this.createBatch(this.events.splice(0), context, isFinal);
 				this.enqueueBatch(batch);
 			}
 		}
@@ -461,7 +588,7 @@ export default class ReplayTracker {
 					? "application/octet-stream"
 					: "application/json",
 				debug: false,
-				useBeacon: false,
+				useBeacon: lowLatency,
 				keepalive: lowLatency,
 			}) ?? Promise.resolve(false)
 		);

package/src/utils/identifiers.ts

@@ -1,89 +1,47 @@
-const SESSION_TIMEOUT = 30 * 60 * 1000;
-const ANONYMOUS_ID_KEY = "faststats_anon_id";
-const SESSION_ID_KEY = "session_id";
-const SESSION_TIMESTAMP_KEY = "session_timestamp";
-const SESSION_START_KEY = "session_start";
+import { createId, isCookielessMode } from "./session-manager";
 
-let cookielessMode = false;
+const ANONYMOUS_ID_KEY = "faststats_anon_id";
 
-export function setCookielessMode(mode: boolean): void {
-	cookielessMode = mode;
+function getLocalStorage(): Storage | undefined {
+	try {
+		return globalThis.localStorage;
+	} catch {
+		return undefined;
+	}
 }
 
 export function getAnonymousId(cookieless?: boolean): string {
-	const useCookieless = cookieless ?? cookielessMode;
-	if (useCookieless) return "";
+	if (cookieless ?? isCookielessMode()) return "";
 	return getOrCreateAnonymousId();
 }
 
 export function getOrCreateAnonymousId(): string {
-	if (!localStorage) return "";
-	const existingId = localStorage.getItem(ANONYMOUS_ID_KEY);
-	if (existingId) return existingId;
+	const storage = getLocalStorage();
+	if (!storage) return "";
+	try {
+		const existingId = storage.getItem(ANONYMOUS_ID_KEY);
+		if (existingId) return existingId;
+	} catch {
+		return "";
+	}
 
-	const newId = crypto.randomUUID();
-	localStorage.setItem(ANONYMOUS_ID_KEY, newId);
+	const newId = createId();
+	try {
+		storage.setItem(ANONYMOUS_ID_KEY, newId);
+	} catch {
+		return "";
+	}
 	return newId;
 }
 
 export function resetAnonymousId(cookieless?: boolean): string {
 	if (cookieless) return "";
-
-	if (!localStorage) return "";
-
-	localStorage.removeItem(ANONYMOUS_ID_KEY);
-	return getOrCreateAnonymousId();
-}
-
-export function getOrCreateSessionId(): string {
-	if (!sessionStorage) return "";
-
-	const existingId = sessionStorage.getItem(SESSION_ID_KEY);
-	const sessionTimestamp = sessionStorage.getItem(SESSION_TIMESTAMP_KEY);
-
-	if (existingId && sessionTimestamp) {
-		const sessionAge = Date.now() - Number.parseInt(sessionTimestamp, 10);
-		if (sessionAge < SESSION_TIMEOUT) {
-			sessionStorage.setItem(SESSION_TIMESTAMP_KEY, Date.now().toString());
-			return existingId;
-		}
-		clearSession(sessionStorage);
+	try {
+		const storage = getLocalStorage();
+		if (!storage) return "";
+		storage.removeItem(ANONYMOUS_ID_KEY);
+	} catch {
+		return "";
 	}
-
-	const now = Date.now().toString();
-	const newId = crypto.randomUUID();
-	sessionStorage.setItem(SESSION_ID_KEY, newId);
-	sessionStorage.setItem(SESSION_TIMESTAMP_KEY, now);
-	sessionStorage.setItem(SESSION_START_KEY, now);
-	return newId;
-}
-
-export function resetSessionId(): string {
-	if (!sessionStorage) return "";
-
-	clearSession(sessionStorage);
-	return getOrCreateSessionId();
-}
-
-export function refreshSessionTimestamp(): void {
-	if (!sessionStorage) return;
-
-	if (sessionStorage.getItem(SESSION_ID_KEY)) {
-		sessionStorage.setItem(SESSION_TIMESTAMP_KEY, Date.now().toString());
-	}
-}
-
-export function getSessionStart(): number {
-	if (!sessionStorage) return Date.now();
-
-	const start = sessionStorage.getItem(SESSION_START_KEY);
-	if (start) return Number.parseInt(start, 10);
-	const ts = sessionStorage.getItem(SESSION_TIMESTAMP_KEY);
-	return ts ? Number.parseInt(ts, 10) : Date.now();
-}
-
-function clearSession(storage: Storage): void {
-	storage.removeItem(SESSION_ID_KEY);
-	storage.removeItem(SESSION_TIMESTAMP_KEY);
-	storage.removeItem(SESSION_START_KEY);
+	return getOrCreateAnonymousId();
 }