@zaplier/sdk 1.6.9 → 1.7.0

package/dist/index.d.ts

@@ -932,9 +932,25 @@ declare class ZaplierSDK implements ZaplierSDK$1 {
             trackHovers?: boolean;
             trackForms?: boolean;
         }) => void;
+        /**
+         * Refresh tracking for dynamic content (React/SPA route changes)
+         * Modern alternative to rescan() - follows GA4/industry best practices
+         */
+        refreshTracking: () => void;
+        /**
+         * Legacy rescan method - use refreshTracking() instead
+         * @deprecated Use refreshTracking() for better performance
+         */
+        rescan: () => void;
+        /**
+         * Get diagnostic information for debugging
+         */
+        getDiagnostics: () => object | null;
         getStats: () => {
             observedElements: number;
             config: AutoTrackerConfig;
+            isModern: boolean;
+            diagnostics?: object;
         } | null;
         isEnabled: () => boolean;
     };
@@ -1119,6 +1135,8 @@ declare const Zaplier: {
         getStats: () => {
             observedElements: number;
             config: AutoTrackerConfig;
+            isModern: boolean;
+            diagnostics?: object;
         } | null;
         isEnabled: () => boolean;
     };

package/dist/index.esm.js

@@ -19262,6 +19262,8 @@ class AutoTracker {
     constructor(sdkInstance, config = {}) {
         this.observedElements = new Set();
         this.scrollThrottle = 0;
+        this.isInitialized = false;
+        this.delegationHandlers = new Map();
         this.handleScroll = () => {
             if (!this.config.trackScrolls)
                 return;
@@ -19366,30 +19368,29 @@ class AutoTracker {
                 trackScrolls: this.config.trackScrolls,
                 trackViews: this.config.trackViews,
                 trackHovers: this.config.trackHovers,
-                trackForms: this.config.trackForms
+                trackForms: this.config.trackForms,
+                domReady: document.readyState
             });
-            // Log elementos existentes encontrados
-            setTimeout(() => {
-                const clickElements = document.querySelectorAll('[data-track-click]');
-                const scrollElements = document.querySelectorAll('[data-track-scroll]');
-                const viewElements = document.querySelectorAll('[data-track-view]');
-                const hoverElements = document.querySelectorAll('[data-track-hover]');
-                const formElements = document.querySelectorAll('[data-track-form]');
-                console.log("[Zaplier AutoTracker] Elementos encontrados:", {
-                    clickElements: clickElements.length,
-                    scrollElements: scrollElements.length,
-                    viewElements: viewElements.length,
-                    hoverElements: hoverElements.length,
-                    formElements: formElements.length
-                });
-                if (scrollElements.length > 0) {
-                    console.log("[Zaplier AutoTracker] Elementos de scroll:", Array.from(scrollElements).map(el => ({
-                        tagName: el.tagName,
-                        trackEvent: el.getAttribute('data-track-scroll'),
-                        threshold: el.getAttribute('data-scroll-threshold') || '0.5'
-                    })));
+        }
+        // Aguardar DOM ready se necessário
+        if (document.readyState === 'loading') {
+            if (this.config.debug) {
+                console.log("[Zaplier AutoTracker] DOM still loading, waiting for DOMContentLoaded...");
+            }
+            document.addEventListener('DOMContentLoaded', () => {
+                if (this.config.debug) {
+                    console.log("[Zaplier AutoTracker] DOMContentLoaded fired, initializing tracking...");
                 }
-            }, 100);
+                this.initializeTracking();
+            }, { once: true });
+        }
+        else {
+            this.initializeTracking();
+        }
+    }
+    initializeTracking() {
+        if (this.config.debug) {
+            console.log("[Zaplier AutoTracker] Initializing tracking...");
         }
         // Observer para novos elementos no DOM
         this.observeDOM();
@@ -19399,42 +19400,269 @@ class AutoTracker {
         if (this.config.trackViews) {
             this.setupViewTracking();
         }
-        // Setup global event listeners
+        // Setup event delegation (modern approach)
+        this.setupEventDelegation();
+        // Debug: Log elementos encontrados após inicialização
+        if (this.config.debug) {
+            this.logFoundElements();
+            // Também agendar uma verificação após delay para elementos React
+            setTimeout(() => {
+                console.log("[Zaplier AutoTracker] Re-checking elements after 500ms...");
+                this.logFoundElements();
+            }, 500);
+            setTimeout(() => {
+                console.log("[Zaplier AutoTracker] Re-checking elements after 2s...");
+                this.logFoundElements();
+            }, 2000);
+        }
+    }
+    logFoundElements() {
+        const clickElements = document.querySelectorAll('[data-track-click]');
+        const scrollElements = document.querySelectorAll('[data-track-scroll]');
+        const viewElements = document.querySelectorAll('[data-track-view]');
+        const hoverElements = document.querySelectorAll('[data-track-hover]');
+        const formElements = document.querySelectorAll('[data-track-form]');
+        console.log("[Zaplier AutoTracker] Elementos encontrados:", {
+            clickElements: clickElements.length,
+            scrollElements: scrollElements.length,
+            viewElements: viewElements.length,
+            hoverElements: hoverElements.length,
+            formElements: formElements.length,
+            totalElements: clickElements.length + scrollElements.length + viewElements.length + hoverElements.length + formElements.length
+        });
+        if (scrollElements.length > 0) {
+            console.log("[Zaplier AutoTracker] Elementos de scroll:", Array.from(scrollElements).map(el => ({
+                tagName: el.tagName,
+                trackEvent: el.getAttribute('data-track-scroll'),
+                threshold: el.getAttribute('data-scroll-threshold') || '0.5',
+                id: el.id || 'no-id',
+                classes: el.className || 'no-classes'
+            })));
+        }
+    }
+    /**
+     * Setup Event Delegation (Industry Best Practice)
+     * Uses single document-level listeners instead of individual element listeners
+     */
+    setupEventDelegation() {
+        if (this.config.debug) {
+            console.log("[AutoTracker] Setting up event delegation...");
+        }
+        // Click delegation
         if (this.config.trackClicks) {
-            document.addEventListener("click", this.handleClick, { passive: true });
+            const clickHandler = this.createDelegatedClickHandler();
+            this.delegationHandlers.set('click', clickHandler);
+            document.addEventListener('click', clickHandler, { passive: true });
         }
+        // Scroll delegation (using global handler with element detection)
         if (this.config.trackScrolls) {
-            document.addEventListener("scroll", this.handleScroll, { passive: true });
+            const scrollHandler = this.createDelegatedScrollHandler();
+            this.delegationHandlers.set('scroll', scrollHandler);
+            document.addEventListener('scroll', scrollHandler, { passive: true });
         }
+        // Setup debounced mutation observer for dynamic content
+        this.setupIntelligentMutationObserver();
+        this.isInitialized = true;
     }
     /**
-     * Parar auto tracking
+     * Create delegated click handler (no individual listeners needed)
      */
-    stop() {
-        document.removeEventListener("click", this.handleClick);
-        document.removeEventListener("scroll", this.handleScroll);
-        if (this.intersectionObserver) {
-            this.intersectionObserver.disconnect();
+    createDelegatedClickHandler() {
+        return (event) => {
+            const target = event.target;
+            if (!target || !this.config.trackClicks)
+                return;
+            // Check if target or any parent has data-track-click
+            const trackingElement = target.closest('[data-track-click]');
+            if (!trackingElement)
+                return;
+            const eventName = trackingElement.getAttribute('data-track-click');
+            if (!eventName)
+                return;
+            const metadata = this.extractMetadata(trackingElement);
+            this.trackEvent(eventName, {
+                type: 'click',
+                element: trackingElement.tagName.toLowerCase(),
+                ...metadata,
+            });
+            if (this.config.debug) {
+                console.log(`[AutoTracker] Click tracked via delegation: ${eventName}`, {
+                    element: trackingElement.tagName.toLowerCase(),
+                    ...metadata
+                });
+            }
+        };
+    }
+    /**
+     * Create delegated scroll handler (efficient global approach)
+     */
+    createDelegatedScrollHandler() {
+        return () => {
+            if (!this.config.trackScrolls)
+                return;
+            // Throttle scroll events for performance
+            const now = Date.now();
+            if (now - this.scrollThrottle < 100)
+                return;
+            this.scrollThrottle = now;
+            // Find all scroll tracking elements and check visibility
+            const scrollElements = document.querySelectorAll('[data-track-scroll]');
+            if (this.config.debug && scrollElements.length > 0) {
+                console.log(`[AutoTracker] Checking ${scrollElements.length} scroll elements via delegation`);
+            }
+            scrollElements.forEach((element) => {
+                this.processScrollElement(element);
+            });
+        };
+    }
+    /**
+     * Process individual scroll element (extracted for reusability)
+     */
+    processScrollElement(element) {
+        const hasTriggered = element.getAttribute('data-scroll-triggered') === 'true';
+        if (hasTriggered)
+            return;
+        const threshold = parseFloat(element.getAttribute('data-scroll-threshold') || '0.5');
+        const rect = element.getBoundingClientRect();
+        const elementHeight = rect.height;
+        const visibleHeight = Math.min(rect.bottom, window.innerHeight) - Math.max(rect.top, 0);
+        const visibilityRatio = Math.max(0, visibleHeight) / elementHeight;
+        if (this.config.debug) {
+            console.log(`[AutoTracker] Scroll element check via delegation:`, {
+                elementId: element.id || element.className,
+                visibilityRatio: Math.round(visibilityRatio * 100) / 100,
+                threshold,
+                triggered: hasTriggered
+            });
+        }
+        if (visibilityRatio >= threshold) {
+            element.setAttribute('data-scroll-triggered', 'true');
+            const eventName = element.getAttribute('data-track-scroll');
+            if (!eventName)
+                return;
+            const metadata = this.extractMetadata(element);
+            this.trackEvent(eventName, {
+                type: 'scroll',
+                element: element.tagName.toLowerCase(),
+                threshold,
+                scrollDepth: window.scrollY,
+                visibilityRatio: Math.round(visibilityRatio * 100) / 100,
+                ...metadata,
+            });
+            if (this.config.debug) {
+                console.log(`[AutoTracker] Scroll tracked via delegation: ${eventName}`, {
+                    threshold,
+                    visibilityRatio,
+                    scrollDepth: window.scrollY,
+                    ...metadata
+                });
+            }
         }
-        this.observedElements.clear();
     }
     /**
-     * Observar mudanças no DOM para novos elementos
+     * Setup intelligent mutation observer (debounced for performance)
      */
-    observeDOM() {
-        const observer = new MutationObserver((mutations) => {
-            mutations.forEach((mutation) => {
-                mutation.addedNodes.forEach((node) => {
+    setupIntelligentMutationObserver() {
+        if (this.mutationObserver)
+            return; // Already setup
+        const debouncedCallback = this.debounce((mutations) => {
+            let hasRelevantChanges = false;
+            mutations.forEach(mutation => {
+                mutation.addedNodes.forEach(node => {
                     if (node.nodeType === Node.ELEMENT_NODE) {
-                        this.processElement(node);
+                        const element = node;
+                        if (this.hasTrackingAttributes(element) || this.hasTrackingDescendants(element)) {
+                            hasRelevantChanges = true;
+                            if (this.config.debug) {
+                                console.log('[AutoTracker] New trackable element detected via mutation observer:', element);
+                            }
+                        }
                     }
                 });
             });
-        });
-        observer.observe(document.body, {
+            if (hasRelevantChanges) {
+                if (this.config.debug) {
+                    console.log('[AutoTracker] Processing new elements from mutations...');
+                }
+                // Process elements for view tracking (only thing that needs setup)
+                this.processExistingElements();
+            }
+        }, 150);
+        this.mutationObserver = new MutationObserver(debouncedCallback);
+        this.mutationObserver.observe(document.body, {
             childList: true,
             subtree: true,
         });
+        if (this.config.debug) {
+            console.log('[AutoTracker] Intelligent mutation observer setup complete');
+        }
+    }
+    /**
+     * Check if element has tracking attributes
+     */
+    hasTrackingAttributes(element) {
+        return element.hasAttribute && (element.hasAttribute('data-track-click') ||
+            element.hasAttribute('data-track-scroll') ||
+            element.hasAttribute('data-track-view') ||
+            element.hasAttribute('data-track-hover') ||
+            element.hasAttribute('data-track-form'));
+    }
+    /**
+     * Check if element has tracking descendants
+     */
+    hasTrackingDescendants(element) {
+        if (!element.querySelector)
+            return false;
+        return !!(element.querySelector('[data-track-click]') ||
+            element.querySelector('[data-track-scroll]') ||
+            element.querySelector('[data-track-view]') ||
+            element.querySelector('[data-track-hover]') ||
+            element.querySelector('[data-track-form]'));
+    }
+    /**
+     * Utility: Debounce function for performance optimization
+     */
+    debounce(func, wait) {
+        let timeout;
+        return (...args) => {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => func.apply(this, args), wait);
+        };
+    }
+    /**
+     * Parar auto tracking (with proper cleanup)
+     */
+    stop() {
+        if (this.config.debug) {
+            console.log('[AutoTracker] Stopping auto tracking and cleaning up...');
+        }
+        // Remove delegation handlers
+        this.delegationHandlers.forEach((handler, eventType) => {
+            document.removeEventListener(eventType, handler);
+        });
+        this.delegationHandlers.clear();
+        // Disconnect observers
+        if (this.intersectionObserver) {
+            this.intersectionObserver.disconnect();
+            this.intersectionObserver = undefined;
+        }
+        if (this.mutationObserver) {
+            this.mutationObserver.disconnect();
+            this.mutationObserver = undefined;
+        }
+        // Clear caches
+        this.observedElements.clear();
+        this.isInitialized = false;
+    }
+    /**
+     * Legacy method - now handled by intelligent mutation observer
+     * @deprecated Use setupIntelligentMutationObserver instead
+     */
+    observeDOM() {
+        // This is now handled by setupIntelligentMutationObserver in setupEventDelegation
+        if (this.config.debug) {
+            console.log('[AutoTracker] observeDOM() is deprecated - using intelligent mutation observer');
+        }
     }
     /**
      * Processar elementos já existentes no DOM
@@ -19622,15 +19850,35 @@ class AutoTracker {
      * Enviar evento para o SDK
      */
     trackEvent(eventName, metadata) {
-        if (!this.sdkInstance)
+        if (this.config.debug) {
+            console.log("[AutoTracker] trackEvent called:", { eventName, metadata });
+        }
+        if (!this.sdkInstance) {
+            if (this.config.debug) {
+                console.error("[AutoTracker] SDK instance is null!");
+            }
+            return;
+        }
+        if (typeof this.sdkInstance.trackCustomEvent !== 'function') {
+            if (this.config.debug) {
+                console.error("[AutoTracker] trackCustomEvent is not a function:", typeof this.sdkInstance.trackCustomEvent);
+            }
             return;
+        }
         try {
-            this.sdkInstance.trackCustomEvent(eventName, {
+            const eventData = {
                 autoTracked: true,
                 timestamp: Date.now(),
                 url: window.location.href,
                 ...metadata,
-            });
+            };
+            if (this.config.debug) {
+                console.log("[AutoTracker] Calling trackCustomEvent:", { eventName, eventData });
+            }
+            const result = this.sdkInstance.trackCustomEvent(eventName, eventData);
+            if (this.config.debug) {
+                console.log("[AutoTracker] trackCustomEvent result:", result);
+            }
         }
         catch (error) {
             if (this.config.debug) {
@@ -19638,6 +19886,55 @@ class AutoTracker {
             }
         }
     }
+    /**
+     * Modern API: Refresh tracking for dynamic content (React/SPA support)
+     * Industry best practice for SPA route changes
+     */
+    refreshTracking() {
+        if (!this.isInitialized) {
+            if (this.config.debug) {
+                console.log('[AutoTracker] Not initialized, cannot refresh tracking');
+            }
+            return;
+        }
+        if (this.config.debug) {
+            console.log('[AutoTracker] Refreshing tracking for dynamic content...');
+        }
+        // Re-process elements for view tracking (only thing that needs setup)
+        this.processExistingElements();
+        // Log current state
+        if (this.config.debug) {
+            this.logFoundElements();
+        }
+    }
+    /**
+     * Legacy method - use refreshTracking() instead
+     * @deprecated Use refreshTracking() for better performance
+     */
+    rescan() {
+        this.refreshTracking();
+    }
+    /**
+     * Get diagnostic information for debugging
+     */
+    getDiagnostics() {
+        return {
+            isInitialized: this.isInitialized,
+            hasClickHandler: this.delegationHandlers.has('click'),
+            hasScrollHandler: this.delegationHandlers.has('scroll'),
+            observedElements: this.observedElements.size,
+            hasMutationObserver: !!this.mutationObserver,
+            hasIntersectionObserver: !!this.intersectionObserver,
+            config: this.config,
+            elementsFound: {
+                click: document.querySelectorAll('[data-track-click]').length,
+                scroll: document.querySelectorAll('[data-track-scroll]').length,
+                view: document.querySelectorAll('[data-track-view]').length,
+                hover: document.querySelectorAll('[data-track-hover]').length,
+                form: document.querySelectorAll('[data-track-form]').length
+            }
+        };
+    }
     /**
      * Configurar tracking
      */
@@ -19645,12 +19942,14 @@ class AutoTracker {
         this.config = { ...this.config, ...config };
     }
     /**
-     * Obter estatísticas
+     * Enhanced stats with diagnostic information
      */
     getStats() {
         return {
             observedElements: this.observedElements.size,
             config: this.config,
+            isModern: this.isInitialized, // Indicates if using new delegation system
+            diagnostics: this.config.debug ? this.getDiagnostics() : undefined
         };
     }
 }
@@ -20199,6 +20498,36 @@ class ZaplierSDK {
                     console.log("[Zaplier] Auto tracking configured:", config);
                 }
             },
+            /**
+             * Refresh tracking for dynamic content (React/SPA route changes)
+             * Modern alternative to rescan() - follows GA4/industry best practices
+             */
+            refreshTracking: () => {
+                if (this.autoTracker) {
+                    this.autoTracker.refreshTracking();
+                }
+                if (this.config.debug) {
+                    console.log("[Zaplier] Auto tracking refreshed");
+                }
+            },
+            /**
+             * Legacy rescan method - use refreshTracking() instead
+             * @deprecated Use refreshTracking() for better performance
+             */
+            rescan: () => {
+                if (this.autoTracker) {
+                    this.autoTracker.rescan();
+                }
+                if (this.config.debug) {
+                    console.log("[Zaplier] Auto tracking rescanned (deprecated - use refreshTracking)");
+                }
+            },
+            /**
+             * Get diagnostic information for debugging
+             */
+            getDiagnostics: () => {
+                return this.autoTracker ? this.autoTracker.getDiagnostics() : null;
+            },
             getStats: () => {
                 return this.autoTracker ? this.autoTracker.getStats() : null;
             },