@grainql/analytics-web 2.5.0 → 2.5.4

package/dist/index.js

@@ -417,10 +417,46 @@ class GrainAnalytics {
         }
     }
     formatEvent(event) {
+        const properties = event.properties || {};
+        // Auto-enrich events with session-level attribution properties
+        // This ensures UTM parameters and attribution data are available on ALL events, not just page_view
+        if (!this.config.disableAutoProperties && typeof window !== 'undefined') {
+            const hasConsent = this.consentManager.hasConsent('analytics');
+            // Only enrich if not a system event (they handle their own properties)
+            const isSystemEvent = event.eventName.startsWith('_grain_');
+            if (!isSystemEvent && hasConsent) {
+                // Get session UTM parameters
+                const sessionUTMs = (0, attribution_1.getSessionUTMParameters)();
+                if (sessionUTMs) {
+                    if (sessionUTMs.utm_source)
+                        properties.utm_source = sessionUTMs.utm_source;
+                    if (sessionUTMs.utm_medium)
+                        properties.utm_medium = sessionUTMs.utm_medium;
+                    if (sessionUTMs.utm_campaign)
+                        properties.utm_campaign = sessionUTMs.utm_campaign;
+                    if (sessionUTMs.utm_term)
+                        properties.utm_term = sessionUTMs.utm_term;
+                    if (sessionUTMs.utm_content)
+                        properties.utm_content = sessionUTMs.utm_content;
+                }
+                // Get first-touch attribution
+                const firstTouch = (0, attribution_1.getFirstTouchAttribution)(this.config.tenantId);
+                if (firstTouch) {
+                    properties.first_touch_source = firstTouch.source;
+                    properties.first_touch_medium = firstTouch.medium;
+                    properties.first_touch_campaign = firstTouch.campaign;
+                    properties.first_touch_referrer_category = firstTouch.referrer_category;
+                }
+                // Add session ID if not already present
+                if (!properties.session_id) {
+                    properties.session_id = this.getSessionId();
+                }
+            }
+        }
         return {
             eventName: event.eventName,
             userId: event.userId || this.getEffectiveUserIdInternal(),
-            properties: event.properties || {},
+            properties,
         };
     }
     async getAuthHeaders() {
@@ -526,9 +562,12 @@ class GrainAnalytics {
         try {
             const headers = await this.getAuthHeaders();
             const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
-            const body = JSON.stringify({ events });
-            // Try beacon API first (more reliable for page unload)
-            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+            // Send events array directly (not wrapped in object) to match API expectation
+            const body = JSON.stringify(events);
+            // Beacon API doesn't support custom headers, so only use it for unauthenticated requests
+            const needsAuth = this.config.authStrategy !== 'NONE';
+            // Try beacon API first (more reliable for page unload, but only if no auth needed)
+            if (!needsAuth && typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
                 const blob = new Blob([body], { type: 'application/json' });
                 const success = navigator.sendBeacon(url, blob);
                 if (success) {
@@ -536,7 +575,7 @@ class GrainAnalytics {
                     return;
                 }
             }
-            // Fallback to fetch with keepalive
+            // Use fetch with keepalive (supports headers and works during page unload)
             await fetch(url, {
                 method: 'POST',
                 headers,
@@ -642,6 +681,7 @@ class GrainAnalytics {
      */
     async initializeAutoTracking() {
         try {
+            this.log('Initializing auto-tracking...');
             // Fetch remote config to get auto-tracking configuration
             const userId = this.globalUserId || this.persistentAnonymousUserId || this.generateUUID();
             const currentUrl = typeof window !== 'undefined' ? window.location.href : '';
@@ -654,16 +694,24 @@ class GrainAnalytics {
             };
             const headers = await this.getAuthHeaders();
             const url = `${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/config/configurations`;
+            this.log('Fetching auto-tracking config from:', url);
             const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(request),
             });
-            if (response.ok) {
-                const configResponse = await response.json();
-                if (configResponse.autoTrackingConfig) {
-                    this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
-                }
+            if (!response.ok) {
+                this.log('Failed to fetch auto-tracking config:', response.status, response.statusText);
+                return;
+            }
+            const configResponse = await response.json();
+            this.log('Received config response:', configResponse);
+            if (configResponse.autoTrackingConfig) {
+                this.log('Auto-tracking config found:', configResponse.autoTrackingConfig);
+                this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
+            }
+            else {
+                this.log('No auto-tracking config in response');
             }
         }
         catch (error) {
@@ -675,27 +723,33 @@ class GrainAnalytics {
      * Setup auto-tracking managers
      */
     setupAutoTrackingManagers(config) {
+        this.log('Setting up auto-tracking managers...', config);
         // Lazy load the managers to avoid bundling them if not needed
-        Promise.resolve().then(() => __importStar(require('./interaction-tracking'))).then(({ InteractionTrackingManager }) => {
-            try {
-                if (config.interactions && config.interactions.length > 0) {
+        if (config.interactions && config.interactions.length > 0) {
+            this.log('Loading interaction tracking module for', config.interactions.length, 'interactions');
+            Promise.resolve().then(() => __importStar(require('./interaction-tracking'))).then(({ InteractionTrackingManager }) => {
+                try {
                     this.interactionTrackingManager = new InteractionTrackingManager(this, config.interactions, {
                         debug: this.config.debug,
                         enableMutationObserver: true,
                         mutationDebounceDelay: 500,
                     });
-                    this.log('Interaction tracking initialized with', config.interactions.length, 'interactions');
+                    this.log('✅ Interaction tracking initialized successfully with', config.interactions.length, 'interactions');
                 }
-            }
-            catch (error) {
-                this.log('Failed to initialize interaction tracking:', error);
-            }
-        }).catch((error) => {
-            this.log('Failed to load interaction tracking module:', error);
-        });
-        Promise.resolve().then(() => __importStar(require('./section-tracking'))).then(({ SectionTrackingManager }) => {
-            try {
-                if (config.sections && config.sections.length > 0) {
+                catch (error) {
+                    this.log('❌ Failed to initialize interaction tracking:', error);
+                }
+            }).catch((error) => {
+                this.log('❌ Failed to load interaction tracking module:', error);
+            });
+        }
+        else {
+            this.log('No interactions configured for auto-tracking');
+        }
+        if (config.sections && config.sections.length > 0) {
+            this.log('Loading section tracking module for', config.sections.length, 'sections');
+            Promise.resolve().then(() => __importStar(require('./section-tracking'))).then(({ SectionTrackingManager }) => {
+                try {
                     this.sectionTrackingManager = new SectionTrackingManager(this, config.sections, {
                         minDwellTime: 1000,
                         scrollVelocityThreshold: 500,
@@ -704,15 +758,18 @@ class GrainAnalytics {
                         batchDelay: 2000,
                         debug: this.config.debug,
                     });
-                    this.log('Section tracking initialized with', config.sections.length, 'sections');
+                    this.log('✅ Section tracking initialized successfully with', config.sections.length, 'sections');
                 }
-            }
-            catch (error) {
-                this.log('Failed to initialize section tracking:', error);
-            }
-        }).catch((error) => {
-            this.log('Failed to load section tracking module:', error);
-        });
+                catch (error) {
+                    this.log('❌ Failed to initialize section tracking:', error);
+                }
+            }).catch((error) => {
+                this.log('❌ Failed to load section tracking module:', error);
+            });
+        }
+        else {
+            this.log('No sections configured for auto-tracking');
+        }
     }
     /**
      * Track session start event

package/dist/index.mjs

@@ -7,7 +7,7 @@ import { setCookie, getCookie, areCookiesEnabled } from './cookies.js';
 import { ActivityDetector } from './activity.js';
 import { HeartbeatManager } from './heartbeat.js';
 import { PageTrackingManager } from './page-tracking.js';
-import { categorizeReferrer, parseUTMParameters, getOrCreateFirstTouchAttribution, getSessionUTMParameters, } from './attribution.js';
+import { categorizeReferrer, parseUTMParameters, getOrCreateFirstTouchAttribution, getSessionUTMParameters, getFirstTouchAttribution, } from './attribution.js';
 export { categorizeReferrer, parseUTMParameters };
 // Re-export timezone-country utilities
 export { getCountry, getCountryCodeFromTimezone, getState } from './countries.js';
@@ -376,10 +376,46 @@ export class GrainAnalytics {
         }
     }
     formatEvent(event) {
+        const properties = event.properties || {};
+        // Auto-enrich events with session-level attribution properties
+        // This ensures UTM parameters and attribution data are available on ALL events, not just page_view
+        if (!this.config.disableAutoProperties && typeof window !== 'undefined') {
+            const hasConsent = this.consentManager.hasConsent('analytics');
+            // Only enrich if not a system event (they handle their own properties)
+            const isSystemEvent = event.eventName.startsWith('_grain_');
+            if (!isSystemEvent && hasConsent) {
+                // Get session UTM parameters
+                const sessionUTMs = getSessionUTMParameters();
+                if (sessionUTMs) {
+                    if (sessionUTMs.utm_source)
+                        properties.utm_source = sessionUTMs.utm_source;
+                    if (sessionUTMs.utm_medium)
+                        properties.utm_medium = sessionUTMs.utm_medium;
+                    if (sessionUTMs.utm_campaign)
+                        properties.utm_campaign = sessionUTMs.utm_campaign;
+                    if (sessionUTMs.utm_term)
+                        properties.utm_term = sessionUTMs.utm_term;
+                    if (sessionUTMs.utm_content)
+                        properties.utm_content = sessionUTMs.utm_content;
+                }
+                // Get first-touch attribution
+                const firstTouch = getFirstTouchAttribution(this.config.tenantId);
+                if (firstTouch) {
+                    properties.first_touch_source = firstTouch.source;
+                    properties.first_touch_medium = firstTouch.medium;
+                    properties.first_touch_campaign = firstTouch.campaign;
+                    properties.first_touch_referrer_category = firstTouch.referrer_category;
+                }
+                // Add session ID if not already present
+                if (!properties.session_id) {
+                    properties.session_id = this.getSessionId();
+                }
+            }
+        }
         return {
             eventName: event.eventName,
             userId: event.userId || this.getEffectiveUserIdInternal(),
-            properties: event.properties || {},
+            properties,
         };
     }
     async getAuthHeaders() {
@@ -485,9 +521,12 @@ export class GrainAnalytics {
         try {
             const headers = await this.getAuthHeaders();
             const url = `${this.config.apiUrl}/v1/events/${encodeURIComponent(this.config.tenantId)}/multi`;
-            const body = JSON.stringify({ events });
-            // Try beacon API first (more reliable for page unload)
-            if (typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
+            // Send events array directly (not wrapped in object) to match API expectation
+            const body = JSON.stringify(events);
+            // Beacon API doesn't support custom headers, so only use it for unauthenticated requests
+            const needsAuth = this.config.authStrategy !== 'NONE';
+            // Try beacon API first (more reliable for page unload, but only if no auth needed)
+            if (!needsAuth && typeof navigator !== 'undefined' && 'sendBeacon' in navigator) {
                 const blob = new Blob([body], { type: 'application/json' });
                 const success = navigator.sendBeacon(url, blob);
                 if (success) {
@@ -495,7 +534,7 @@ export class GrainAnalytics {
                     return;
                 }
             }
-            // Fallback to fetch with keepalive
+            // Use fetch with keepalive (supports headers and works during page unload)
             await fetch(url, {
                 method: 'POST',
                 headers,
@@ -601,6 +640,7 @@ export class GrainAnalytics {
      */
     async initializeAutoTracking() {
         try {
+            this.log('Initializing auto-tracking...');
             // Fetch remote config to get auto-tracking configuration
             const userId = this.globalUserId || this.persistentAnonymousUserId || this.generateUUID();
             const currentUrl = typeof window !== 'undefined' ? window.location.href : '';
@@ -613,16 +653,24 @@ export class GrainAnalytics {
             };
             const headers = await this.getAuthHeaders();
             const url = `${this.config.apiUrl}/v1/client/${encodeURIComponent(this.config.tenantId)}/config/configurations`;
+            this.log('Fetching auto-tracking config from:', url);
             const response = await fetch(url, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(request),
             });
-            if (response.ok) {
-                const configResponse = await response.json();
-                if (configResponse.autoTrackingConfig) {
-                    this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
-                }
+            if (!response.ok) {
+                this.log('Failed to fetch auto-tracking config:', response.status, response.statusText);
+                return;
+            }
+            const configResponse = await response.json();
+            this.log('Received config response:', configResponse);
+            if (configResponse.autoTrackingConfig) {
+                this.log('Auto-tracking config found:', configResponse.autoTrackingConfig);
+                this.setupAutoTrackingManagers(configResponse.autoTrackingConfig);
+            }
+            else {
+                this.log('No auto-tracking config in response');
             }
         }
         catch (error) {
@@ -634,27 +682,33 @@ export class GrainAnalytics {
      * Setup auto-tracking managers
      */
     setupAutoTrackingManagers(config) {
+        this.log('Setting up auto-tracking managers...', config);
         // Lazy load the managers to avoid bundling them if not needed
-        import('./interaction-tracking').then(({ InteractionTrackingManager }) => {
-            try {
-                if (config.interactions && config.interactions.length > 0) {
+        if (config.interactions && config.interactions.length > 0) {
+            this.log('Loading interaction tracking module for', config.interactions.length, 'interactions');
+            import('./interaction-tracking').then(({ InteractionTrackingManager }) => {
+                try {
                     this.interactionTrackingManager = new InteractionTrackingManager(this, config.interactions, {
                         debug: this.config.debug,
                         enableMutationObserver: true,
                         mutationDebounceDelay: 500,
                     });
-                    this.log('Interaction tracking initialized with', config.interactions.length, 'interactions');
+                    this.log('✅ Interaction tracking initialized successfully with', config.interactions.length, 'interactions');
                 }
-            }
-            catch (error) {
-                this.log('Failed to initialize interaction tracking:', error);
-            }
-        }).catch((error) => {
-            this.log('Failed to load interaction tracking module:', error);
-        });
-        import('./section-tracking').then(({ SectionTrackingManager }) => {
-            try {
-                if (config.sections && config.sections.length > 0) {
+                catch (error) {
+                    this.log('❌ Failed to initialize interaction tracking:', error);
+                }
+            }).catch((error) => {
+                this.log('❌ Failed to load interaction tracking module:', error);
+            });
+        }
+        else {
+            this.log('No interactions configured for auto-tracking');
+        }
+        if (config.sections && config.sections.length > 0) {
+            this.log('Loading section tracking module for', config.sections.length, 'sections');
+            import('./section-tracking').then(({ SectionTrackingManager }) => {
+                try {
                     this.sectionTrackingManager = new SectionTrackingManager(this, config.sections, {
                         minDwellTime: 1000,
                         scrollVelocityThreshold: 500,
@@ -663,15 +717,18 @@ export class GrainAnalytics {
                         batchDelay: 2000,
                         debug: this.config.debug,
                     });
-                    this.log('Section tracking initialized with', config.sections.length, 'sections');
+                    this.log('✅ Section tracking initialized successfully with', config.sections.length, 'sections');
                 }
-            }
-            catch (error) {
-                this.log('Failed to initialize section tracking:', error);
-            }
-        }).catch((error) => {
-            this.log('Failed to load section tracking module:', error);
-        });
+                catch (error) {
+                    this.log('❌ Failed to initialize section tracking:', error);
+                }
+            }).catch((error) => {
+                this.log('❌ Failed to load section tracking module:', error);
+            });
+        }
+        else {
+            this.log('No sections configured for auto-tracking');
+        }
     }
     /**
      * Track session start event

package/dist/interaction-tracking.d.ts

@@ -3,8 +3,11 @@
  * Automatically attaches click and focus listeners to detected interactive elements
  */
 import type { InteractionConfig } from './types/auto-tracking';
+export interface SendEventOptions {
+    flush?: boolean;
+}
 export interface InteractionTracker {
-    track(eventName: string, properties?: Record<string, unknown>): void | Promise<void>;
+    track(eventName: string, properties?: Record<string, unknown>, options?: SendEventOptions): void | Promise<void>;
     hasConsent(category: 'analytics' | 'marketing' | 'functional'): boolean;
     log(...args: unknown[]): void;
 }

package/dist/interaction-tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interaction-tracking.d.ts","sourceRoot":"","sources":["../src/interaction-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,0BAA0B;IACrC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAA6E;IACtG,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,qBAAqB,CAAuB;gBAGlD,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,iBAAiB,EAAE,EACjC,MAAM,GAAE,yBAA8B;IA0BxC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAkCjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAqB9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAmC1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,EAAE,GAAG,IAAI;IAoB3D;;OAEG;IACH,OAAO,IAAI,IAAI;CA4BhB"}
+{"version":3,"file":"interaction-tracking.d.ts","sourceRoot":"","sources":["../src/interaction-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,0BAA0B;IACrC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAA6E;IACtG,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,qBAAqB,CAAuB;gBAGlD,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,iBAAiB,EAAE,EACjC,MAAM,GAAE,yBAA8B;IA0BxC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAkCjC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuC9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyC1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IA+BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,EAAE,GAAG,IAAI;IAoB3D;;OAEG;IACH,OAAO,IAAI,IAAI;CA4BhB"}

package/dist/interaction-tracking.js

@@ -84,7 +84,9 @@ class InteractionTrackingManager {
         if (!this.tracker.hasConsent('analytics'))
             return;
         const element = event.target;
-        this.tracker.track(interaction.eventName, {
+        // Check if this is a navigation link (has href attribute)
+        const isNavigationLink = element instanceof HTMLAnchorElement && element.href;
+        const eventProperties = {
             interaction_type: 'click',
             interaction_label: interaction.label,
             interaction_description: interaction.description,
@@ -93,8 +95,23 @@ class InteractionTrackingManager {
             element_text: element.textContent?.trim().substring(0, 100),
             element_id: element.id || undefined,
             element_class: element.className || undefined,
+            ...(isNavigationLink && { href: element.href }),
             timestamp: Date.now(),
-        });
+        };
+        // If it's a navigation link, flush immediately to ensure event is sent before navigation
+        if (isNavigationLink) {
+            // Use flush option to send immediately - handle promise if returned
+            const result = this.tracker.track(interaction.eventName, eventProperties, { flush: true });
+            if (result instanceof Promise) {
+                result.catch((error) => {
+                    // Log error but don't block navigation
+                    this.log('Failed to track navigation click:', error);
+                });
+            }
+        }
+        else {
+            this.tracker.track(interaction.eventName, eventProperties);
+        }
         this.log('Tracked click interaction:', interaction.eventName);
     }
     /**
@@ -133,9 +150,14 @@ class InteractionTrackingManager {
             this.xpathCache.delete(xpath);
         }
         try {
-            const result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+            // Strip the xpath= prefix if present (from Stagehand selectors)
+            let cleanXpath = xpath;
+            if (xpath.startsWith('xpath=')) {
+                cleanXpath = xpath.substring(6); // Remove 'xpath=' prefix
+            }
+            const result = document.evaluate(cleanXpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
             const element = result.singleNodeValue;
-            // Cache the result
+            // Cache the result (use original xpath as key)
             if (element) {
                 this.xpathCache.set(xpath, element);
             }

package/dist/section-tracking.d.ts

@@ -22,6 +22,8 @@ export declare class SectionTrackingManager {
     private scrollDebounceTimer;
     private pendingEvents;
     private batchTimer;
+    private sectionTimers;
+    private readonly SPLIT_DURATION;
     constructor(tracker: SectionTracker, sections: SectionConfig[], options?: Partial<SectionTrackingOptions>);
     /**
      * Initialize section tracking
@@ -47,6 +49,14 @@ export declare class SectionTrackingManager {
      * Handle section entry (became visible)
      */
     private handleSectionEntry;
+    /**
+     * Start periodic tracking for a section (sends events every 3 seconds)
+     */
+    private startPeriodicTracking;
+    /**
+     * Stop periodic tracking for a section
+     */
+    private stopPeriodicTracking;
     /**
      * Handle section exit (became invisible)
      */

package/dist/section-tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"section-tracking.d.ts","sourceRoot":"","sources":["../src/section-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmB,sBAAsB,EAAwB,MAAM,uBAAuB,CAAC;AAE1H,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/B;AAWD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,aAAa,CAAgD;IACrE,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,UAAU,CAA0C;IAG5D,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,mBAAmB,CAAuB;IAGlD,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAuB;gBAGvC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAgB/C;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAqBjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoCzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgC1B;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI;IAsB/C;;OAEG;IACH,OAAO,IAAI,IAAI;CAgChB"}
+{"version":3,"file":"section-tracking.d.ts","sourceRoot":"","sources":["../src/section-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAmB,sBAAsB,EAAwB,MAAM,uBAAuB,CAAC;AAE1H,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;IACxE,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC/B;AAWD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,aAAa,CAAgD;IACrE,OAAO,CAAC,oBAAoB,CAAqC;IACjE,OAAO,CAAC,UAAU,CAA0C;IAG5D,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,mBAAmB,CAAuB;IAGlD,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAuB;IAGzC,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;gBAGrC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,GAAE,OAAO,CAAC,sBAAsB,CAAM;IAgB/C;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAqBjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkC1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2D7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAuC1B;;OAEG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI;IAsB/C;;OAEG;IACH,OAAO,IAAI,IAAI;CAsChB"}

package/dist/section-tracking.js

@@ -28,6 +28,9 @@ class SectionTrackingManager {
         // Event batching
         this.pendingEvents = [];
         this.batchTimer = null;
+        // Periodic tracking for long-duration views
+        this.sectionTimers = new Map(); // sectionName -> timer ID
+        this.SPLIT_DURATION = 3000; // 3 seconds
         this.tracker = tracker;
         this.sections = sections;
         this.options = { ...DEFAULT_OPTIONS, ...options };
@@ -159,12 +162,80 @@ class SectionTrackingManager {
         state.lastScrollPosition = window.scrollY;
         state.lastScrollTime = Date.now();
         state.maxVisibleArea = 0;
+        // Start periodic tracking timer (3 second intervals)
+        this.startPeriodicTracking(state);
+    }
+    /**
+     * Start periodic tracking for a section (sends events every 3 seconds)
+     */
+    startPeriodicTracking(state) {
+        // Clear any existing timer for this section
+        this.stopPeriodicTracking(state.config.sectionName);
+        const timerId = window.setInterval(() => {
+            if (this.isDestroyed || !state.isVisible || state.entryTime === null) {
+                this.stopPeriodicTracking(state.config.sectionName);
+                return;
+            }
+            const now = Date.now();
+            const duration = now - state.entryTime;
+            // Only track if minimum dwell time has passed
+            if (duration >= this.options.minDwellTime) {
+                // Create partial section view data
+                const viewData = {
+                    sectionName: state.config.sectionName,
+                    sectionType: state.config.sectionType,
+                    entryTime: state.entryTime,
+                    exitTime: now, // Current time as "exit" for this split
+                    duration,
+                    viewportWidth: window.innerWidth,
+                    viewportHeight: window.innerHeight,
+                    scrollDepth: this.calculateScrollDepth(),
+                    visibleAreaPercentage: Math.round(state.maxVisibleArea * 100),
+                    scrollSpeedAtEntry: state.entryScrollSpeed,
+                    scrollSpeedAtExit: this.scrollVelocity,
+                };
+                // Track this split immediately (don't queue for batching)
+                if (this.shouldTrackSection(viewData)) {
+                    this.tracker.trackSystemEvent('_grain_section_view', {
+                        section_name: viewData.sectionName,
+                        section_type: viewData.sectionType,
+                        duration_ms: viewData.duration,
+                        viewport_width: viewData.viewportWidth,
+                        viewport_height: viewData.viewportHeight,
+                        scroll_depth_percent: viewData.scrollDepth,
+                        visible_area_percent: viewData.visibleAreaPercentage,
+                        scroll_speed_entry: Math.round(viewData.scrollSpeedAtEntry || 0),
+                        scroll_speed_exit: Math.round(viewData.scrollSpeedAtExit || 0),
+                        entry_timestamp: viewData.entryTime,
+                        exit_timestamp: viewData.exitTime,
+                        is_split: true, // Flag to indicate this is a periodic split, not final exit
+                    });
+                    this.log('Tracked periodic section view split:', state.config.sectionName, 'duration:', duration);
+                    // Reset entry time for next split (but keep tracking)
+                    state.entryTime = now;
+                    state.entryScrollSpeed = this.scrollVelocity;
+                }
+            }
+        }, this.SPLIT_DURATION);
+        this.sectionTimers.set(state.config.sectionName, timerId);
+    }
+    /**
+     * Stop periodic tracking for a section
+     */
+    stopPeriodicTracking(sectionName) {
+        const timerId = this.sectionTimers.get(sectionName);
+        if (timerId !== undefined) {
+            clearInterval(timerId);
+            this.sectionTimers.delete(sectionName);
+        }
     }
     /**
      * Handle section exit (became invisible)
      */
     handleSectionExit(state) {
         this.log('Section exited view:', state.config.sectionName);
+        // Stop periodic tracking
+        this.stopPeriodicTracking(state.config.sectionName);
         if (state.entryTime === null)
             return;
         state.exitTime = Date.now();
@@ -299,8 +370,14 @@ class SectionTrackingManager {
             this.xpathCache.delete(xpath);
         }
         try {
-            const result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+            // Strip the xpath= prefix if present (from Stagehand selectors)
+            let cleanXpath = xpath;
+            if (xpath.startsWith('xpath=')) {
+                cleanXpath = xpath.substring(6); // Remove 'xpath=' prefix
+            }
+            const result = document.evaluate(cleanXpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
             const element = result.singleNodeValue;
+            // Cache the result (use original xpath as key)
             if (element) {
                 this.xpathCache.set(xpath, element);
             }
@@ -347,6 +424,11 @@ class SectionTrackingManager {
             return;
         this.log('Destroying section tracking manager');
         this.isDestroyed = true;
+        // Stop all periodic tracking timers
+        this.sectionTimers.forEach((timerId) => {
+            clearInterval(timerId);
+        });
+        this.sectionTimers.clear();
         // Flush any pending events
         this.flushPendingEvents();
         // Clear timers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainql/analytics-web",
-  "version": "2.5.0",
+  "version": "2.5.4",
   "description": "Lightweight TypeScript SDK for sending analytics events and managing remote configurations via Grain's REST API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",