@probat/react 0.1.5 → 0.2.0

package/README.md

@@ -93,6 +93,38 @@ function Button() {
 }
 ```
 
+### 4. Heatmap Tracking (Automatic)
+
+Heatmap tracking is automatically enabled when you use `ProbatProvider`. It tracks:
+- **Click events**: User clicks across your website
+- **Cursor movements**: Mouse movement patterns for engagement analysis
+
+The tracking automatically associates data with the active experiment (`proposalId`) and variant (`variantLabel`) based on the experiment context. No additional configuration needed!
+
+```tsx
+// Heatmap tracking is automatically initialized by ProbatProvider
+<ProbatProvider clientKey="your-key" environment="dev">
+  <YourApp />
+</ProbatProvider>
+```
+
+To manually control heatmap tracking:
+
+```tsx
+import { initHeatmapTracking, stopHeatmapTracking } from '@probat/react';
+
+// Initialize with custom config
+initHeatmapTracking({
+  apiBaseUrl: 'https://api.probat.com',
+  batchSize: 10,
+  batchInterval: 5000,
+  trackCursor: true, // Enable cursor movement tracking
+});
+
+// Stop tracking when needed
+stopHeatmapTracking();
+```
+
 ## API Reference
 
 ### `<ProbatProvider>`
@@ -108,8 +140,12 @@ Wraps your app and provides Probat configuration to all child components.
   - Default: `"https://gushi.onrender.com"`
 - `clientKey?: string` - Client key for identification (optional)
 - `environment?: "dev" | "prod"` - Explicitly set environment. If not provided, will auto-detect based on hostname.
+- `proposalId?: string` - Optional proposal/experiment ID for heatmap tracking segregation
+- `variantLabel?: string` - Optional variant label for heatmap tracking segregation
 - `children: React.ReactNode` - Your app components
 
+**Note**: `proposalId` and `variantLabel` are automatically set from localStorage when experiments are active. You typically don't need to pass these manually.
+
 #### Example
 
 ```tsx
@@ -177,6 +213,58 @@ trackMetric('purchase', 'proposal-id', 'variant-a', { amount: 100 });
 trackImpression('proposal-id', 'control', 'experiment-id');
 ```
 
+### Heatmap Tracking Functions
+
+#### `initHeatmapTracking(config)`
+
+Initialize heatmap tracking with custom configuration.
+
+##### Parameters
+
+- `config: HeatmapConfig` - Configuration object:
+  - `apiBaseUrl: string` - Base URL for the heatmap API (default: from ProbatProvider)
+  - `batchSize?: number` - Number of clicks to batch before sending (default: `10`)
+  - `batchInterval?: number` - Time in ms to wait before sending batch (default: `5000`)
+  - `trackCursor?: boolean` - Enable cursor movement tracking (default: `true`)
+  - `cursorThrottle?: number` - Throttle cursor events in ms (default: `100`)
+  - `cursorBatchSize?: number` - Number of cursor movements to batch (default: `50`)
+  - `enabled?: boolean` - Enable/disable tracking (default: `true`)
+  - `excludeSelectors?: string[]` - CSS selectors to exclude from tracking
+  - `excludedOrigins?: string[]` - Origins to exclude from tracking
+
+##### Example
+
+```tsx
+import { initHeatmapTracking } from '@probat/react';
+
+initHeatmapTracking({
+  apiBaseUrl: 'https://api.probat.com',
+  batchSize: 20,
+  trackCursor: true,
+  cursorThrottle: 100,
+});
+```
+
+#### `stopHeatmapTracking()`
+
+Stop heatmap tracking and send any pending batches.
+
+##### Example
+
+```tsx
+import { stopHeatmapTracking } from '@probat/react';
+
+stopHeatmapTracking();
+```
+
+#### `getHeatmapTracker()`
+
+Get the current heatmap tracker instance (for advanced usage).
+
+##### Returns
+
+- `HeatmapTracker | null` - The tracker instance or null if not initialized
+
 ### `withExperiment(Control, options)`
 
 Higher-Order Component for wrapping components with experiment variants (backward compatible with old injection pattern).

package/dist/index.d.mts

@@ -10,6 +10,8 @@ interface ProbatContextValue {
     environment: "dev" | "prod";
     clientKey?: string;
     repoFullName?: string;
+    proposalId?: string;
+    variantLabel?: string;
 }
 interface ProbatProviderProps {
     /**
@@ -21,6 +23,14 @@ interface ProbatProviderProps {
      * - Default: "https://gushi.onrender.com"
      */
     apiBaseUrl?: string;
+    /**
+     * Optional: proposal/experiment id for heatmap segregation
+     */
+    proposalId?: string;
+    /**
+     * Optional: variant label for heatmap segregation
+     */
+    variantLabel?: string;
     /**
      * Client key for identification (optional)
      */
@@ -40,7 +50,7 @@ interface ProbatProviderProps {
     repoFullName?: string;
     children: React.ReactNode;
 }
-declare function ProbatProvider({ apiBaseUrl, clientKey, environment: explicitEnvironment, repoFullName: explicitRepoFullName, children, }: ProbatProviderProps): React.JSX.Element;
+declare function ProbatProvider({ apiBaseUrl, clientKey, environment: explicitEnvironment, repoFullName: explicitRepoFullName, proposalId, variantLabel, children, }: ProbatProviderProps): React.JSX.Element;
 declare function useProbatContext(): ProbatContextValue;
 
 /**
@@ -180,6 +190,54 @@ declare function extractClickMeta(event?: {
     target?: EventTarget | null;
 } | null): Record<string, any> | undefined;
 
+/**
+ * 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 HeatmapConfig {
+    apiBaseUrl: string;
+    batchSize?: number;
+    batchInterval?: number;
+    enabled?: boolean;
+    excludeSelectors?: string[];
+    trackCursor?: boolean;
+    cursorThrottle?: number;
+    cursorBatchSize?: number;
+    proposalId?: string;
+    variantLabel?: string;
+}
+declare class HeatmapTracker {
+    private clicks;
+    private movements;
+    private sessionId;
+    private config;
+    private batchTimer;
+    private cursorBatchTimer;
+    private lastCursorTime;
+    private isInitialized;
+    constructor(config: HeatmapConfig);
+    private getOrCreateSessionId;
+    private shouldExcludeElement;
+    private extractElementInfo;
+    private handleMouseMove;
+    private scheduleCursorBatchSend;
+    private sendCursorBatch;
+    private handleClick;
+    private scheduleBatchSend;
+    private sendBatch;
+    init(): void;
+    stop(): void;
+}
+/**
+ * Initialize heatmap tracking for user websites
+ * Called automatically by ProbatProvider
+ */
+declare function initHeatmapTracking(config: HeatmapConfig): HeatmapTracker;
+declare function getHeatmapTracker(): HeatmapTracker | null;
+declare function stopHeatmapTracking(): void;
+
 type Choice = {
     experiment_id: string;
     label: string;
@@ -190,4 +248,4 @@ declare function writeChoice(proposalId: string, experiment_id: string, label: s
 declare function hasTrackedVisit(proposalId: string, label: string): boolean;
 declare function markTrackedVisit(proposalId: string, label: string): void;
 
-export { type Choice, type ProbatContextValue, ProbatProvider, ProbatProviderClient, type ProbatProviderProps as ProbatProviderClientProps, type ProbatProviderProps, type RetrieveResponse, type UseExperimentReturn, type UseProbatMetricsReturn, type WithExperimentOptions, detectEnvironment, extractClickMeta, fetchDecision, hasTrackedVisit, markTrackedVisit, readChoice, sendMetric, useExperiment, useProbatContext, useProbatMetrics, withExperiment, writeChoice };
+export { type Choice, type ProbatContextValue, ProbatProvider, ProbatProviderClient, type ProbatProviderProps as ProbatProviderClientProps, type ProbatProviderProps, type RetrieveResponse, type UseExperimentReturn, type UseProbatMetricsReturn, type WithExperimentOptions, detectEnvironment, extractClickMeta, fetchDecision, getHeatmapTracker, hasTrackedVisit, initHeatmapTracking, markTrackedVisit, readChoice, sendMetric, stopHeatmapTracking, useExperiment, useProbatContext, useProbatMetrics, withExperiment, writeChoice };

package/dist/index.d.ts

@@ -10,6 +10,8 @@ interface ProbatContextValue {
     environment: "dev" | "prod";
     clientKey?: string;
     repoFullName?: string;
+    proposalId?: string;
+    variantLabel?: string;
 }
 interface ProbatProviderProps {
     /**
@@ -21,6 +23,14 @@ interface ProbatProviderProps {
      * - Default: "https://gushi.onrender.com"
      */
     apiBaseUrl?: string;
+    /**
+     * Optional: proposal/experiment id for heatmap segregation
+     */
+    proposalId?: string;
+    /**
+     * Optional: variant label for heatmap segregation
+     */
+    variantLabel?: string;
     /**
      * Client key for identification (optional)
      */
@@ -40,7 +50,7 @@ interface ProbatProviderProps {
     repoFullName?: string;
     children: React.ReactNode;
 }
-declare function ProbatProvider({ apiBaseUrl, clientKey, environment: explicitEnvironment, repoFullName: explicitRepoFullName, children, }: ProbatProviderProps): React.JSX.Element;
+declare function ProbatProvider({ apiBaseUrl, clientKey, environment: explicitEnvironment, repoFullName: explicitRepoFullName, proposalId, variantLabel, children, }: ProbatProviderProps): React.JSX.Element;
 declare function useProbatContext(): ProbatContextValue;
 
 /**
@@ -180,6 +190,54 @@ declare function extractClickMeta(event?: {
     target?: EventTarget | null;
 } | null): Record<string, any> | undefined;
 
+/**
+ * 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 HeatmapConfig {
+    apiBaseUrl: string;
+    batchSize?: number;
+    batchInterval?: number;
+    enabled?: boolean;
+    excludeSelectors?: string[];
+    trackCursor?: boolean;
+    cursorThrottle?: number;
+    cursorBatchSize?: number;
+    proposalId?: string;
+    variantLabel?: string;
+}
+declare class HeatmapTracker {
+    private clicks;
+    private movements;
+    private sessionId;
+    private config;
+    private batchTimer;
+    private cursorBatchTimer;
+    private lastCursorTime;
+    private isInitialized;
+    constructor(config: HeatmapConfig);
+    private getOrCreateSessionId;
+    private shouldExcludeElement;
+    private extractElementInfo;
+    private handleMouseMove;
+    private scheduleCursorBatchSend;
+    private sendCursorBatch;
+    private handleClick;
+    private scheduleBatchSend;
+    private sendBatch;
+    init(): void;
+    stop(): void;
+}
+/**
+ * Initialize heatmap tracking for user websites
+ * Called automatically by ProbatProvider
+ */
+declare function initHeatmapTracking(config: HeatmapConfig): HeatmapTracker;
+declare function getHeatmapTracker(): HeatmapTracker | null;
+declare function stopHeatmapTracking(): void;
+
 type Choice = {
     experiment_id: string;
     label: string;
@@ -190,4 +248,4 @@ declare function writeChoice(proposalId: string, experiment_id: string, label: s
 declare function hasTrackedVisit(proposalId: string, label: string): boolean;
 declare function markTrackedVisit(proposalId: string, label: string): void;
 
-export { type Choice, type ProbatContextValue, ProbatProvider, ProbatProviderClient, type ProbatProviderProps as ProbatProviderClientProps, type ProbatProviderProps, type RetrieveResponse, type UseExperimentReturn, type UseProbatMetricsReturn, type WithExperimentOptions, detectEnvironment, extractClickMeta, fetchDecision, hasTrackedVisit, markTrackedVisit, readChoice, sendMetric, useExperiment, useProbatContext, useProbatMetrics, withExperiment, writeChoice };
+export { type Choice, type ProbatContextValue, ProbatProvider, ProbatProviderClient, type ProbatProviderProps as ProbatProviderClientProps, type ProbatProviderProps, type RetrieveResponse, type UseExperimentReturn, type UseProbatMetricsReturn, type WithExperimentOptions, detectEnvironment, extractClickMeta, fetchDecision, getHeatmapTracker, hasTrackedVisit, initHeatmapTracking, markTrackedVisit, readChoice, sendMetric, stopHeatmapTracking, useExperiment, useProbatContext, useProbatMetrics, withExperiment, writeChoice };