alphana-sdk 1.8.0 → 2.0.2

package/dist/index.d.mts

@@ -61,15 +61,11 @@ interface TrackerConfig {
      */
     trackLogs?: boolean;
     /**
-     * List of page paths for which heatmap data should be captured client-side.
-     * Paths should match the dashboard "Heatmap pages" list (decoded Unicode is
-     * fine — the SDK normalizes percent-encoding vs `window.location` mismatches).
-     *
-     * If empty or undefined, the SDK may still collect moves locally, but the
-     * backend only persists points when the app has at least one registered
-     * heatmap page and the path matches.
-     *
-     * Example: `heatmapPages: ["/", "/pricing", "/dashboard"]`
+     * @deprecated Optional client-side path filter only. Heatmap pages are
+     * registered in the Alphana dashboard; the backend persists points only for
+     * those paths. Leave unset so the SDK collects on every page and the server
+     * filters — no SDK configuration is required when you add a page in the
+     * dashboard.
      */
     heatmapPages?: string[];
     /**
@@ -97,6 +93,12 @@ interface TrackerConfig {
     sessionReplayMaskTextClass?: string;
     /** CSS class name for DOM subtrees that rrweb should not capture. */
     sessionReplayBlockClass?: string;
+    /**
+     * Cookie consent mode.
+     * - `auto` (default): honor the dashboard cookie-consent widget when enabled.
+     * - `disabled`: never show the consent banner; track immediately.
+     */
+    consentMode?: "auto" | "disabled";
     /** Called synchronously for every emitted event. */
     onEvent?: (event: TrackerEvent) => void;
 }
@@ -159,11 +161,23 @@ interface HeatmapPoint {
     pw?: number;
     /** Page scrollHeight at the time of the event (used for accurate remapping) */
     ph?: number;
+    /** Viewport (innerWidth) at capture time — disambiguates responsive layouts. */
+    vw?: number;
     type: "move" | "click" | "scroll";
     path: string;
     timestamp: number;
     /** Text/label of the clicked element — only present on click events. */
     target?: string;
+    /**
+     * Stable CSS selector of the anchored element (clicks only). Lets the
+     * dashboard place the point relative to the element in the screenshot, so it
+     * stays accurate even when the visitor's layout differed from the capture.
+     */
+    selector?: string;
+    /** Click X as a fraction (0–1) of the anchored element's width (clicks only). */
+    relX?: number;
+    /** Click Y as a fraction (0–1) of the anchored element's height (clicks only). */
+    relY?: number;
 }
 interface RageClick {
     path: string;
@@ -423,6 +437,10 @@ declare class UserTracker {
     /** Public so consumers can call logCapture.capture() for manual log entries. */
     logCapture?: LogCapture;
     private initialized;
+    private trackingAllowed;
+    private trackingBlocked;
+    private visitorPersisted;
+    private elementBindings?;
     private readonly subscribers;
     /** In-memory queue of events waiting to be flushed. */
     private queue;
@@ -440,8 +458,17 @@ declare class UserTracker {
      * Attach event listeners and start tracking.
      * Safe to call during SSR — returns `this` immediately if `window` is
      * undefined so it can be chained: `const tracker = new UserTracker(cfg).init()`.
+     *
+     * When the dashboard cookie-consent widget is enabled, tracking waits until
+     * the visitor accepts (or resumes a prior decision for the same config version).
      */
     init(): this;
+    private bootstrapRuntime;
+    private applyElementBindings;
+    private persistVisitorIfNeeded;
+    /** Start plugins, network flush, and element listeners after consent is OK. */
+    private startTracking;
+    private blockTracking;
     /** Remove all event listeners, flush remaining queue, and reset state. */
     destroy(): void;
     private handleVisibilityChange;
@@ -561,6 +588,7 @@ declare class UserTracker {
     /** Heatmap points for all tracked paths. */
     getHeatmapData(): Record<string, HeatmapPoint[]>;
     private get collectUrl();
+    private fetchRuntimeConfig;
     private currentPath;
     /**
      * Immediately drain the event queue and POST pending events to `/batch`.
@@ -598,7 +626,7 @@ declare class UserTracker {
  */
 declare function renderHeatmap(canvas: HTMLCanvasElement, points: HeatmapPoint[], options?: HeatmapRenderOptions): void;
 
-declare const ALPHANA_SDK_VERSION = "1.0.2";
+declare const ALPHANA_SDK_VERSION = "2.0.2";
 
 /**
  * Canonical URL path (+ optional query) for analytics / heatmap matching.

package/dist/index.d.ts

@@ -61,15 +61,11 @@ interface TrackerConfig {
      */
     trackLogs?: boolean;
     /**
-     * List of page paths for which heatmap data should be captured client-side.
-     * Paths should match the dashboard "Heatmap pages" list (decoded Unicode is
-     * fine — the SDK normalizes percent-encoding vs `window.location` mismatches).
-     *
-     * If empty or undefined, the SDK may still collect moves locally, but the
-     * backend only persists points when the app has at least one registered
-     * heatmap page and the path matches.
-     *
-     * Example: `heatmapPages: ["/", "/pricing", "/dashboard"]`
+     * @deprecated Optional client-side path filter only. Heatmap pages are
+     * registered in the Alphana dashboard; the backend persists points only for
+     * those paths. Leave unset so the SDK collects on every page and the server
+     * filters — no SDK configuration is required when you add a page in the
+     * dashboard.
      */
     heatmapPages?: string[];
     /**
@@ -97,6 +93,12 @@ interface TrackerConfig {
     sessionReplayMaskTextClass?: string;
     /** CSS class name for DOM subtrees that rrweb should not capture. */
     sessionReplayBlockClass?: string;
+    /**
+     * Cookie consent mode.
+     * - `auto` (default): honor the dashboard cookie-consent widget when enabled.
+     * - `disabled`: never show the consent banner; track immediately.
+     */
+    consentMode?: "auto" | "disabled";
     /** Called synchronously for every emitted event. */
     onEvent?: (event: TrackerEvent) => void;
 }
@@ -159,11 +161,23 @@ interface HeatmapPoint {
     pw?: number;
     /** Page scrollHeight at the time of the event (used for accurate remapping) */
     ph?: number;
+    /** Viewport (innerWidth) at capture time — disambiguates responsive layouts. */
+    vw?: number;
     type: "move" | "click" | "scroll";
     path: string;
     timestamp: number;
     /** Text/label of the clicked element — only present on click events. */
     target?: string;
+    /**
+     * Stable CSS selector of the anchored element (clicks only). Lets the
+     * dashboard place the point relative to the element in the screenshot, so it
+     * stays accurate even when the visitor's layout differed from the capture.
+     */
+    selector?: string;
+    /** Click X as a fraction (0–1) of the anchored element's width (clicks only). */
+    relX?: number;
+    /** Click Y as a fraction (0–1) of the anchored element's height (clicks only). */
+    relY?: number;
 }
 interface RageClick {
     path: string;
@@ -423,6 +437,10 @@ declare class UserTracker {
     /** Public so consumers can call logCapture.capture() for manual log entries. */
     logCapture?: LogCapture;
     private initialized;
+    private trackingAllowed;
+    private trackingBlocked;
+    private visitorPersisted;
+    private elementBindings?;
     private readonly subscribers;
     /** In-memory queue of events waiting to be flushed. */
     private queue;
@@ -440,8 +458,17 @@ declare class UserTracker {
      * Attach event listeners and start tracking.
      * Safe to call during SSR — returns `this` immediately if `window` is
      * undefined so it can be chained: `const tracker = new UserTracker(cfg).init()`.
+     *
+     * When the dashboard cookie-consent widget is enabled, tracking waits until
+     * the visitor accepts (or resumes a prior decision for the same config version).
      */
     init(): this;
+    private bootstrapRuntime;
+    private applyElementBindings;
+    private persistVisitorIfNeeded;
+    /** Start plugins, network flush, and element listeners after consent is OK. */
+    private startTracking;
+    private blockTracking;
     /** Remove all event listeners, flush remaining queue, and reset state. */
     destroy(): void;
     private handleVisibilityChange;
@@ -561,6 +588,7 @@ declare class UserTracker {
     /** Heatmap points for all tracked paths. */
     getHeatmapData(): Record<string, HeatmapPoint[]>;
     private get collectUrl();
+    private fetchRuntimeConfig;
     private currentPath;
     /**
      * Immediately drain the event queue and POST pending events to `/batch`.
@@ -598,7 +626,7 @@ declare class UserTracker {
  */
 declare function renderHeatmap(canvas: HTMLCanvasElement, points: HeatmapPoint[], options?: HeatmapRenderOptions): void;
 
-declare const ALPHANA_SDK_VERSION = "1.0.2";
+declare const ALPHANA_SDK_VERSION = "2.0.2";
 
 /**
  * Canonical URL path (+ optional query) for analytics / heatmap matching.