@grainql/analytics-web 3.1.1 → 3.2.0

package/dist/heatmap-tracking.js

@@ -3,6 +3,39 @@
  * Heatmap Tracking Manager for Grain Analytics
  * Tracks click interactions and scroll depth across all pages
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HeatmapTrackingManager = void 0;
 const attention_quality_1 = require("./attention-quality");
@@ -29,6 +62,9 @@ class HeatmapTrackingManager {
         this.lastScrollPosition = 0;
         this.lastScrollTime = Date.now();
         this.SPLIT_DURATION = 3000; // 3 seconds - same as section tracking
+        // Snapshot capture state
+        this.snapshotCaptured = false;
+        this.snapshotEnabled = false;
         this.tracker = tracker;
         this.options = { ...DEFAULT_OPTIONS, ...options };
         // Initialize attention quality manager
@@ -51,10 +87,12 @@ class HeatmapTrackingManager {
     /**
      * Initialize heatmap tracking
      */
-    initialize() {
+    async initialize() {
         if (this.isDestroyed)
             return;
         this.log('Initializing heatmap tracking');
+        // Check remote config for snapshot capture
+        await this.checkSnapshotConfig();
         // Setup click tracking
         this.setupClickTracking();
         // Setup scroll tracking
@@ -63,6 +101,158 @@ class HeatmapTrackingManager {
         this.startScrollTracking();
         // Setup page unload handler for beaconing
         this.setupUnloadHandler();
+        // Initialize snapshot capture if enabled
+        if (this.snapshotEnabled && !this.snapshotCaptured) {
+            this.captureSnapshot();
+        }
+    }
+    /**
+     * Check remote config for snapshot capture enablement
+     */
+    /**
+     * Normalize URL by removing query params and hash, and stripping www prefix
+     * This ensures heatmap data is aggregated by page, not by URL variations
+     * Subdomains (other than www) are preserved: api.example.com != app.example.com
+     */
+    normalizeUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            let hostname = urlObj.hostname.toLowerCase();
+            // Strip www prefix but keep other subdomains
+            if (hostname.startsWith('www.')) {
+                hostname = hostname.substring(4);
+            }
+            // Return protocol + normalized hostname + pathname only
+            return `${urlObj.protocol}//${hostname}${urlObj.pathname}`;
+        }
+        catch {
+            // If URL parsing fails, return as-is
+            return url;
+        }
+    }
+    async checkSnapshotConfig() {
+        try {
+            const enableSnapshot = await this.tracker.getConfigAsync('enableHeatmapSnapshot');
+            this.snapshotEnabled = enableSnapshot === 'true';
+            this.log('Heatmap snapshot capture enabled:', this.snapshotEnabled);
+        }
+        catch (error) {
+            this.log('Failed to check snapshot config, defaulting to disabled:', error);
+            this.snapshotEnabled = false;
+        }
+    }
+    /**
+     * Capture DOM snapshot using rrweb-snapshot
+     */
+    async captureSnapshot() {
+        if (this.snapshotCaptured || !this.snapshotEnabled)
+            return;
+        try {
+            this.log('Capturing DOM snapshot...');
+            // Dynamically import rrweb-snapshot (only if enabled)
+            // @ts-ignore - rrweb-snapshot is an optional dependency, may not be resolvable during React build
+            const rrwebSnapshot = await Promise.resolve().then(() => __importStar(require('rrweb-snapshot')));
+            // Capture full DOM snapshot with PII masking
+            const snapshot = rrwebSnapshot.snapshot(document, {
+                maskAllInputs: true,
+                maskTextFn: (text) => {
+                    // Basic PII masking - mask anything that looks like email or sensitive data
+                    return text.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '*****');
+                },
+            });
+            this.snapshotCaptured = true;
+            this.log('DOM snapshot captured successfully');
+            // Upload snapshot to backend
+            await this.uploadSnapshot(snapshot);
+        }
+        catch (error) {
+            this.log('Failed to capture DOM snapshot:', error);
+        }
+    }
+    /**
+     * Upload snapshot to backend
+     */
+    async uploadSnapshot(snapshot) {
+        try {
+            const sessionId = this.tracker.getEffectiveUserId();
+            const pageUrl = this.normalizeUrl(window.location.href);
+            this.log('Uploading snapshot to backend - sessionId:', sessionId);
+            // Note: The actual API call would need the tenantId from the tracker
+            // For now, we'll log that the snapshot is ready to be uploaded
+            // The tracker would need to expose tenantId for this to work
+            const snapshotData = {
+                sessionId,
+                pageUrl,
+                snapshot
+            };
+            this.log('Snapshot data prepared:', { sessionId, pageUrl, snapshotSize: JSON.stringify(snapshot).length });
+            // Get API configuration from tracker
+            const apiUrl = await this.getApiUrl();
+            const tenantId = await this.getTenantId();
+            const headers = await this.getAuthHeaders();
+            if (!apiUrl || !tenantId) {
+                this.log('Cannot upload snapshot: missing API URL or tenant ID');
+                return;
+            }
+            // Upload to backend
+            const response = await fetch(`${apiUrl}/v1/events/${encodeURIComponent(tenantId)}/snapshot`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...headers
+                },
+                body: JSON.stringify({
+                    sessionId,
+                    pageUrl,
+                    snapshot: JSON.stringify(snapshot),
+                    timestamp: Date.now()
+                })
+            });
+            if (!response.ok) {
+                throw new Error(`Snapshot upload failed: ${response.status}`);
+            }
+            const result = await response.json();
+            this.log('Snapshot uploaded successfully:', result);
+        }
+        catch (error) {
+            this.log('Failed to upload snapshot:', error);
+        }
+    }
+    /**
+     * Get API URL from tracker configuration
+     */
+    async getApiUrl() {
+        try {
+            return this.tracker.config?.apiUrl || 'https://api.grainql.com';
+        }
+        catch {
+            return 'https://api.grainql.com';
+        }
+    }
+    /**
+     * Get tenant ID from tracker configuration
+     */
+    async getTenantId() {
+        try {
+            return this.tracker.config?.tenantId;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Get auth headers from tracker
+     */
+    async getAuthHeaders() {
+        try {
+            if (typeof this.tracker.getAuthHeaders === 'function') {
+                return await this.tracker.getAuthHeaders();
+            }
+            return {};
+        }
+        catch {
+            return {};
+        }
     }
     /**
      * Setup click event tracking
@@ -151,7 +341,7 @@ class HeatmapTrackingManager {
                     return;
                 }
                 const scrollData = {
-                    pageUrl: window.location.href,
+                    pageUrl: this.normalizeUrl(window.location.href),
                     viewportSection: this.currentScrollState.viewportSection,
                     scrollDepthPx: scrollY,
                     durationMs: duration,
@@ -192,7 +382,7 @@ class HeatmapTrackingManager {
                 const duration = currentTime - this.currentScrollState.entryTime;
                 if (duration > 100) {
                     const scrollData = {
-                        pageUrl: window.location.href,
+                        pageUrl: this.normalizeUrl(window.location.href),
                         viewportSection: this.currentScrollState.viewportSection,
                         scrollDepthPx: this.currentScrollState.scrollDepthPx,
                         durationMs: duration,
@@ -220,8 +410,23 @@ class HeatmapTrackingManager {
         const element = event.target;
         if (!element)
             return;
-        const pageUrl = window.location.href;
+        const pageUrl = this.normalizeUrl(window.location.href);
         const xpath = this.generateXPath(element);
+        // Generate CSS selector for element-relative positioning
+        const selector = this.generateCSSSelector(element);
+        // Calculate element-relative coordinates
+        let relX;
+        let relY;
+        try {
+            const rect = element.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+                relX = Math.max(0, Math.min(1, (event.clientX - rect.left) / rect.width));
+                relY = Math.max(0, Math.min(1, (event.clientY - rect.top) / rect.height));
+            }
+        }
+        catch (error) {
+            this.log('Failed to calculate relative coordinates:', error);
+        }
         // Get viewport coordinates
         const viewportX = Math.round(event.clientX);
         const viewportY = Math.round(event.clientY);
@@ -233,6 +438,9 @@ class HeatmapTrackingManager {
         const clickData = {
             pageUrl,
             xpath,
+            selector,
+            relX,
+            relY,
             viewportX,
             viewportY,
             pageX,
@@ -248,6 +456,9 @@ class HeatmapTrackingManager {
             this.tracker.trackSystemEvent('_grain_heatmap_click', {
                 page_url: clickData.pageUrl,
                 xpath: clickData.xpath,
+                selector: clickData.selector,
+                rel_x: clickData.relX,
+                rel_y: clickData.relY,
                 viewport_x: clickData.viewportX,
                 viewport_y: clickData.viewportY,
                 page_x: clickData.pageX,
@@ -291,7 +502,7 @@ class HeatmapTrackingManager {
             // Only record if duration is meaningful (> 100ms)
             if (duration > 100) {
                 const scrollData = {
-                    pageUrl: window.location.href,
+                    pageUrl: this.normalizeUrl(window.location.href),
                     viewportSection: this.currentScrollState.viewportSection,
                     scrollDepthPx: this.currentScrollState.scrollDepthPx,
                     durationMs: duration,
@@ -319,6 +530,50 @@ class HeatmapTrackingManager {
         // Check if we should flush
         this.considerBatchFlush();
     }
+    /**
+     * Generate CSS selector for an element (for element-relative positioning)
+     */
+    generateCSSSelector(element) {
+        if (!element)
+            return '';
+        // Prefer ID if available
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        // Try data attributes
+        const dataAttrs = Array.from(element.attributes).filter(attr => attr.name.startsWith('data-'));
+        if (dataAttrs.length > 0) {
+            const attr = dataAttrs[0];
+            return `${element.tagName.toLowerCase()}[${attr.name}="${attr.value}"]`;
+        }
+        // Try class names (pick first meaningful class)
+        if (element.className && typeof element.className === 'string') {
+            const classes = element.className.split(' ').filter(c => c && !c.match(/^(active|hover|focus)/));
+            if (classes.length > 0) {
+                return `${element.tagName.toLowerCase()}.${classes[0]}`;
+            }
+        }
+        // Fall back to nth-child path
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            if (current.parentElement) {
+                const siblings = Array.from(current.parentElement.children);
+                const sameTagSiblings = siblings.filter(s => s.tagName === current.tagName);
+                if (sameTagSiblings.length > 1) {
+                    const index = sameTagSiblings.indexOf(current) + 1;
+                    selector += `:nth-child(${index})`;
+                }
+            }
+            path.unshift(selector);
+            current = current.parentElement;
+            // Limit path depth to avoid overly long selectors
+            if (path.length >= 5)
+                break;
+        }
+        return path.join(' > ');
+    }
     /**
      * Generate XPath for an element
      */
@@ -380,6 +635,9 @@ class HeatmapTrackingManager {
                 this.tracker.trackSystemEvent('_grain_heatmap_click', {
                     page_url: clickData.pageUrl,
                     xpath: clickData.xpath,
+                    selector: clickData.selector,
+                    rel_x: clickData.relX,
+                    rel_y: clickData.relY,
                     viewport_x: clickData.viewportX,
                     viewport_y: clickData.viewportY,
                     page_x: clickData.pageX,
@@ -425,6 +683,9 @@ class HeatmapTrackingManager {
                 this.tracker.trackSystemEvent('_grain_heatmap_click', {
                     page_url: clickData.pageUrl,
                     xpath: clickData.xpath,
+                    selector: clickData.selector,
+                    rel_x: clickData.relX,
+                    rel_y: clickData.relY,
                     viewport_x: clickData.viewportX,
                     viewport_y: clickData.viewportY,
                     page_x: clickData.pageX,