@probat/react 0.1.5 → 0.2.0

package/src/hoc/withExperiment.tsx

@@ -163,23 +163,53 @@ export function withExperiment<P = any>(
             const cached = readChoice(proposalId);
 
             if (cached) {
-                setChoice({
+                const choiceData = {
                     experiment_id: cached.experiment_id,
                     label: cached.label,
-                });
+                };
+                setChoice(choiceData);
+                // Set localStorage for heatmap tracking
+                if (typeof window !== 'undefined') {
+                    try {
+                        window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                        window.localStorage.setItem('probat_active_variant_label', cached.label);
+                    } catch (e) {
+                        console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
+                    }
+                }
             } else {
                 (async () => {
                     try {
                         const { experiment_id, label } = await fetchDecision(apiBaseUrl, proposalId);
                         if (!alive) return;
                         writeChoice(proposalId, experiment_id, label);
-                        setChoice({ experiment_id, label });
+                        const choiceData = { experiment_id, label };
+                        setChoice(choiceData);
+                        // Set localStorage for heatmap tracking (fetchDecision already sets it, but ensure it's set here too)
+                        if (typeof window !== 'undefined') {
+                            try {
+                                window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                                window.localStorage.setItem('probat_active_variant_label', label);
+                            } catch (e) {
+                                console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
+                            }
+                        }
                     } catch (e) {
                         if (!alive) return;
-                        setChoice({
+                        const choiceData = {
                             experiment_id: `exp_${proposalId}`,
                             label: "control",
-                        });
+                        };
+                        setChoice(choiceData);
+                        // Set localStorage for control variant
+                        if (typeof window !== 'undefined') {
+                            try {
+                                window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                                window.localStorage.setItem('probat_active_variant_label', 'control');
+                            } catch (err) {
+                                console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', err);
+                            }
+                        }
                     }
                 })();
             }

package/src/index.ts

@@ -28,6 +28,8 @@ export type { WithExperimentOptions } from "./hoc/withExperiment";
 export { detectEnvironment } from "./utils/environment";
 export { fetchDecision, sendMetric, extractClickMeta } from "./utils/api";
 export type { RetrieveResponse } from "./utils/api";
+// Heatmap tracking (automatically initialized by ProbatProvider)
+export { initHeatmapTracking, stopHeatmapTracking, getHeatmapTracker } from "./utils/heatmapTracker";
 export {
     readChoice,
     writeChoice,

package/src/utils/api.ts

@@ -51,6 +51,16 @@ export async function fetchDecision(
             const experiment_id = (data.experiment_id || `exp_${proposalId}`).toString();
             const label = data.label && data.label.trim() ? data.label : "control";
 
+            // Auto-set localStorage for heatmap tracking
+            if (typeof window !== 'undefined') {
+                try {
+                    window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                    window.localStorage.setItem('probat_active_variant_label', label);
+                } catch (e) {
+                    console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
+                }
+            }
+
             return { experiment_id, label };
         } finally {
             // Remove from pending cache after completion
@@ -161,6 +171,18 @@ export async function fetchComponentExperimentConfig(
             }
 
             const data = (await res.json()) as ComponentExperimentConfig;
+
+            // Auto-set localStorage for heatmap tracking when component config is loaded
+            // This will be updated when a specific variant is selected via fetchDecision
+            if (typeof window !== 'undefined' && data?.proposal_id) {
+                try {
+                    window.localStorage.setItem('probat_active_proposal_id', data.proposal_id);
+                    // Variant label will be set when fetchDecision is called
+                } catch (e) {
+                    console.warn('[PROBAT] Failed to set proposal_id in localStorage:', e);
+                }
+            }
+
             return data;
         } catch (e) {
             console.warn(`[PROBAT] Failed to fetch component config: ${e}`);

package/src/utils/heatmapTracker.ts

@@ -0,0 +1,478 @@
+/**
+ * Universal Heatmap Tracker for User Websites
+ * 
+ * Tracks all clicks across the entire user website for heatmap visualization.
+ * This is injected into user websites via the probat-react package.
+ */
+
+interface ClickEvent {
+	page_url: string;
+	site_url: string;
+	x_coordinate: number;
+	y_coordinate: number;
+	viewport_width: number;
+	viewport_height: number;
+	element_tag: string | null;
+	element_class: string | null;
+	element_id: string | null;
+	session_id: string;
+	proposal_id?: string | null;
+	variant_label?: string | null;
+}
+
+interface CursorMovementEvent {
+	page_url: string;
+	site_url: string;
+	x_coordinate: number;
+	y_coordinate: number;
+	viewport_width: number;
+	viewport_height: number;
+	session_id: string;
+	proposal_id?: string | null;
+	variant_label?: string | null;
+}
+
+interface HeatmapConfig {
+	apiBaseUrl: string;
+	batchSize?: number;
+	batchInterval?: number;
+	enabled?: boolean;
+	excludeSelectors?: string[];
+	trackCursor?: boolean; // Enable cursor movement tracking
+	cursorThrottle?: number; // Milliseconds between cursor movement captures (default: 100ms)
+	cursorBatchSize?: number; // Number of cursor movements to batch before sending
+	proposalId?: string; // Optional proposal/experiment id
+	variantLabel?: string; // Optional variant label
+}
+
+function getStoredExperimentInfo(): { proposalId?: string; variantLabel?: string } {
+	if (typeof window === 'undefined') return {};
+	try {
+		const proposalId = window.localStorage.getItem('probat_active_proposal_id') || undefined;
+		const variantLabel = window.localStorage.getItem('probat_active_variant_label') || undefined;
+		return { proposalId, variantLabel };
+	} catch {
+		return {};
+	}
+}
+
+class HeatmapTracker {
+	private clicks: ClickEvent[] = [];
+	private movements: CursorMovementEvent[] = [];
+	private sessionId: string;
+	private config: HeatmapConfig;
+	private batchTimer: ReturnType<typeof setTimeout> | null = null;
+	private cursorBatchTimer: ReturnType<typeof setTimeout> | null = null;
+	private lastCursorTime = 0;
+	private isInitialized = false;
+
+	constructor(config: HeatmapConfig) {
+		this.sessionId = this.getOrCreateSessionId();
+		const stored = getStoredExperimentInfo();
+
+		this.config = {
+			apiBaseUrl: config.apiBaseUrl,
+			batchSize: config.batchSize || 10,
+			batchInterval: config.batchInterval || 5000,
+			enabled: config.enabled !== false,
+			excludeSelectors: config.excludeSelectors || [
+				'[data-heatmap-exclude]',
+				'input[type="password"]',
+				'input[type="email"]',
+				'textarea',
+			],
+			trackCursor: config.trackCursor !== false, // Enable cursor tracking by default
+			cursorThrottle: config.cursorThrottle || 100, // Capture cursor position every 100ms
+			cursorBatchSize: config.cursorBatchSize || 50, // Send every 50 movements
+			proposalId: config.proposalId || stored.proposalId,
+			variantLabel: config.variantLabel || stored.variantLabel,
+		};
+	}
+
+	private getOrCreateSessionId(): string {
+		if (typeof window === 'undefined') return '';
+
+		const storageKey = 'probat_heatmap_session_id';
+		let sessionId = localStorage.getItem(storageKey);
+
+		if (!sessionId) {
+			sessionId = `heatmap_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+			localStorage.setItem(storageKey, sessionId);
+		}
+
+		return sessionId;
+	}
+
+	private shouldExcludeElement(element: HTMLElement): boolean {
+		if (!this.config.excludeSelectors) return false;
+
+		for (const selector of this.config.excludeSelectors) {
+			if (element.matches(selector) || element.closest(selector)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	private extractElementInfo(element: HTMLElement): {
+		tag: string | null;
+		class: string | null;
+		id: string | null;
+	} {
+		return {
+			tag: element.tagName || null,
+			class: element.className && typeof element.className === 'string' ? element.className : null,
+			id: element.id || null,
+		};
+	}
+
+	private handleMouseMove = (event: MouseEvent): void => {
+		if (!this.config.enabled || !this.config.trackCursor) return;
+		if (typeof window === 'undefined') return;
+
+		// Refresh proposal/variant from localStorage at runtime
+		const stored = getStoredExperimentInfo();
+		const proposalId = this.config.proposalId || stored.proposalId;
+		const variantLabel = this.config.variantLabel || stored.variantLabel;
+
+		// Throttle cursor tracking
+		const now = Date.now();
+		const cursorThrottle = this.config.cursorThrottle ?? 100;
+		if (now - this.lastCursorTime < cursorThrottle) {
+			return;
+		}
+		this.lastCursorTime = now;
+
+		// Debug: Log first few movements to verify it's working
+		if (this.movements.length < 3) {
+			console.log('[PROBAT Heatmap] Cursor movement captured:', {
+				x: event.clientX,
+				y: event.clientY,
+				movementsInBatch: this.movements.length + 1
+			});
+		}
+
+		// Get page information
+		const pageUrl = window.location.href;
+		const siteUrl = window.location.origin;
+
+		// Get cursor coordinates relative to viewport
+		const x = event.clientX;
+		const y = event.clientY;
+
+		// Get viewport dimensions
+		const viewportWidth = window.innerWidth;
+		const viewportHeight = window.innerHeight;
+
+		// Create cursor movement event
+		const movementEvent: CursorMovementEvent = {
+			page_url: pageUrl,
+			site_url: siteUrl,
+			x_coordinate: x,
+			y_coordinate: y,
+			viewport_width: viewportWidth,
+			viewport_height: viewportHeight,
+			session_id: this.sessionId,
+			proposal_id: proposalId,
+			variant_label: variantLabel,
+		};
+
+		// Add to batch
+		this.movements.push(movementEvent);
+
+		// Send batch if it reaches the size limit
+		const cursorBatchSize = this.config.cursorBatchSize ?? 50;
+		if (this.movements.length >= cursorBatchSize) {
+			this.sendCursorBatch();
+		} else {
+			// Otherwise, schedule a send after the interval
+			this.scheduleCursorBatchSend();
+		}
+	};
+
+	private scheduleCursorBatchSend(): void {
+		// Clear existing timer
+		if (this.cursorBatchTimer) {
+			clearTimeout(this.cursorBatchTimer);
+		}
+
+		// Schedule new send
+		this.cursorBatchTimer = setTimeout(() => {
+			if (this.movements.length > 0) {
+				this.sendCursorBatch();
+			}
+		}, this.config.batchInterval ?? 5000);
+	}
+
+	private async sendCursorBatch(): Promise<void> {
+		if (this.movements.length === 0) return;
+
+		// Get site URL from first movement
+		const siteUrl = this.movements[0]?.site_url || window.location.origin;
+
+		// Create batch
+		const batch = {
+			movements: this.movements,
+			site_url: siteUrl,
+			proposal_id: this.config.proposalId,
+			variant_label: this.config.variantLabel,
+		};
+
+		// Clear movements array
+		this.movements = [];
+
+		// Clear timer
+		if (this.cursorBatchTimer) {
+			clearTimeout(this.cursorBatchTimer);
+			this.cursorBatchTimer = null;
+		}
+
+		try {
+			console.log('[PROBAT Heatmap] Sending cursor movements batch:', {
+				count: batch.movements.length,
+				site_url: batch.site_url
+			});
+
+			// Send to backend
+			const response = await fetch(`${this.config.apiBaseUrl}/api/heatmap/cursor-movements`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+				},
+				body: JSON.stringify(batch),
+				// Don't wait for response - fire and forget for performance
+			});
+
+			if (!response.ok) {
+				console.warn('[PROBAT Heatmap] Failed to send cursor movements:', response.status);
+			} else {
+				console.log('[PROBAT Heatmap] Successfully sent cursor movements batch');
+			}
+		} catch (error) {
+			// Silently fail - don't interrupt user experience
+			console.warn('[PROBAT Heatmap] Error sending cursor movements:', error);
+		}
+	}
+
+	private handleClick = (event: MouseEvent): void => {
+		if (!this.config.enabled) return;
+		if (typeof window === 'undefined') return;
+
+		// Refresh proposal/variant from localStorage at runtime
+		const stored = getStoredExperimentInfo();
+		const proposalId = this.config.proposalId || stored.proposalId;
+		const variantLabel = this.config.variantLabel || stored.variantLabel;
+
+		const target = event.target as HTMLElement | null;
+		if (!target) return;
+
+		if (this.shouldExcludeElement(target)) {
+			return;
+		}
+
+		const pageUrl = window.location.href;
+		const siteUrl = window.location.origin;
+
+		const x = event.clientX;
+		const y = event.clientY;
+
+		const viewportWidth = window.innerWidth;
+		const viewportHeight = window.innerHeight;
+
+		const elementInfo = this.extractElementInfo(target);
+
+		const clickEvent: ClickEvent = {
+			page_url: pageUrl,
+			site_url: siteUrl,
+			x_coordinate: x,
+			y_coordinate: y,
+			viewport_width: viewportWidth,
+			viewport_height: viewportHeight,
+			element_tag: elementInfo.tag,
+			element_class: elementInfo.class,
+			element_id: elementInfo.id,
+			session_id: this.sessionId,
+			proposal_id: proposalId,
+			variant_label: variantLabel,
+		};
+
+		this.clicks.push(clickEvent);
+
+		const batchSize = this.config.batchSize ?? 10;
+		if (this.clicks.length >= batchSize) {
+			this.sendBatch();
+		} else {
+			this.scheduleBatchSend();
+		}
+	};
+
+	private scheduleBatchSend(): void {
+		if (this.batchTimer) {
+			clearTimeout(this.batchTimer);
+		}
+
+		this.batchTimer = setTimeout(() => {
+			if (this.clicks.length > 0) {
+				this.sendBatch();
+			}
+		}, this.config.batchInterval ?? 5000);
+	}
+
+	private async sendBatch(): Promise<void> {
+		if (this.clicks.length === 0) return;
+
+		if (this.batchTimer) {
+			clearTimeout(this.batchTimer);
+			this.batchTimer = null;
+		}
+
+		const siteUrl = this.clicks[0]?.site_url || window.location.origin;
+
+		const batch = {
+			clicks: [...this.clicks],
+			site_url: siteUrl,
+		};
+
+		this.clicks = [];
+
+		try {
+			const response = await fetch(`${this.config.apiBaseUrl}/api/heatmap/clicks`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+				},
+				body: JSON.stringify(batch),
+			});
+
+			if (!response.ok) {
+				console.warn('[PROBAT Heatmap] Failed to send clicks:', response.status);
+			}
+		} catch (error) {
+			console.warn('[PROBAT Heatmap] Error sending clicks:', error);
+		}
+	}
+
+	public init(): void {
+		if (this.isInitialized) {
+			console.warn('[PROBAT Heatmap] Tracker already initialized');
+			return;
+		}
+
+		if (typeof window === 'undefined') {
+			return;
+		}
+
+		document.addEventListener('click', this.handleClick, true);
+
+		// Attach cursor movement listener if enabled
+		if (this.config.trackCursor) {
+			document.addEventListener('mousemove', this.handleMouseMove, { passive: true });
+			console.log('[PROBAT Heatmap] Cursor tracking enabled');
+		} else {
+			console.log('[PROBAT Heatmap] Cursor tracking disabled');
+		}
+
+		this.isInitialized = true;
+		console.log('[PROBAT Heatmap] Tracker initialized', {
+			enabled: this.config.enabled,
+			trackCursor: this.config.trackCursor,
+			cursorThrottle: this.config.cursorThrottle,
+			cursorBatchSize: this.config.cursorBatchSize
+		});
+
+		window.addEventListener('beforeunload', () => {
+			if (this.clicks.length > 0) {
+				const siteUrl = this.clicks[0]?.site_url || window.location.origin;
+				const batch = {
+					clicks: this.clicks,
+					site_url: siteUrl,
+				};
+
+				const blob = new Blob([JSON.stringify(batch)], {
+					type: 'application/json',
+				});
+				navigator.sendBeacon(
+					`${this.config.apiBaseUrl}/api/heatmap/clicks`,
+					blob
+				);
+			}
+
+			if (this.movements.length > 0) {
+				const siteUrl = this.movements[0]?.site_url || window.location.origin;
+				const batch = {
+					movements: this.movements,
+					site_url: siteUrl,
+				};
+
+				const blob = new Blob([JSON.stringify(batch)], {
+					type: 'application/json',
+				});
+				navigator.sendBeacon(
+					`${this.config.apiBaseUrl}/api/heatmap/cursor-movements`,
+					blob
+				);
+			}
+		});
+	}
+
+	public stop(): void {
+		if (!this.isInitialized) return;
+
+		// Send any pending clicks
+		if (this.clicks.length > 0) {
+			this.sendBatch();
+		}
+
+		// Send any pending cursor movements
+		if (this.movements.length > 0) {
+			this.sendCursorBatch();
+		}
+
+		// Remove event listeners
+		document.removeEventListener('click', this.handleClick, true);
+		if (this.config.trackCursor) {
+			document.removeEventListener('mousemove', this.handleMouseMove);
+		}
+
+		// Clear timers
+		if (this.batchTimer) {
+			clearTimeout(this.batchTimer);
+			this.batchTimer = null;
+		}
+		if (this.cursorBatchTimer) {
+			clearTimeout(this.cursorBatchTimer);
+			this.cursorBatchTimer = null;
+		}
+
+		this.isInitialized = false;
+	}
+}
+
+let trackerInstance: HeatmapTracker | null = null;
+
+/**
+ * Initialize heatmap tracking for user websites
+ * Called automatically by ProbatProvider
+ */
+export function initHeatmapTracking(config: HeatmapConfig): HeatmapTracker {
+	if (trackerInstance) {
+		trackerInstance.stop();
+	}
+
+	trackerInstance = new HeatmapTracker(config);
+	trackerInstance.init();
+
+	return trackerInstance;
+}
+
+export function getHeatmapTracker(): HeatmapTracker | null {
+	return trackerInstance;
+}
+
+export function stopHeatmapTracking(): void {
+	if (trackerInstance) {
+		trackerInstance.stop();
+		trackerInstance = null;
+	}
+}