@grainql/analytics-web 3.2.0 → 3.2.2

package/dist/heatmap-tracking.js

@@ -65,8 +65,12 @@ class HeatmapTrackingManager {
         // Snapshot capture state
         this.snapshotCaptured = false;
         this.snapshotEnabled = false;
+        // Device type detection
+        this.deviceType = 'desktop';
         this.tracker = tracker;
         this.options = { ...DEFAULT_OPTIONS, ...options };
+        // Detect device type on initialization
+        this.deviceType = this.detectDeviceType();
         // Initialize attention quality manager
         this.attentionQuality = new attention_quality_1.AttentionQualityManager(tracker.getActivityDetector(), {
             maxSectionDuration: 9000, // 9 seconds per viewport section
@@ -109,6 +113,34 @@ class HeatmapTrackingManager {
     /**
      * Check remote config for snapshot capture enablement
      */
+    /**
+     * Detect device type based on viewport width and user agent
+     * Mobile: width < 768px OR mobile user agent
+     * Desktop: width >= 768px AND non-mobile user agent
+     */
+    detectDeviceType() {
+        if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+            return 'desktop'; // SSR default
+        }
+        // Check viewport width
+        const width = window.innerWidth || window.screen?.width || 0;
+        const isMobileWidth = width < 768;
+        // Check user agent for mobile indicators
+        const userAgent = navigator.userAgent.toLowerCase();
+        const mobileKeywords = [
+            'mobile',
+            'android',
+            'iphone',
+            'ipad',
+            'ipod',
+            'blackberry',
+            'windows phone',
+            'webos',
+        ];
+        const isMobileUserAgent = mobileKeywords.some((keyword) => userAgent.includes(keyword));
+        // Device is mobile if either width OR user agent indicates mobile
+        return isMobileWidth || isMobileUserAgent ? 'mobile' : 'desktop';
+    }
     /**
      * Normalize URL by removing query params and hash, and stripping www prefix
      * This ensures heatmap data is aggregated by page, not by URL variations
@@ -147,6 +179,12 @@ class HeatmapTrackingManager {
     async captureSnapshot() {
         if (this.snapshotCaptured || !this.snapshotEnabled)
             return;
+        // Check daily snapshot limits before capturing
+        if (!this.canUploadSnapshot()) {
+            this.log('Snapshot upload limit reached or URL already captured today');
+            this.snapshotCaptured = true; // Prevent retry
+            return;
+        }
         try {
             this.log('Capturing DOM snapshot...');
             // Dynamically import rrweb-snapshot (only if enabled)
@@ -205,7 +243,8 @@ class HeatmapTrackingManager {
                     sessionId,
                     pageUrl,
                     snapshot: JSON.stringify(snapshot),
-                    timestamp: Date.now()
+                    timestamp: Date.now(),
+                    deviceType: this.deviceType
                 })
             });
             if (!response.ok) {
@@ -213,11 +252,97 @@ class HeatmapTrackingManager {
             }
             const result = await response.json();
             this.log('Snapshot uploaded successfully:', result);
+            // Record successful upload
+            this.recordSnapshotUpload(pageUrl);
         }
         catch (error) {
             this.log('Failed to upload snapshot:', error);
         }
     }
+    /**
+     * Check if snapshot can be uploaded based on daily limits
+     * - Max 5 snapshots per user per day
+     * - Same URL (without query params) can't be uploaded twice in same day
+     */
+    canUploadSnapshot() {
+        if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+            return true; // Allow in SSR/non-browser environments
+        }
+        try {
+            const pageUrl = this.normalizeUrl(window.location.href);
+            const urlWithoutQuery = this.stripQueryParams(pageUrl);
+            const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+            const storageKey = '_grain_snapshots';
+            // Get existing snapshot records
+            const stored = localStorage.getItem(storageKey);
+            let snapshots = stored ? JSON.parse(stored) : [];
+            // Clean up old entries (older than 2 days)
+            const twoDaysAgo = Date.now() - (2 * 24 * 60 * 60 * 1000);
+            snapshots = snapshots.filter(s => s.timestamp > twoDaysAgo);
+            // Get today's snapshots
+            const todaySnapshots = snapshots.filter(s => s.date === today);
+            // Check daily limit (5 per day)
+            if (todaySnapshots.length >= 5) {
+                this.log('Daily snapshot limit reached (5/5)');
+                return false;
+            }
+            // Check if this URL (without query params) was already uploaded today
+            const urlAlreadyUploaded = todaySnapshots.some(s => this.stripQueryParams(s.url) === urlWithoutQuery);
+            if (urlAlreadyUploaded) {
+                this.log(`Snapshot for ${urlWithoutQuery} already uploaded today`);
+                return false;
+            }
+            this.log(`Snapshot upload allowed (${todaySnapshots.length}/5 today)`);
+            return true;
+        }
+        catch (error) {
+            this.log('Error checking snapshot limits:', error);
+            return true; // Allow on error to not break functionality
+        }
+    }
+    /**
+     * Record a successful snapshot upload
+     */
+    recordSnapshotUpload(pageUrl) {
+        if (typeof window === 'undefined' || typeof localStorage === 'undefined') {
+            return;
+        }
+        try {
+            const today = new Date().toISOString().split('T')[0];
+            const storageKey = '_grain_snapshots';
+            // Get existing records
+            const stored = localStorage.getItem(storageKey);
+            let snapshots = stored ? JSON.parse(stored) : [];
+            // Add new record
+            snapshots.push({
+                url: pageUrl,
+                date: today,
+                timestamp: Date.now()
+            });
+            // Clean up old entries (older than 2 days)
+            const twoDaysAgo = Date.now() - (2 * 24 * 60 * 60 * 1000);
+            snapshots = snapshots.filter(s => s.timestamp > twoDaysAgo);
+            // Save back to localStorage
+            localStorage.setItem(storageKey, JSON.stringify(snapshots));
+            this.log(`Snapshot upload recorded: ${snapshots.filter(s => s.date === today).length}/5 today`);
+        }
+        catch (error) {
+            this.log('Error recording snapshot upload:', error);
+        }
+    }
+    /**
+     * Strip query parameters from URL for comparison
+     */
+    stripQueryParams(url) {
+        try {
+            const urlObj = new URL(url);
+            return `${urlObj.origin}${urlObj.pathname}`;
+        }
+        catch {
+            // If URL parsing fails, remove everything after ?
+            return url.split('?')[0];
+        }
+    }
     /**
      * Get API URL from tracker configuration
      */
@@ -349,6 +474,7 @@ class HeatmapTrackingManager {
                     exitTimestamp: currentTime,
                     pageHeight,
                     viewportHeight,
+                    deviceType: this.deviceType,
                 };
                 // Send immediately using beacon to ensure delivery
                 this.tracker.trackSystemEvent('_grain_heatmap_scroll', {
@@ -360,6 +486,7 @@ class HeatmapTrackingManager {
                     exit_timestamp: scrollData.exitTimestamp,
                     page_height: scrollData.pageHeight,
                     viewport_height: scrollData.viewportHeight,
+                    device_type: scrollData.deviceType,
                     is_split: true, // Flag to indicate periodic tracking, not final exit
                 }, { flush: true });
                 // Update attention quality duration tracker
@@ -390,6 +517,7 @@ class HeatmapTrackingManager {
                         exitTimestamp: currentTime,
                         pageHeight: document.documentElement.scrollHeight,
                         viewportHeight: window.innerHeight,
+                        deviceType: this.deviceType,
                     };
                     this.pendingScrolls.push(scrollData);
                 }
@@ -448,6 +576,7 @@ class HeatmapTrackingManager {
             elementTag,
             elementText: elementText || undefined,
             timestamp: Date.now(),
+            deviceType: this.deviceType,
         };
         // Check if this is a navigation link
         const isNavigationLink = element instanceof HTMLAnchorElement && element.href;
@@ -466,6 +595,7 @@ class HeatmapTrackingManager {
                 element_tag: clickData.elementTag,
                 element_text: clickData.elementText,
                 timestamp: clickData.timestamp,
+                device_type: clickData.deviceType,
             }, { flush: true });
         }
         else {
@@ -510,6 +640,7 @@ class HeatmapTrackingManager {
                     exitTimestamp: currentTime,
                     pageHeight,
                     viewportHeight,
+                    deviceType: this.deviceType,
                 };
                 this.pendingScrolls.push(scrollData);
             }
@@ -645,6 +776,7 @@ class HeatmapTrackingManager {
                     element_tag: clickData.elementTag,
                     element_text: clickData.elementText,
                     timestamp: clickData.timestamp,
+                    device_type: clickData.deviceType,
                 });
             }
             this.pendingClicks = [];
@@ -661,6 +793,7 @@ class HeatmapTrackingManager {
                     exit_timestamp: scrollData.exitTimestamp,
                     page_height: scrollData.pageHeight,
                     viewport_height: scrollData.viewportHeight,
+                    device_type: scrollData.deviceType,
                 });
             }
             this.pendingScrolls = [];
@@ -693,6 +826,7 @@ class HeatmapTrackingManager {
                     element_tag: clickData.elementTag,
                     element_text: clickData.elementText,
                     timestamp: clickData.timestamp,
+                    device_type: clickData.deviceType,
                 }, { flush: true });
             }
             this.pendingClicks = [];
@@ -709,6 +843,7 @@ class HeatmapTrackingManager {
                     exit_timestamp: scrollData.exitTimestamp,
                     page_height: scrollData.pageHeight,
                     viewport_height: scrollData.viewportHeight,
+                    device_type: scrollData.deviceType,
                 }, { flush: true });
             }
             this.pendingScrolls = [];

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v3.2.0 | MIT License | Development Build */
+/* Grain Analytics Web SDK v3.2.2 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;
@@ -5851,8 +5851,11 @@ var Grain = (() => {
           // Snapshot capture state
           this.snapshotCaptured = false;
           this.snapshotEnabled = false;
+          // Device type detection
+          this.deviceType = "desktop";
           this.tracker = tracker;
           this.options = { ...DEFAULT_OPTIONS2, ...options };
+          this.deviceType = this.detectDeviceType();
           this.attentionQuality = new AttentionQualityManager(
             tracker.getActivityDetector(),
             {
@@ -5892,6 +5895,33 @@ var Grain = (() => {
         /**
          * Check remote config for snapshot capture enablement
          */
+        /**
+         * Detect device type based on viewport width and user agent
+         * Mobile: width < 768px OR mobile user agent
+         * Desktop: width >= 768px AND non-mobile user agent
+         */
+        detectDeviceType() {
+          if (typeof window === "undefined" || typeof navigator === "undefined") {
+            return "desktop";
+          }
+          const width = window.innerWidth || window.screen?.width || 0;
+          const isMobileWidth = width < 768;
+          const userAgent = navigator.userAgent.toLowerCase();
+          const mobileKeywords = [
+            "mobile",
+            "android",
+            "iphone",
+            "ipad",
+            "ipod",
+            "blackberry",
+            "windows phone",
+            "webos"
+          ];
+          const isMobileUserAgent = mobileKeywords.some(
+            (keyword) => userAgent.includes(keyword)
+          );
+          return isMobileWidth || isMobileUserAgent ? "mobile" : "desktop";
+        }
         /**
          * Normalize URL by removing query params and hash, and stripping www prefix
          * This ensures heatmap data is aggregated by page, not by URL variations
@@ -5925,6 +5955,11 @@ var Grain = (() => {
         async captureSnapshot() {
           if (this.snapshotCaptured || !this.snapshotEnabled)
             return;
+          if (!this.canUploadSnapshot()) {
+            this.log("Snapshot upload limit reached or URL already captured today");
+            this.snapshotCaptured = true;
+            return;
+          }
           try {
             this.log("Capturing DOM snapshot...");
             const rrwebSnapshot = await Promise.resolve().then(() => (init_rrweb_snapshot(), rrweb_snapshot_exports));
@@ -5974,7 +6009,8 @@ var Grain = (() => {
                   sessionId,
                   pageUrl,
                   snapshot: JSON.stringify(snapshot2),
-                  timestamp: Date.now()
+                  timestamp: Date.now(),
+                  deviceType: this.deviceType
                 })
               }
             );
@@ -5983,10 +6019,84 @@ var Grain = (() => {
             }
             const result2 = await response.json();
             this.log("Snapshot uploaded successfully:", result2);
+            this.recordSnapshotUpload(pageUrl);
           } catch (error) {
             this.log("Failed to upload snapshot:", error);
           }
         }
+        /**
+         * Check if snapshot can be uploaded based on daily limits
+         * - Max 5 snapshots per user per day
+         * - Same URL (without query params) can't be uploaded twice in same day
+         */
+        canUploadSnapshot() {
+          if (typeof window === "undefined" || typeof localStorage === "undefined") {
+            return true;
+          }
+          try {
+            const pageUrl = this.normalizeUrl(window.location.href);
+            const urlWithoutQuery = this.stripQueryParams(pageUrl);
+            const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+            const storageKey = "_grain_snapshots";
+            const stored = localStorage.getItem(storageKey);
+            let snapshots = stored ? JSON.parse(stored) : [];
+            const twoDaysAgo = Date.now() - 2 * 24 * 60 * 60 * 1e3;
+            snapshots = snapshots.filter((s) => s.timestamp > twoDaysAgo);
+            const todaySnapshots = snapshots.filter((s) => s.date === today);
+            if (todaySnapshots.length >= 5) {
+              this.log("Daily snapshot limit reached (5/5)");
+              return false;
+            }
+            const urlAlreadyUploaded = todaySnapshots.some(
+              (s) => this.stripQueryParams(s.url) === urlWithoutQuery
+            );
+            if (urlAlreadyUploaded) {
+              this.log(`Snapshot for ${urlWithoutQuery} already uploaded today`);
+              return false;
+            }
+            this.log(`Snapshot upload allowed (${todaySnapshots.length}/5 today)`);
+            return true;
+          } catch (error) {
+            this.log("Error checking snapshot limits:", error);
+            return true;
+          }
+        }
+        /**
+         * Record a successful snapshot upload
+         */
+        recordSnapshotUpload(pageUrl) {
+          if (typeof window === "undefined" || typeof localStorage === "undefined") {
+            return;
+          }
+          try {
+            const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+            const storageKey = "_grain_snapshots";
+            const stored = localStorage.getItem(storageKey);
+            let snapshots = stored ? JSON.parse(stored) : [];
+            snapshots.push({
+              url: pageUrl,
+              date: today,
+              timestamp: Date.now()
+            });
+            const twoDaysAgo = Date.now() - 2 * 24 * 60 * 60 * 1e3;
+            snapshots = snapshots.filter((s) => s.timestamp > twoDaysAgo);
+            localStorage.setItem(storageKey, JSON.stringify(snapshots));
+            this.log(`Snapshot upload recorded: ${snapshots.filter((s) => s.date === today).length}/5 today`);
+          } catch (error) {
+            this.log("Error recording snapshot upload:", error);
+          }
+        }
+        /**
+         * Strip query parameters from URL for comparison
+         */
+        stripQueryParams(url) {
+          try {
+            const urlObj = new URL(url);
+            return `${urlObj.origin}${urlObj.pathname}`;
+          } catch {
+            return url.split("?")[0];
+          }
+        }
         /**
          * Get API URL from tracker configuration
          */
@@ -6102,7 +6212,8 @@ var Grain = (() => {
                 entryTimestamp: this.currentScrollState.entryTime,
                 exitTimestamp: currentTime,
                 pageHeight,
-                viewportHeight
+                viewportHeight,
+                deviceType: this.deviceType
               };
               this.tracker.trackSystemEvent("_grain_heatmap_scroll", {
                 page_url: scrollData.pageUrl,
@@ -6113,6 +6224,7 @@ var Grain = (() => {
                 exit_timestamp: scrollData.exitTimestamp,
                 page_height: scrollData.pageHeight,
                 viewport_height: scrollData.viewportHeight,
+                device_type: scrollData.deviceType,
                 is_split: true
                 // Flag to indicate periodic tracking, not final exit
               }, { flush: true });
@@ -6140,7 +6252,8 @@ var Grain = (() => {
                   entryTimestamp: this.currentScrollState.entryTime,
                   exitTimestamp: currentTime,
                   pageHeight: document.documentElement.scrollHeight,
-                  viewportHeight: window.innerHeight
+                  viewportHeight: window.innerHeight,
+                  deviceType: this.deviceType
                 };
                 this.pendingScrolls.push(scrollData);
               }
@@ -6189,7 +6302,8 @@ var Grain = (() => {
             pageY,
             elementTag,
             elementText: elementText || void 0,
-            timestamp: Date.now()
+            timestamp: Date.now(),
+            deviceType: this.deviceType
           };
           const isNavigationLink = element instanceof HTMLAnchorElement && element.href;
           if (isNavigationLink) {
@@ -6205,7 +6319,8 @@ var Grain = (() => {
               page_y: clickData.pageY,
               element_tag: clickData.elementTag,
               element_text: clickData.elementText,
-              timestamp: clickData.timestamp
+              timestamp: clickData.timestamp,
+              device_type: clickData.deviceType
             }, { flush: true });
           } else {
             this.pendingClicks.push(clickData);
@@ -6240,7 +6355,8 @@ var Grain = (() => {
                 entryTimestamp: this.currentScrollState.entryTime,
                 exitTimestamp: currentTime,
                 pageHeight,
-                viewportHeight
+                viewportHeight,
+                deviceType: this.deviceType
               };
               this.pendingScrolls.push(scrollData);
             }
@@ -6360,7 +6476,8 @@ var Grain = (() => {
                 page_y: clickData.pageY,
                 element_tag: clickData.elementTag,
                 element_text: clickData.elementText,
-                timestamp: clickData.timestamp
+                timestamp: clickData.timestamp,
+                device_type: clickData.deviceType
               });
             }
             this.pendingClicks = [];
@@ -6375,7 +6492,8 @@ var Grain = (() => {
                 entry_timestamp: scrollData.entryTimestamp,
                 exit_timestamp: scrollData.exitTimestamp,
                 page_height: scrollData.pageHeight,
-                viewport_height: scrollData.viewportHeight
+                viewport_height: scrollData.viewportHeight,
+                device_type: scrollData.deviceType
               });
             }
             this.pendingScrolls = [];
@@ -6403,7 +6521,8 @@ var Grain = (() => {
                 page_y: clickData.pageY,
                 element_tag: clickData.elementTag,
                 element_text: clickData.elementText,
-                timestamp: clickData.timestamp
+                timestamp: clickData.timestamp,
+                device_type: clickData.deviceType
               }, { flush: true });
             }
             this.pendingClicks = [];
@@ -6418,7 +6537,8 @@ var Grain = (() => {
                 entry_timestamp: scrollData.entryTimestamp,
                 exit_timestamp: scrollData.exitTimestamp,
                 page_height: scrollData.pageHeight,
-                viewport_height: scrollData.viewportHeight
+                viewport_height: scrollData.viewportHeight,
+                device_type: scrollData.deviceType
               }, { flush: true });
             }
             this.pendingScrolls = [];