@journium/react 1.0.7 → 1.1.0

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAkD,SAAS,EAAE,MAAM,OAAO,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,UAAU,oBAAoB;IAC5B,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C;AAID,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA6C5D,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,oBAM9B,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAkD,SAAS,EAAE,MAAM,OAAO,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,UAAU,oBAAoB;IAC5B,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C;AAID,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAuC5D,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,oBAM9B,CAAC"}

package/dist/index.cjs

@@ -701,15 +701,23 @@ Logger.isDebugEnabled = false;
 
 class JourniumClient {
     constructor(config) {
-        var _a;
+        var _a, _b, _c, _d;
         this.queue = [];
+        this.stagedEvents = [];
         this.flushTimer = null;
-        this.initialized = false;
+        this.initializationComplete = false;
+        this.initializationFailed = false;
+        this.disabled = false;
         this.optionsChangeCallbacks = new Set();
-        // Validate required configuration
-        if (!config.publishableKey) {
+        // Validate required configuration - put in disabled state if invalid
+        if (!config.publishableKey || config.publishableKey.trim() === '') {
+            this.disabled = true;
             Logger.setDebug(true);
-            Logger.error('Journium: publishableKey is required but not provided. SDK will not function.');
+            Logger.error('Journium: publishableKey is required but not provided or is empty. SDK will not function.');
+            // Create minimal config to prevent crashes
+            this.config = { publishableKey: '', apiHost: 'https://events.journium.app' };
+            this.effectiveOptions = { debug: true };
+            this.optionsStorageKey = 'jrnm_invalid_options';
             return;
         }
         // Set default apiHost if not provided
@@ -719,25 +727,15 @@ class JourniumClient {
         };
         // Generate storage key for options caching
         this.optionsStorageKey = `jrnm_${config.publishableKey}_options`;
-        // Generate default values
-        const defaultOptions = {
-            debug: false,
-            flushAt: 20,
-            flushInterval: 10000,
-            sessionTimeout: 30 * 60 * 1000, // 30 minutes
-        };
-        // Initialize effective options with local options taking precedence over defaults
-        this.effectiveOptions = { ...defaultOptions };
-        if (this.config.options) {
-            this.effectiveOptions = mergeOptions(defaultOptions, this.config.options);
-        }
-        // Initialize Logger with debug setting
-        Logger.setDebug((_a = this.effectiveOptions.debug) !== null && _a !== void 0 ? _a : false);
-        // Initialize identity manager
-        this.identityManager = new BrowserIdentityManager(this.effectiveOptions.sessionTimeout, this.config.publishableKey);
-        // Initialize synchronously with cached config, fetch fresh config in background
-        this.initializeSync();
-        this.fetchRemoteOptionsAsync();
+        // Initialize with minimal defaults for identity manager
+        const fallbackSessionTimeout = 30 * 60 * 1000; // 30 minutes
+        this.effectiveOptions = {}; // Will be set after remote config
+        // Initialize Logger with local debug setting or false
+        Logger.setDebug((_b = (_a = this.config.options) === null || _a === void 0 ? void 0 : _a.debug) !== null && _b !== void 0 ? _b : false);
+        // Initialize identity manager with fallback timeout
+        this.identityManager = new BrowserIdentityManager((_d = (_c = this.config.options) === null || _c === void 0 ? void 0 : _c.sessionTimeout) !== null && _d !== void 0 ? _d : fallbackSessionTimeout, this.config.publishableKey);
+        // Initialize asynchronously - wait for remote config first
+        this.initializeAsync();
     }
     loadCachedOptions() {
         if (typeof window === 'undefined' || !window.localStorage) {
@@ -763,70 +761,105 @@ class JourniumClient {
             Logger.warn('Journium: Failed to save config to cache:', error);
         }
     }
-    initializeSync() {
-        // Step 1: Load cached remote options from localStorage (synchronous)
-        const cachedRemoteOptions = this.loadCachedOptions();
-        // Step 2: Merge cached remote options with local options (if cached options exist)
-        // Local options take precedence over cached remote options
-        if (cachedRemoteOptions) {
-            if (this.config.options) {
-                // Merge: local options override cached remote options
-                this.effectiveOptions = mergeOptions(cachedRemoteOptions, this.config.options);
-                Logger.log('Journium: Using cached remote options merged with local options:', this.effectiveOptions);
+    async initializeAsync() {
+        var _a;
+        try {
+            Logger.log('Journium: Starting initialization - fetching fresh remote config...');
+            // Step 1: Try to fetch fresh remote config with timeout and retry
+            const remoteOptions = await this.fetchRemoteOptionsWithRetry();
+            if (remoteOptions) {
+                // Step 2: Cache the fresh remote config
+                this.saveCachedOptions(remoteOptions);
+                // Step 3: Merge local options over remote config (local overrides remote)
+                if (this.config.options) {
+                    this.effectiveOptions = mergeOptions(this.config.options, remoteOptions);
+                    Logger.log('Journium: Using fresh remote config merged with local options:', this.effectiveOptions);
+                }
+                else {
+                    this.effectiveOptions = remoteOptions;
+                    Logger.log('Journium: Using fresh remote config:', this.effectiveOptions);
+                }
             }
             else {
-                // No local options, use cached remote options as-is
-                this.effectiveOptions = cachedRemoteOptions;
-                Logger.log('Journium: Using cached remote options:', cachedRemoteOptions);
+                // Step 4: Fallback to cached config if fresh fetch failed
+                const cachedRemoteOptions = this.loadCachedOptions();
+                if (cachedRemoteOptions) {
+                    if (this.config.options) {
+                        this.effectiveOptions = mergeOptions(this.config.options, cachedRemoteOptions);
+                        Logger.log('Journium: Fresh config failed, using cached remote config merged with local options:', this.effectiveOptions);
+                    }
+                    else {
+                        this.effectiveOptions = cachedRemoteOptions;
+                        Logger.log('Journium: Fresh config failed, using cached remote config:', this.effectiveOptions);
+                    }
+                }
+                else {
+                    // Step 5: No remote config and no cached config - initialization fails
+                    Logger.error('Journium: Initialization failed - no remote config available and no cached config found');
+                    this.initializationFailed = true;
+                    this.initializationComplete = false;
+                    return;
+                }
             }
+            // Step 6: Update identity manager session timeout if provided
+            if (this.effectiveOptions.sessionTimeout) {
+                this.identityManager.updateSessionTimeout(this.effectiveOptions.sessionTimeout);
+            }
+            // Step 7: Update Logger debug setting
+            Logger.setDebug((_a = this.effectiveOptions.debug) !== null && _a !== void 0 ? _a : false);
+            // Step 8: Mark initialization as complete
+            this.initializationComplete = true;
+            this.initializationFailed = false;
+            // Step 9: Process any staged events
+            this.processStagedEvents();
+            // Step 10: Start flush timer
+            if (this.effectiveOptions.flushInterval && this.effectiveOptions.flushInterval > 0) {
+                this.startFlushTimer();
+            }
+            Logger.log('Journium: Initialization complete with options:', this.effectiveOptions);
+            // Step 11: Notify callbacks about options
+            this.notifyOptionsChange();
         }
-        // If no cached options, effectiveOptions already has defaults merged with local options from constructor
-        // Step 3: Mark as initialized immediately - no need to wait for remote fetch
-        this.initialized = true;
-        // Step 4: Start flush timer immediately
-        if (this.effectiveOptions.flushInterval && this.effectiveOptions.flushInterval > 0) {
-            this.startFlushTimer();
-        }
-        Logger.log('Journium: Client initialized with effective options:', this.effectiveOptions);
-    }
-    async fetchRemoteOptionsAsync() {
-        // Fetch fresh config in background
-        if (this.config.publishableKey) {
-            await this.fetchAndCacheRemoteOptions();
+        catch (error) {
+            Logger.error('Journium: Initialization failed:', error);
+            this.initializationFailed = true;
+            this.initializationComplete = false;
         }
     }
-    async fetchAndCacheRemoteOptions() {
-        var _a;
-        try {
-            Logger.log('Journium: Fetching remote configuration in background...');
-            const remoteOptionsResponse = await fetchRemoteOptions(this.config.apiHost, this.config.publishableKey);
-            if (remoteOptionsResponse && remoteOptionsResponse.success) {
-                // Save remote config to cache for next session
-                this.saveCachedOptions(remoteOptionsResponse.config);
-                // Update effective options: local options (if provided) overrides fresh remote options
-                if (!this.config.options) {
-                    // No local options provided, use fresh remote options
-                    this.effectiveOptions = remoteOptionsResponse.config;
+    async fetchRemoteOptionsWithRetry() {
+        const maxRetries = 2;
+        const timeoutMs = 15000; // 15 seconds
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                Logger.log(`Journium: Fetching remote config (attempt ${attempt}/${maxRetries})...`);
+                // Create timeout promise
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error('Timeout')), timeoutMs);
+                });
+                // Race fetch against timeout
+                const fetchPromise = fetchRemoteOptions(this.config.apiHost, this.config.publishableKey);
+                const remoteOptionsResponse = await Promise.race([fetchPromise, timeoutPromise]);
+                if (remoteOptionsResponse && remoteOptionsResponse.success) {
+                    Logger.log('Journium: Successfully fetched fresh remote config:', remoteOptionsResponse.config);
+                    return remoteOptionsResponse.config;
                 }
                 else {
-                    // Local options provided, merge it over fresh remote options
-                    this.effectiveOptions = mergeOptions(remoteOptionsResponse.config, this.config.options);
+                    throw new Error('Remote config fetch unsuccessful');
                 }
-                // Update session timeout if provided in fresh effective options
-                if (this.effectiveOptions.sessionTimeout) {
-                    this.identityManager.updateSessionTimeout(this.effectiveOptions.sessionTimeout);
+            }
+            catch (error) {
+                Logger.warn(`Journium: Remote config fetch attempt ${attempt} failed:`, error);
+                if (attempt === maxRetries) {
+                    Logger.warn('Journium: All remote config fetch attempts failed, falling back to cached config');
+                    return null;
+                }
+                // Wait 1 second before retry (except on last attempt)
+                if (attempt < maxRetries) {
+                    await new Promise(resolve => setTimeout(resolve, 1000));
                 }
-                Logger.log('Journium: Background remote options applied:', remoteOptionsResponse.config);
-                Logger.log('Journium: New effective options:', this.effectiveOptions);
-                // Update Logger debug setting with new options
-                Logger.setDebug((_a = this.effectiveOptions.debug) !== null && _a !== void 0 ? _a : false);
-                // Notify all registered callbacks about the options change
-                this.notifyOptionsChange();
             }
         }
-        catch (error) {
-            Logger.warn('Journium: Background remote options fetch failed:', error);
-        }
+        return null;
     }
     /**
      * Register a callback to be notified when effective options change (e.g., when remote options are fetched)
@@ -848,12 +881,48 @@ class JourniumClient {
             }
         });
     }
+    processStagedEvents() {
+        if (this.stagedEvents.length === 0)
+            return;
+        Logger.log(`Journium: Processing ${this.stagedEvents.length} staged events`);
+        // Move staged events to main queue, adding identity properties now
+        const identity = this.identityManager.getIdentity();
+        const userAgentInfo = this.identityManager.getUserAgentInfo();
+        for (const stagedEvent of this.stagedEvents) {
+            // Add identity properties that weren't available during staging
+            const eventWithIdentity = {
+                ...stagedEvent,
+                properties: {
+                    $device_id: identity === null || identity === void 0 ? void 0 : identity.$device_id,
+                    distinct_id: identity === null || identity === void 0 ? void 0 : identity.distinct_id,
+                    $session_id: identity === null || identity === void 0 ? void 0 : identity.$session_id,
+                    $is_identified: (identity === null || identity === void 0 ? void 0 : identity.$user_state) === 'identified',
+                    $current_url: typeof window !== 'undefined' ? window.location.href : '',
+                    $pathname: typeof window !== 'undefined' ? window.location.pathname : '',
+                    ...userAgentInfo,
+                    $lib_version: '0.1.0', // TODO: Get from package.json
+                    $platform: 'web',
+                    ...stagedEvent.properties, // Original properties override system properties
+                },
+            };
+            this.queue.push(eventWithIdentity);
+        }
+        // Clear staged events
+        this.stagedEvents = [];
+        Logger.log('Journium: Staged events processed and moved to main queue');
+        // Check if we should flush immediately
+        if (this.queue.length >= this.effectiveOptions.flushAt) {
+            // console.log('1 Journium: Flushing events...'+JSON.stringify(this.effectiveOptions));
+            this.flush();
+        }
+    }
     startFlushTimer() {
         if (this.flushTimer) {
             clearInterval(this.flushTimer);
         }
         // Use universal setInterval (works in both browser and Node.js)
         this.flushTimer = setInterval(() => {
+            // console.log('2 Journium: Flushing events...'+JSON.stringify(this.effectiveOptions));
             this.flush();
         }, this.effectiveOptions.flushInterval);
     }
@@ -882,9 +951,14 @@ class JourniumClient {
         }
     }
     identify(distinctId, attributes = {}) {
-        // Don't identify if SDK is not properly configured
-        if (!this.config || !this.config.publishableKey || !this.initialized) {
-            Logger.warn('Journium: identify() call rejected - SDK not ready');
+        // Don't identify if SDK is not properly configured or disabled
+        if (this.disabled || !this.config || !this.config.publishableKey) {
+            Logger.warn('Journium: identify() call rejected - SDK not ready or disabled');
+            return;
+        }
+        // Don't identify if initialization failed
+        if (this.initializationFailed) {
+            Logger.warn('Journium: identify() call rejected - initialization failed');
             return;
         }
         // Call identify on identity manager to get previous distinct ID
@@ -898,9 +972,14 @@ class JourniumClient {
         Logger.log('Journium: User identified', { distinctId, attributes, previousDistinctId });
     }
     reset() {
-        // Don't reset if SDK is not properly configured
-        if (!this.config || !this.config.publishableKey || !this.initialized) {
-            Logger.warn('Journium: reset() call rejected - SDK not ready');
+        // Don't reset if SDK is not properly configured or disabled
+        if (this.disabled || !this.config || !this.config.publishableKey) {
+            Logger.warn('Journium: reset() call rejected - SDK not ready or disabled');
+            return;
+        }
+        // Don't reset if initialization failed
+        if (this.initializationFailed) {
+            Logger.warn('Journium: reset() call rejected - initialization failed');
             return;
         }
         // Reset identity in identity manager
@@ -908,36 +987,58 @@ class JourniumClient {
         Logger.log('Journium: User identity reset');
     }
     track(event, properties = {}) {
-        // Don't track if SDK is not properly configured
-        if (!this.config || !this.config.publishableKey || !this.initialized) {
-            Logger.warn('Journium: track() call rejected - SDK not ready');
+        // Don't track if SDK is not properly configured or disabled
+        if (this.disabled || !this.config || !this.config.publishableKey) {
+            Logger.warn('Journium: track() call rejected - SDK not ready or disabled');
             return;
         }
-        const identity = this.identityManager.getIdentity();
-        const userAgentInfo = this.identityManager.getUserAgentInfo();
-        // Create standardized event properties
-        const eventProperties = {
-            $device_id: identity === null || identity === void 0 ? void 0 : identity.$device_id,
-            distinct_id: identity === null || identity === void 0 ? void 0 : identity.distinct_id,
-            $session_id: identity === null || identity === void 0 ? void 0 : identity.$session_id,
-            $is_identified: (identity === null || identity === void 0 ? void 0 : identity.$user_state) === 'identified',
-            $current_url: typeof window !== 'undefined' ? window.location.href : '',
-            $pathname: typeof window !== 'undefined' ? window.location.pathname : '',
-            ...userAgentInfo,
-            $lib_version: '0.1.0', // TODO: Get from package.json
-            $platform: 'web',
-            ...properties, // User-provided properties override defaults
-        };
+        // Create minimal event without identity properties (will be added later if staging)
         const journiumEvent = {
             uuid: generateUuidv7(),
             ingestion_key: this.config.publishableKey,
             client_timestamp: getCurrentTimestamp(),
             event,
-            properties: eventProperties,
+            properties: { ...properties }, // Only user properties for now
         };
-        this.queue.push(journiumEvent);
-        Logger.log('Journium: Event tracked', journiumEvent);
-        if (this.queue.length >= this.effectiveOptions.flushAt) {
+        // Stage events during initialization, add to queue after initialization
+        if (!this.initializationComplete) {
+            // If initialization failed, reject events
+            if (this.initializationFailed) {
+                Logger.warn('Journium: track() call rejected - initialization failed');
+                return;
+            }
+            this.stagedEvents.push(journiumEvent);
+            Logger.log('Journium: Event staged during initialization', journiumEvent);
+            return;
+        }
+        // If initialization failed, reject events
+        if (this.initializationFailed) {
+            Logger.warn('Journium: track() call rejected - initialization failed');
+            return;
+        }
+        // Add identity properties for immediate events (after initialization)
+        const identity = this.identityManager.getIdentity();
+        const userAgentInfo = this.identityManager.getUserAgentInfo();
+        const eventWithIdentity = {
+            ...journiumEvent,
+            properties: {
+                $device_id: identity === null || identity === void 0 ? void 0 : identity.$device_id,
+                distinct_id: identity === null || identity === void 0 ? void 0 : identity.distinct_id,
+                $session_id: identity === null || identity === void 0 ? void 0 : identity.$session_id,
+                $is_identified: (identity === null || identity === void 0 ? void 0 : identity.$user_state) === 'identified',
+                $current_url: typeof window !== 'undefined' ? window.location.href : '',
+                $pathname: typeof window !== 'undefined' ? window.location.pathname : '',
+                ...userAgentInfo,
+                $lib_version: '0.1.0', // TODO: Get from package.json
+                $platform: 'web',
+                ...properties, // User-provided properties override system properties
+            },
+        };
+        this.queue.push(eventWithIdentity);
+        Logger.log('Journium: Event tracked', eventWithIdentity);
+        // Only flush if we have effective options (after initialization)
+        if (this.effectiveOptions.flushAt && this.queue.length >= this.effectiveOptions.flushAt) {
+            // console.log('3 Journium: Flushing events...'+JSON.stringify(this.effectiveOptions));
             this.flush();
         }
     }
@@ -946,6 +1047,11 @@ class JourniumClient {
         if (!this.config || !this.config.publishableKey) {
             return;
         }
+        // Don't flush if initialization failed
+        if (this.initializationFailed) {
+            Logger.warn('Journium: flush() call rejected - initialization failed');
+            return;
+        }
         if (this.queue.length === 0)
             return;
         const events = [...this.queue];
@@ -997,7 +1103,7 @@ class PageviewTracker {
      * Start automatic autocapture for pageviews
      * @returns void
      */
-    startAutocapture() {
+    startAutoPageviewTracking() {
         this.capturePageview();
         if (typeof window !== 'undefined') {
             // Store original methods for cleanup
@@ -1426,6 +1532,9 @@ class JourniumAnalytics {
         this.unsubscribeOptionsChange = this.client.onOptionsChange((effectiveOptions) => {
             this.handleOptionsChange(effectiveOptions);
         });
+        // Start automatic autocapture immediately if initial options support it
+        // This handles cached remote options or local options with autocapture enabled
+        this.startAutocaptureIfEnabled(initialEffectiveOptions);
     }
     resolveAutocaptureOptions(autocapture) {
         if (autocapture === false) {
@@ -1456,13 +1565,18 @@ class JourniumAnalytics {
     startAutocapture() {
         // Always check effective options (which may include remote options)
         const effectiveOptions = this.client.getEffectiveOptions();
-        const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
-        const autocaptureEnabled = effectiveOptions.autocapture !== false;
+        // Only enable if effectiveOptions are loaded and autoTrackPageviews is not explicitly false
+        const autoTrackPageviews = effectiveOptions && Object.keys(effectiveOptions).length > 0
+            ? effectiveOptions.autoTrackPageviews !== false
+            : false;
+        const autocaptureEnabled = effectiveOptions && Object.keys(effectiveOptions).length > 0
+            ? effectiveOptions.autocapture !== false
+            : false;
         // Update autocapture tracker options if they've changed
         const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
         this.autocaptureTracker.updateOptions(autocaptureOptions);
         if (autoTrackPageviews) {
-            this.pageviewTracker.startAutocapture();
+            this.pageviewTracker.startAutoPageviewTracking();
         }
         if (autocaptureEnabled) {
             this.autocaptureTracker.start();
@@ -1475,30 +1589,60 @@ class JourniumAnalytics {
         this.autocaptureStarted = false;
     }
     /**
-     * Handle effective options change (e.g., when remote options are fetched)
+     * Automatically start autocapture if enabled in options
+     * Handles both initial options and empty options during remote-first initialization
      */
-    handleOptionsChange(effectiveOptions) {
-        // If autocapture was already started, re-evaluate with new options
+    startAutocaptureIfEnabled(effectiveOptions) {
+        // Skip if autocapture was already started manually
         if (this.autocaptureStarted) {
-            // Stop current autocapture
-            this.pageviewTracker.stopAutocapture();
-            this.autocaptureTracker.stop();
-            this.autocaptureStarted = false;
-            // Re-evaluate if autocapture should be enabled with new options
+            return;
+        }
+        // During remote-first initialization, effective options might be empty initially
+        // Only auto-start if we have actual options loaded, not empty options
+        const hasActualOptions = effectiveOptions && Object.keys(effectiveOptions).length > 0;
+        if (hasActualOptions) {
+            // Use same logic as manual startAutocapture() but only start automatically
             const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
             const autocaptureEnabled = effectiveOptions.autocapture !== false;
             // Update autocapture tracker options
             const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
             this.autocaptureTracker.updateOptions(autocaptureOptions);
-            // Restart only if still enabled
             if (autoTrackPageviews) {
-                this.pageviewTracker.startAutocapture();
+                this.pageviewTracker.startAutoPageviewTracking();
             }
             if (autocaptureEnabled) {
                 this.autocaptureTracker.start();
             }
-            this.autocaptureStarted = autoTrackPageviews || autocaptureEnabled;
+            if (autoTrackPageviews || autocaptureEnabled) {
+                this.autocaptureStarted = true;
+            }
+        }
+        // If options are empty (during initialization), wait for options change callback
+    }
+    /**
+     * Handle effective options change (e.g., when remote options are fetched)
+     */
+    handleOptionsChange(effectiveOptions) {
+        // Stop current autocapture if it was already started
+        if (this.autocaptureStarted) {
+            this.pageviewTracker.stopAutocapture();
+            this.autocaptureTracker.stop();
+            this.autocaptureStarted = false;
         }
+        // Evaluate if autocapture should be enabled with new options
+        const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
+        const autocaptureEnabled = effectiveOptions.autocapture !== false;
+        // Update autocapture tracker options
+        const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
+        this.autocaptureTracker.updateOptions(autocaptureOptions);
+        // Start autocapture based on new options (even if it wasn't started before)
+        if (autoTrackPageviews) {
+            this.pageviewTracker.startAutoPageviewTracking();
+        }
+        if (autocaptureEnabled) {
+            this.autocaptureTracker.start();
+        }
+        this.autocaptureStarted = autoTrackPageviews || autocaptureEnabled;
     }
     async flush() {
         return this.client.flush();
@@ -1525,24 +1669,20 @@ const init = (config) => {
     return new JourniumAnalytics(config);
 };
 
-const JourniumContext = React.createContext({ analytics: null, config: null, effectiveOptions: null });
+const JourniumContext = React.createContext(undefined);
 const JourniumProvider = ({ children, config, }) => {
     const [analytics, setAnalytics] = React.useState(null);
     const [effectiveOptions, setEffectiveOptions] = React.useState(null);
     React.useEffect(() => {
         const analyticsInstance = new JourniumAnalytics(config);
-        // Get initial effective options (may include cached remote options)
+        // Get initial effective options (may be empty during remote-first initialization)
         const initialEffective = analyticsInstance.getEffectiveOptions();
         setEffectiveOptions(initialEffective);
-        // Check if autocapture should be enabled based on initial effective options
-        const autocaptureEnabled = initialEffective.autocapture !== false;
-        if (autocaptureEnabled) {
-            analyticsInstance.startAutocapture();
-        }
+        // Don't start autocapture immediately with potentially empty options
+        // Let the analytics instance handle autocapture after initialization completes
         setAnalytics(analyticsInstance);
         // Listen for options changes (when remote options are fetched)
-        // Note: JourniumAnalytics already handles restarting autocapture when options change
-        // We just need to update the effectiveOptions state for consumers
+        // The JourniumAnalytics will automatically start autocapture when initialization completes
         const unsubscribe = analyticsInstance.onOptionsChange((newOptions) => {
             setEffectiveOptions(newOptions);
         });