@faststats/web 0.0.1

package/src/analytics.ts

@@ -0,0 +1,544 @@
+import type { ReplayTrackerOptions } from "./replay";
+import {
+	getAnonymousId,
+	getOrCreateSessionId,
+	getSessionStart,
+	refreshSessionTimestamp,
+	resetAnonymousId,
+	resetSessionId,
+} from "./utils/identifiers";
+import {
+	normalizeSamplingPercentage,
+	type SendDataOptions,
+} from "./utils/types";
+
+export type { SendDataOptions };
+
+export function isTrackingDisabled(): boolean {
+	if (typeof localStorage === "undefined") return false;
+	const value = localStorage.getItem("disable-faststats");
+	return value === "true" || value === "1";
+}
+
+export async function sendData(options: SendDataOptions): Promise<boolean> {
+	const {
+		url,
+		data,
+		contentType = "application/json",
+		headers = {},
+		debug = false,
+		debugPrefix = "[Analytics]",
+	} = options;
+
+	const blob =
+		data instanceof Blob ? data : new Blob([data], { type: contentType });
+
+	if (navigator.sendBeacon?.(url, blob)) {
+		if (debug) {
+			console.log(`${debugPrefix} ✓ Sent via beacon`);
+		}
+		return true;
+	}
+
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			body: data,
+			headers: {
+				"Content-Type": contentType,
+				...headers,
+			},
+			keepalive: true,
+		});
+		const success = response.ok;
+		if (debug) {
+			if (success) {
+				console.log(`${debugPrefix} ✓ Sent via fetch`);
+			} else {
+				console.warn(`${debugPrefix} ✗ Failed: ${response.status}`);
+			}
+		}
+		return success;
+	} catch {
+		if (debug) {
+			console.warn(`${debugPrefix} ✗ Failed to send`);
+		}
+		return false;
+	}
+}
+
+function getLinkEl(el: Node | null): HTMLAnchorElement | null {
+	while (
+		el &&
+		!((el as Element).tagName === "A" && (el as HTMLAnchorElement).href)
+	) {
+		el = el.parentNode;
+	}
+	return el as HTMLAnchorElement | null;
+}
+
+function getUTM(): Record<string, string> {
+	const params: Record<string, string> = {};
+	if (!location.search) return params;
+	const sp = new URLSearchParams(location.search);
+	for (const k of [
+		"utm_source",
+		"utm_medium",
+		"utm_campaign",
+		"utm_term",
+		"utm_content",
+	]) {
+		const v = sp.get(k);
+		if (v) params[k] = v;
+	}
+	return params;
+}
+
+type Dict = Record<string, unknown>;
+
+interface SamplingOptions {
+	percentage?: number;
+}
+
+interface ErrorTrackingConfig {
+	enabled?: boolean;
+}
+
+interface WebVitalsConfig {
+	enabled?: boolean;
+	sampling?: SamplingOptions;
+}
+
+interface SessionReplayConfig {
+	enabled?: boolean;
+	sampling?: SamplingOptions;
+}
+
+export type ConsentMode = "pending" | "granted" | "denied";
+
+interface ConsentConfig {
+	mode?: ConsentMode;
+	cookielessWhilePending?: boolean;
+}
+
+export interface IdentifyOptions {
+	name?: string;
+	phone?: string;
+	avatarUrl?: string;
+	traits?: Record<string, unknown>;
+}
+
+export interface WebAnalyticsOptions {
+	siteKey: string;
+	endpoint?: string;
+	baseUrl?: string;
+	debug?: boolean;
+	autoTrack?: boolean;
+	trackHash?: boolean;
+	trackErrors?: boolean;
+	trackWebVitals?: boolean;
+	trackReplay?: boolean;
+	cookieless?: boolean;
+	consent?: ConsentConfig;
+	errorTracking?: ErrorTrackingConfig;
+	webVitals?: WebVitalsConfig;
+	sessionReplays?: SessionReplayConfig;
+	replayOptions?: Partial<ReplayTrackerOptions>;
+}
+
+declare global {
+	interface Window {
+		WebAnalytics: typeof WebAnalytics;
+		__FA_getAnonymousId?: () => string;
+		__FA_getSessionId?: () => string;
+		__FA_sendData?: (options: SendDataOptions) => Promise<boolean>;
+		__FA_identify?: (
+			externalId: string,
+			email: string,
+			options?: IdentifyOptions,
+		) => void;
+		__FA_logout?: (resetAnonymousIdentity?: boolean) => void;
+		__FA_setConsentMode?: (mode: ConsentMode) => void;
+		__FA_optIn?: () => void;
+		__FA_optOut?: () => void;
+		__FA_isTrackingDisabled?: () => boolean;
+		__FA_webAnalyticsInstance?: WebAnalytics;
+	}
+}
+
+export class WebAnalytics {
+	private readonly endpoint: string;
+	private readonly debug: boolean;
+	private readonly baseUrl: string;
+	private started = false;
+	private pageKey = "";
+	private navTimer: ReturnType<typeof setTimeout> | null = null;
+	private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+	private scrollDepth = 0;
+	private pageEntryTime = 0;
+	private pagePath = "";
+	private pageUrl = "";
+	private pageHash = "";
+	private hasLeftCurrentPage = false;
+	private scrollHandler: (() => void) | null = null;
+	private consentMode: ConsentMode;
+	private readonly cookielessWhilePending: boolean;
+
+	constructor(private readonly options: WebAnalyticsOptions) {
+		this.endpoint = options.endpoint ?? "https://metrics.faststats.dev/v1/web";
+		this.debug = options.debug ?? false;
+		this.consentMode = options.consent?.mode ?? "granted";
+		this.cookielessWhilePending =
+			options.consent?.cookielessWhilePending ?? true;
+		const script =
+			typeof document !== "undefined"
+				? (document.currentScript as HTMLScriptElement | null)
+				: null;
+		const scriptBase = script?.src
+			? script.src.substring(0, script.src.lastIndexOf("/"))
+			: "";
+		this.baseUrl =
+			(options.baseUrl ?? scriptBase) ||
+			(typeof window !== "undefined" ? window.location.origin : "");
+		if (options.autoTrack ?? true) this.init();
+	}
+
+	private log(msg: string): void {
+		if (this.debug) console.log(`[Analytics] ${msg}`);
+	}
+
+	private init(): void {
+		if (typeof window === "undefined") return;
+		if (isTrackingDisabled()) {
+			this.log("disabled");
+			return;
+		}
+		if ("requestIdleCallback" in window)
+			window.requestIdleCallback(() => this.start());
+		else setTimeout(() => this.start(), 1);
+	}
+
+	start(): void {
+		if (this.started || typeof window === "undefined") return;
+		if (
+			window.__FA_webAnalyticsInstance &&
+			window.__FA_webAnalyticsInstance !== this
+		) {
+			this.log("already started by another instance");
+			return;
+		}
+		if (isTrackingDisabled()) {
+			this.log("disabled");
+			return;
+		}
+		this.started = true;
+		window.__FA_webAnalyticsInstance = this;
+
+		window.__FA_getAnonymousId = () => getAnonymousId(this.isCookielessMode());
+		window.__FA_getSessionId = getOrCreateSessionId;
+		window.__FA_sendData = sendData;
+		window.__FA_identify = (externalId, email, options) =>
+			this.identify(externalId, email, options);
+		window.__FA_logout = (resetAnonymousIdentity) =>
+			this.logout(resetAnonymousIdentity);
+		window.__FA_setConsentMode = (mode) => this.setConsentMode(mode);
+		window.__FA_optIn = () => this.optIn();
+		window.__FA_optOut = () => this.optOut();
+		window.__FA_isTrackingDisabled = isTrackingDisabled;
+
+		const opts = this.options;
+		const hasWebVitalsSampling =
+			opts.webVitals?.sampling?.percentage !== undefined;
+		const hasReplaySampling =
+			opts.replayOptions?.samplingPercentage !== undefined ||
+			opts.sessionReplays?.sampling?.percentage !== undefined;
+
+		if (opts.errorTracking?.enabled ?? opts.trackErrors) {
+			this.load("error", "__FA_ErrorTracker", {
+				siteKey: opts.siteKey,
+				endpoint: this.endpoint,
+				debug: this.debug,
+				getCommonData: () => ({
+					url: location.href,
+					page: location.pathname,
+					referrer: document.referrer || null,
+				}),
+			});
+		}
+		if (
+			opts.webVitals?.enabled ??
+			opts.trackWebVitals ??
+			hasWebVitalsSampling
+		) {
+			this.load("web-vitals", "__FA_WebVitalsTracker", {
+				siteKey: opts.siteKey,
+				endpoint: this.endpoint,
+				debug: this.debug,
+				samplingPercentage: normalizeSamplingPercentage(
+					opts.webVitals?.sampling?.percentage,
+				),
+			});
+		}
+		if (opts.sessionReplays?.enabled ?? opts.trackReplay ?? hasReplaySampling) {
+			const replayOpts = opts.replayOptions ?? {};
+			this.load("replay", "__FA_ReplayTracker", {
+				siteKey: opts.siteKey,
+				endpoint: this.endpoint,
+				debug: this.debug,
+				...replayOpts,
+				samplingPercentage: normalizeSamplingPercentage(
+					replayOpts.samplingPercentage ??
+						opts.sessionReplays?.sampling?.percentage,
+				),
+			});
+		}
+
+		this.enterPage();
+		this.pageview({ trigger: "load" });
+		this.links();
+		this.trackScroll();
+		this.startHeartbeat();
+
+		document.addEventListener("visibilitychange", () => {
+			if (document.visibilityState === "hidden") this.leavePage();
+			else this.startHeartbeat();
+		});
+		window.addEventListener("pagehide", () => this.leavePage());
+		window.addEventListener("popstate", () => this.navigate());
+		if (opts.trackHash)
+			window.addEventListener("hashchange", () => this.navigate());
+		this.patch();
+	}
+
+	private load(
+		script: string,
+		key: string,
+		trackerOpts: Record<string, unknown>,
+	): void {
+		const el = document.createElement("script");
+		el.src = `${this.baseUrl}/${script}.js`;
+		el.async = true;
+		el.onload = () => {
+			const Ctor = (window as unknown as Record<string, unknown>)[key] as
+				| (new (
+						o: Record<string, unknown>,
+				  ) => { start(): void })
+				| undefined;
+			if (Ctor) {
+				new Ctor(trackerOpts).start();
+				this.log(`${script} loaded`);
+			}
+		};
+		el.onerror = () => {
+			if (this.debug) console.warn(`[Analytics] ${script} failed`);
+		};
+		document.head.appendChild(el);
+	}
+
+	pageview(extra: Dict = {}): void {
+		const key = `${location.pathname}|${(this.options.trackHash ?? false) ? location.hash : ""}`;
+		if (key === this.pageKey) return;
+		this.pageKey = key;
+		this.send("pageview", extra);
+	}
+
+	track(name: string, extra: Dict = {}): void {
+		this.send(name, extra);
+	}
+
+	identify(
+		externalId: string,
+		email: string,
+		options: IdentifyOptions = {},
+	): void {
+		if (isTrackingDisabled()) return;
+		if (this.isCookielessMode()) return;
+
+		const trimmedExternalId = externalId.trim();
+		const trimmedEmail = email.trim();
+		if (!trimmedExternalId || !trimmedEmail) return;
+
+		const identifyEndpoint = this.endpoint.replace(
+			/\/v1\/web$/,
+			"/v1/identify",
+		);
+		const payload = JSON.stringify({
+			token: this.options.siteKey,
+			identifier: getAnonymousId(false),
+			externalId: trimmedExternalId,
+			email: trimmedEmail,
+			name: options.name?.trim() || undefined,
+			phone: options.phone?.trim() || undefined,
+			avatarUrl: options.avatarUrl?.trim() || undefined,
+			traits: options.traits ?? {},
+		});
+
+		sendData({
+			url: identifyEndpoint,
+			data: payload,
+			contentType: "text/plain",
+			debug: this.debug,
+			debugPrefix: "[Analytics] identify",
+		});
+	}
+
+	logout(resetAnonymousIdentity = true): void {
+		if (isTrackingDisabled()) return;
+		if (resetAnonymousIdentity) {
+			resetAnonymousId(this.isCookielessMode());
+		}
+		resetSessionId();
+	}
+
+	setConsentMode(mode: ConsentMode): void {
+		this.consentMode = mode;
+	}
+
+	optIn(): void {
+		this.setConsentMode("granted");
+	}
+
+	optOut(): void {
+		this.setConsentMode("denied");
+	}
+
+	getConsentMode(): ConsentMode {
+		return this.consentMode;
+	}
+
+	private isCookielessMode(): boolean {
+		if (this.options.cookieless) return true;
+		if (this.consentMode === "denied") return true;
+		if (this.consentMode === "pending") return this.cookielessWhilePending;
+		return false;
+	}
+
+	private send(event: string, extra: Dict = {}): void {
+		const identifier = getAnonymousId(this.isCookielessMode());
+		const payload = JSON.stringify({
+			token: this.options.siteKey,
+			...(identifier ? { userId: identifier } : {}),
+			sessionId: getOrCreateSessionId(),
+			data: {
+				event,
+				page: location.pathname,
+				referrer: document.referrer || null,
+				title: document.title || "",
+				url: location.href,
+				...getUTM(),
+				...extra,
+			},
+		});
+		this.log(event);
+		sendData({
+			url: this.endpoint,
+			data: payload,
+			contentType: "text/plain",
+			debug: this.debug,
+			debugPrefix: `[Analytics] ${event}`,
+		});
+	}
+
+	private enterPage(): void {
+		this.pageEntryTime = Date.now();
+		this.pagePath = location.pathname;
+		this.pageUrl = location.href;
+		this.pageHash = location.hash;
+		this.scrollDepth = 0;
+		this.hasLeftCurrentPage = false;
+	}
+
+	private leavePage(): void {
+		if (this.hasLeftCurrentPage) return;
+		this.hasLeftCurrentPage = true;
+		const now = Date.now();
+		this.send("page_leave", {
+			page: this.pagePath,
+			url: this.pageUrl,
+			time_on_page: now - this.pageEntryTime,
+			scroll_depth: this.scrollDepth,
+			session_duration: now - getSessionStart(),
+		});
+	}
+
+	private trackScroll(): void {
+		if (this.scrollHandler) {
+			window.removeEventListener("scroll", this.scrollHandler);
+		}
+		const update = () => {
+			const doc = document.documentElement;
+			const body = document.body;
+			const viewportH = window.innerHeight;
+			const docH = Math.max(doc.scrollHeight, body.scrollHeight);
+			if (docH <= viewportH) {
+				this.scrollDepth = 100;
+				return;
+			}
+			const depth = Math.min(
+				100,
+				Math.round(
+					(((window.scrollY || doc.scrollTop) + viewportH) / docH) * 100,
+				),
+			);
+			if (depth > this.scrollDepth) this.scrollDepth = depth;
+		};
+		this.scrollHandler = update;
+		update();
+		window.addEventListener("scroll", update, { passive: true });
+	}
+
+	private startHeartbeat(): void {
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = setInterval(
+			() => {
+				if (document.visibilityState === "hidden") {
+					clearInterval(this.heartbeatTimer as ReturnType<typeof setInterval>);
+					this.heartbeatTimer = null;
+					return;
+				}
+				refreshSessionTimestamp();
+			},
+			5 * 60 * 1000,
+		);
+	}
+
+	private navigate(): void {
+		if (this.navTimer) clearTimeout(this.navTimer);
+		this.navTimer = setTimeout(() => {
+			this.navTimer = null;
+			const pathChanged = location.pathname !== this.pagePath;
+			const hashChanged =
+				(this.options.trackHash ?? false) && location.hash !== this.pageHash;
+			if (!pathChanged && !hashChanged) return;
+			this.leavePage();
+			this.enterPage();
+			this.trackScroll();
+			this.pageview({ trigger: "navigation" });
+		}, 300);
+	}
+
+	private patch(): void {
+		const fire = () => this.navigate();
+		for (const method of ["pushState", "replaceState"] as const) {
+			const orig = history[method];
+			history[method] = function (
+				this: History,
+				...args: Parameters<typeof orig>
+			) {
+				const result = orig.apply(this, args);
+				fire();
+				return result;
+			};
+		}
+	}
+
+	private links(): void {
+		const handler = (event: MouseEvent) => {
+			const link = getLinkEl(event.target as Node);
+			if (link && link.host !== location.host)
+				this.track("outbound_link", { outbound_link: link.href });
+		};
+		document.addEventListener("click", handler);
+		document.addEventListener("auxclick", handler);
+	}
+}