@rejourneyco/react-native 1.0.0

package/src/sdk/autoTracking.ts

@@ -0,0 +1,1373 @@
+/**
+ * Rejourney Auto Tracking Module
+ * 
+ * Automatic tracking features that work with just init() - no additional code needed.
+ * This module handles:
+ * - Rage tap detection
+ * - Error tracking (JS + React Native)
+ * - Session metrics aggregation
+ * - Device info collection
+ * - Anonymous ID generation
+ * - Funnel/screen tracking
+ * - Score calculations
+ * 
+ * IMPORTANT: This file uses lazy loading for react-native imports to avoid
+ * "PlatformConstants could not be found" errors on RN 0.81+.
+ */
+
+import type {
+  DeviceInfo,
+  ErrorEvent,
+} from '../types';
+import { logger } from './utils';
+
+// Lazy-loaded React Native modules
+let _RN: typeof import('react-native') | null = null;
+
+function getRN(): typeof import('react-native') | null {
+  if (_RN) return _RN;
+  try {
+    _RN = require('react-native');
+    return _RN;
+  } catch {
+    return null;
+  }
+}
+
+function getPlatform() {
+  return getRN()?.Platform;
+}
+
+function getDimensions() {
+  return getRN()?.Dimensions;
+}
+
+function getNativeModules() {
+  return getRN()?.NativeModules;
+}
+
+function getRejourneyNativeModule() {
+  const RN = getRN();
+  if (!RN) return null;
+
+  const { TurboModuleRegistry, NativeModules } = RN;
+  let nativeModule = null;
+
+  if (TurboModuleRegistry && typeof TurboModuleRegistry.get === 'function') {
+    try {
+      nativeModule = TurboModuleRegistry.get('Rejourney');
+    } catch {
+      // Ignore and fall back to NativeModules
+    }
+  }
+
+  if (!nativeModule && NativeModules) {
+    nativeModule = NativeModules.Rejourney ?? null;
+  }
+
+  return nativeModule;
+}
+
+// Type declarations for browser globals (only used in hybrid apps where DOM is available)
+// These don't exist in pure React Native but are needed for error tracking in hybrid scenarios
+type OnErrorEventHandler = ((
+  event: Event | string,
+  source?: string,
+  lineno?: number,
+  colno?: number,
+  error?: Error
+) => boolean | void) | null;
+
+interface PromiseRejectionEvent {
+  reason?: any;
+  promise?: Promise<any>;
+}
+
+// Cast globalThis to work with both RN and hybrid scenarios
+const _globalThis = globalThis as typeof globalThis & {
+  onerror?: OnErrorEventHandler;
+  addEventListener?: (type: string, handler: (event: any) => void) => void;
+  removeEventListener?: (type: string, handler: (event: any) => void) => void;
+  ErrorUtils?: {
+    getGlobalHandler: () => ((error: Error, isFatal: boolean) => void) | undefined;
+    setGlobalHandler: (handler: (error: Error, isFatal: boolean) => void) => void;
+  };
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TapEvent {
+  x: number;
+  y: number;
+  timestamp: number;
+  targetId?: string;
+}
+
+export interface SessionMetrics {
+  // Core counts
+  totalEvents: number;
+  touchCount: number;
+  scrollCount: number;
+  gestureCount: number;
+  inputCount: number;
+  navigationCount: number;
+
+  // Issue tracking
+  errorCount: number;
+  rageTapCount: number;
+
+  // API metrics
+  apiSuccessCount: number;
+  apiErrorCount: number;
+  apiTotalCount: number;
+
+  // Network timing (for avg calculation)
+  netTotalDurationMs: number;  // Sum of all API durations
+  netTotalBytes: number;       // Sum of all response bytes
+
+  // Screen tracking for funnels
+  screensVisited: string[];
+  uniqueScreensCount: number;
+
+  // Scores (0-100)
+  interactionScore: number;
+  explorationScore: number;
+  uxScore: number;
+}
+
+export interface AutoTrackingConfig {
+  // Rage tap detection
+  rageTapThreshold?: number;    // Number of taps (default: 3)
+  rageTapTimeWindow?: number;   // Time window in ms (default: 500)
+  rageTapRadius?: number;       // Max radius in pixels (default: 50)
+
+  // Error tracking
+  trackJSErrors?: boolean;      // Track window errors (default: true)
+  trackPromiseRejections?: boolean; // Track unhandled rejections (default: true)
+  trackReactNativeErrors?: boolean; // Track RN ErrorUtils (default: true)
+
+  // Session settings
+  collectDeviceInfo?: boolean;  // Collect device info (default: true)
+  maxSessionDurationMs?: number; // Clamp to 1–10 minutes; default set from server/config
+}
+
+// =============================================================================
+// State
+// =============================================================================
+
+let isInitialized = false;
+let config: AutoTrackingConfig = {};
+
+// Rage tap tracking
+const recentTaps: TapEvent[] = [];
+let tapHead = 0; // Circular buffer head pointer
+let tapCount = 0; // Actual count of taps in buffer
+const MAX_RECENT_TAPS = 10;
+
+// Session metrics
+let metrics: SessionMetrics = createEmptyMetrics();
+let sessionStartTime: number = 0;
+let maxSessionDurationMs: number = 10 * 60 * 1000;
+
+// Screen tracking
+let currentScreen = '';
+let screensVisited: string[] = [];
+
+// Anonymous ID
+let anonymousId: string | null = null;
+let anonymousIdPromise: Promise<string> | null = null;
+
+// Callbacks
+let onRageTapDetected: ((count: number, x: number, y: number) => void) | null = null;
+let onErrorCaptured: ((error: ErrorEvent) => void) | null = null;
+let onScreenChange: ((screenName: string, previousScreen?: string) => void) | null = null;
+
+// Original error handlers (for restoration)
+let originalErrorHandler: ((error: Error, isFatal: boolean) => void) | undefined;
+let originalOnError: OnErrorEventHandler | null = null;
+let originalOnUnhandledRejection: ((event: PromiseRejectionEvent) => void) | null = null;
+
+// =============================================================================
+// Initialization
+// =============================================================================
+
+/**
+ * Initialize auto tracking features
+ * Called automatically by Rejourney.init() - no user action needed
+ */
+export function initAutoTracking(
+  trackingConfig: AutoTrackingConfig,
+  callbacks: {
+    onRageTap?: (count: number, x: number, y: number) => void;
+    onError?: (error: ErrorEvent) => void;
+    onScreen?: (screenName: string, previousScreen?: string) => void;
+  } = {}
+): void {
+  if (isInitialized) return;
+
+  config = {
+    rageTapThreshold: 3,
+    rageTapTimeWindow: 500,
+    rageTapRadius: 50,
+    trackJSErrors: true,
+    trackPromiseRejections: true,
+    trackReactNativeErrors: true,
+    collectDeviceInfo: true,
+    maxSessionDurationMs: trackingConfig.maxSessionDurationMs,
+    ...trackingConfig,
+  };
+
+  // Session timing
+  sessionStartTime = Date.now();
+  setMaxSessionDurationMinutes(
+    trackingConfig.maxSessionDurationMs
+      ? trackingConfig.maxSessionDurationMs / 60000
+      : undefined
+  );
+
+  // Set callbacks
+  onRageTapDetected = callbacks.onRageTap || null;
+  onErrorCaptured = callbacks.onError || null;
+  onScreenChange = callbacks.onScreen || null;
+
+  // Initialize metrics
+  metrics = createEmptyMetrics();
+  sessionStartTime = Date.now();
+  anonymousId = generateAnonymousId();
+
+  // Setup error tracking
+  setupErrorTracking();
+
+  // Setup React Navigation tracking (if available)
+  setupNavigationTracking();
+
+  isInitialized = true;
+}
+
+/**
+ * Cleanup auto tracking features
+ */
+export function cleanupAutoTracking(): void {
+  if (!isInitialized) return;
+
+  // Restore original error handlers
+  restoreErrorHandlers();
+
+  // Cleanup navigation tracking
+  cleanupNavigationTracking();
+
+  // Reset state
+  tapHead = 0;
+  tapCount = 0;
+  metrics = createEmptyMetrics();
+  screensVisited = [];
+  currentScreen = '';
+  sessionStartTime = 0;
+  maxSessionDurationMs = 10 * 60 * 1000;
+  isInitialized = false;
+}
+
+// =============================================================================
+// Rage Tap Detection
+// =============================================================================
+
+/**
+ * Track a tap event for rage tap detection
+ * Called automatically from touch interceptor
+ */
+export function trackTap(tap: TapEvent): void {
+  if (!isInitialized) return;
+
+  const now = Date.now();
+
+  // Add to circular buffer (O(1) instead of shift() which is O(n))
+  const insertIndex = (tapHead + tapCount) % MAX_RECENT_TAPS;
+  if (tapCount < MAX_RECENT_TAPS) {
+    recentTaps[insertIndex] = { ...tap, timestamp: now };
+    tapCount++;
+  } else {
+    // Buffer full, overwrite oldest
+    recentTaps[tapHead] = { ...tap, timestamp: now };
+    tapHead = (tapHead + 1) % MAX_RECENT_TAPS;
+  }
+
+  // Evict old taps outside time window
+  const windowStart = now - (config.rageTapTimeWindow || 500);
+  while (tapCount > 0) {
+    const oldestTap = recentTaps[tapHead];
+    if (oldestTap && oldestTap.timestamp < windowStart) {
+      tapHead = (tapHead + 1) % MAX_RECENT_TAPS;
+      tapCount--;
+    } else {
+      break;
+    }
+  }
+
+  // Check for rage tap
+  detectRageTap();
+
+  // Update metrics
+  metrics.touchCount++;
+  metrics.totalEvents++;
+}
+
+/**
+ * Detect if recent taps form a rage tap pattern
+ */
+function detectRageTap(): void {
+  const threshold = config.rageTapThreshold || 3;
+  const radius = config.rageTapRadius || 50;
+
+  if (tapCount < threshold) return;
+  // Check last N taps from circular buffer
+  const tapsToCheck: TapEvent[] = [];
+  for (let i = 0; i < threshold; i++) {
+    const idx = (tapHead + tapCount - threshold + i) % MAX_RECENT_TAPS;
+    tapsToCheck.push(recentTaps[idx]!);
+  }
+
+  // Calculate center point
+  let centerX = 0;
+  let centerY = 0;
+  for (const tap of tapsToCheck) {
+    centerX += tap.x;
+    centerY += tap.y;
+  }
+  centerX /= tapsToCheck.length;
+  centerY /= tapsToCheck.length;
+
+  // Check if all taps are within radius of center
+  let allWithinRadius = true;
+  for (const tap of tapsToCheck) {
+    const dx = tap.x - centerX;
+    const dy = tap.y - centerY;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    if (distance > radius) {
+      allWithinRadius = false;
+      break;
+    }
+  }
+
+  if (allWithinRadius) {
+    // Rage tap detected!
+    metrics.rageTapCount++;
+    // Clear circular buffer to prevent duplicate detection
+    tapHead = 0;
+    tapCount = 0;
+
+    // Notify callback
+    if (onRageTapDetected) {
+      onRageTapDetected(threshold, centerX, centerY);
+    }
+  }
+}
+
+// =============================================================================
+// State Change Notification
+// =============================================================================
+
+/**
+ * Notify that a state change occurred (navigation, modal, etc.)
+ * Kept for API compatibility
+ */
+export function notifyStateChange(): void {
+  // No-op - kept for backward compatibility
+}
+
+// =============================================================================
+// Error Tracking
+// =============================================================================
+
+/**
+ * Setup automatic error tracking
+ */
+function setupErrorTracking(): void {
+  // Track React Native errors
+  if (config.trackReactNativeErrors !== false) {
+    setupReactNativeErrorHandler();
+  }
+
+  // Track JavaScript errors (only works in web/debug)
+  if (config.trackJSErrors !== false && typeof _globalThis !== 'undefined') {
+    setupJSErrorHandler();
+  }
+
+  // Track unhandled promise rejections
+  if (config.trackPromiseRejections !== false && typeof _globalThis !== 'undefined') {
+    setupPromiseRejectionHandler();
+  }
+}
+
+/**
+ * Setup React Native ErrorUtils handler
+ */
+function setupReactNativeErrorHandler(): void {
+  try {
+    // Access ErrorUtils from global scope
+    const ErrorUtils = _globalThis.ErrorUtils;
+    if (!ErrorUtils) return;
+
+    // Store original handler
+    originalErrorHandler = ErrorUtils.getGlobalHandler();
+
+    // Set new handler
+    ErrorUtils.setGlobalHandler((error: Error, isFatal: boolean) => {
+      // Track the error
+      trackError({
+        type: 'error',
+        timestamp: Date.now(),
+        message: error.message || String(error),
+        stack: error.stack,
+        name: error.name || 'Error',
+      });
+
+      // Call original handler
+      if (originalErrorHandler) {
+        originalErrorHandler(error, isFatal);
+      }
+    });
+  } catch {
+    // ErrorUtils not available
+  }
+}
+
+/**
+ * Setup global JS error handler
+ */
+function setupJSErrorHandler(): void {
+  if (typeof _globalThis.onerror !== 'undefined') {
+    // Note: In React Native, this typically doesn't fire
+    // But we set it up anyway for hybrid apps
+    originalOnError = _globalThis.onerror;
+
+    _globalThis.onerror = (
+      message: string | Event,
+      source?: string,
+      lineno?: number,
+      colno?: number,
+      error?: Error
+    ) => {
+      trackError({
+        type: 'error',
+        timestamp: Date.now(),
+        message: typeof message === 'string' ? message : 'Unknown error',
+        stack: error?.stack || `${source}:${lineno}:${colno}`,
+        name: error?.name || 'Error',
+      });
+
+      // Call original handler
+      if (originalOnError) {
+        return originalOnError(message, source, lineno, colno, error);
+      }
+      return false;
+    };
+  }
+}
+
+/**
+ * Setup unhandled promise rejection handler
+ */
+function setupPromiseRejectionHandler(): void {
+  if (typeof _globalThis.addEventListener !== 'undefined') {
+    const handler = (event: PromiseRejectionEvent) => {
+      const reason = event.reason;
+      trackError({
+        type: 'error',
+        timestamp: Date.now(),
+        message: reason?.message || String(reason) || 'Unhandled Promise Rejection',
+        stack: reason?.stack,
+        name: reason?.name || 'UnhandledRejection',
+      });
+    };
+
+    originalOnUnhandledRejection = handler;
+    _globalThis.addEventListener!('unhandledrejection', handler);
+  }
+}
+
+/**
+ * Restore original error handlers
+ */
+function restoreErrorHandlers(): void {
+  // Restore React Native handler
+  if (originalErrorHandler) {
+    try {
+      const ErrorUtils = _globalThis.ErrorUtils;
+      if (ErrorUtils) {
+        ErrorUtils.setGlobalHandler(originalErrorHandler);
+      }
+    } catch {
+      // Ignore
+    }
+    originalErrorHandler = undefined;
+  }
+
+  // Restore global onerror
+  if (originalOnError !== null) {
+    _globalThis.onerror = originalOnError;
+    originalOnError = null;
+  }
+
+  // Remove promise rejection handler
+  if (originalOnUnhandledRejection && typeof _globalThis.removeEventListener !== 'undefined') {
+    _globalThis.removeEventListener!('unhandledrejection', originalOnUnhandledRejection);
+    originalOnUnhandledRejection = null;
+  }
+}
+
+/**
+ * Track an error
+ */
+function trackError(error: ErrorEvent): void {
+  metrics.errorCount++;
+  metrics.totalEvents++;
+
+  if (onErrorCaptured) {
+    onErrorCaptured(error);
+  }
+}
+
+/**
+ * Manually track an error (for API errors, etc.)
+ */
+export function captureError(
+  message: string,
+  stack?: string,
+  name?: string
+): void {
+  trackError({
+    type: 'error',
+    timestamp: Date.now(),
+    message,
+    stack,
+    name: name || 'Error',
+  });
+}
+
+// =============================================================================
+// Screen/Funnel Tracking - Automatic Navigation Detection
+// =============================================================================
+
+// Navigation detection state
+let navigationPollingInterval: ReturnType<typeof setInterval> | null = null;
+let lastDetectedScreen = '';
+let navigationSetupDone = false;
+let navigationPollingErrors = 0; // Track consecutive errors
+const MAX_POLLING_ERRORS = 10; // Stop polling after 10 consecutive errors
+
+/**
+ * Track a navigation state change from React Navigation.
+ * 
+ * For bare React Native apps using @react-navigation/native.
+ * Just add this to your NavigationContainer's onStateChange prop.
+ * 
+ * @example
+ * ```tsx
+ * import { trackNavigationState } from 'rejourney';
+ * 
+ * <NavigationContainer onStateChange={trackNavigationState}>
+ *   ...
+ * </NavigationContainer>
+ * ```
+ */
+export function trackNavigationState(state: any): void {
+  if (!state?.routes) return;
+
+  try {
+    const { normalizeScreenName } = require('./navigation');
+
+    // Find the active screen recursively
+    const findActiveScreen = (navState: any): string | null => {
+      if (!navState?.routes) return null;
+      const index = navState.index ?? navState.routes.length - 1;
+      const route = navState.routes[index];
+      if (!route) return null;
+      if (route.state) return findActiveScreen(route.state);
+      return normalizeScreenName(route.name || 'Unknown');
+    };
+
+    const screenName = findActiveScreen(state);
+    if (screenName && screenName !== lastDetectedScreen) {
+      lastDetectedScreen = screenName;
+      trackScreen(screenName);
+    }
+  } catch {
+    // Navigation tracking error
+  }
+}
+
+/**
+ * React hook for navigation tracking.
+ * 
+ * Returns props to spread on NavigationContainer that will:
+ * 1. Track the initial screen on mount (via onReady)
+ * 2. Track all subsequent navigations (via onStateChange)
+ * 
+ * This is the RECOMMENDED approach for bare React Native apps.
+ * 
+ * @example
+ * ```tsx
+ * import { useNavigationTracking } from 'rejourney';
+ * import { NavigationContainer } from '@react-navigation/native';
+ * 
+ * function App() {
+ *   const navigationTracking = useNavigationTracking();
+ *   
+ *   return (
+ *     <NavigationContainer {...navigationTracking}>
+ *       <RootNavigator />
+ *     </NavigationContainer>
+ *   );
+ * }
+ * ```
+ */
+export function useNavigationTracking() {
+  // Use React's useRef and useCallback to create stable references
+  const React = require('react');
+  const { createNavigationContainerRef } = require('@react-navigation/native');
+
+  // Create a stable navigation ref
+  const navigationRef = React.useRef(createNavigationContainerRef());
+
+  // Track initial screen when navigation is ready
+  const onReady = React.useCallback(() => {
+    try {
+      const currentRoute = navigationRef.current?.getCurrentRoute?.();
+      if (currentRoute?.name) {
+        const { normalizeScreenName } = require('./navigation');
+        const screenName = normalizeScreenName(currentRoute.name);
+        if (screenName && screenName !== lastDetectedScreen) {
+          lastDetectedScreen = screenName;
+          trackScreen(screenName);
+        }
+      }
+    } catch {
+      // Navigation not ready yet
+    }
+  }, []);
+
+  // Return props to spread on NavigationContainer
+  return {
+    ref: navigationRef.current,
+    onReady,
+    onStateChange: trackNavigationState,
+  };
+}
+
+/**
+ * Setup automatic Expo Router tracking
+ * 
+ * For Expo apps using expo-router - works automatically.
+ * For bare React Native apps - use trackNavigationState instead.
+ */
+function setupNavigationTracking(): void {
+  if (navigationSetupDone) return;
+  navigationSetupDone = true;
+
+  if (__DEV__) {
+    logger.debug('Setting up navigation tracking...');
+  }
+
+  // Delay to ensure navigation is initialized - Expo Router needs more time
+  // We retry a few times with increasing delays
+  let attempts = 0;
+  const maxAttempts = 5;
+  
+  const trySetup = () => {
+    attempts++;
+    if (__DEV__) {
+      logger.debug('Navigation setup attempt', attempts, 'of', maxAttempts);
+    }
+    
+    const success = trySetupExpoRouter();
+    
+    if (success) {
+      if (__DEV__) {
+        logger.debug('Expo Router setup: SUCCESS on attempt', attempts);
+      }
+    } else if (attempts < maxAttempts) {
+      // Retry with exponential backoff
+      const delay = 200 * attempts; // 200, 400, 600, 800ms
+      if (__DEV__) {
+        logger.debug('Expo Router not ready, retrying in', delay, 'ms');
+      }
+      setTimeout(trySetup, delay);
+    } else {
+      if (__DEV__) {
+        logger.debug('Expo Router setup: FAILED after', maxAttempts, 'attempts');
+        logger.debug('For manual navigation tracking, use trackNavigationState() on your NavigationContainer');
+      }
+    }
+  };
+
+  // Start first attempt after 200ms
+  setTimeout(trySetup, 200);
+}
+
+/**
+   * Set up Expo Router auto-tracking by polling the internal router store
+   * 
+   * Supports both expo-router v3 (store.rootState) and v6+ (store.state, store.navigationRef)
+   */
+function trySetupExpoRouter(): boolean {
+  try {
+    const expoRouter = require('expo-router');
+    const router = expoRouter.router;
+
+    if (!router) {
+      if (__DEV__) {
+        logger.debug('Expo Router: router object not found');
+      }
+      return false;
+    }
+
+    if (__DEV__) {
+      logger.debug('Expo Router: Setting up navigation tracking');
+    }
+
+    const { normalizeScreenName, getScreenNameFromPath } = require('./navigation');
+
+    // Poll for route changes (expo-router doesn't expose a listener API outside hooks)
+    navigationPollingInterval = setInterval(() => {
+      try {
+        let state = null;
+        let stateSource = '';
+
+        // Method 1: Public accessors on router object
+        if (typeof router.getState === 'function') {
+          state = router.getState();
+          stateSource = 'router.getState()';
+        } else if ((router as any).rootState) {
+          state = (router as any).rootState;
+          stateSource = 'router.rootState';
+        }
+
+        // Method 2: Internal store access (works for both v3 and v6+)
+        if (!state) {
+          try {
+            const storeModule = require('expo-router/build/global-state/router-store');
+            if (storeModule?.store) {
+              // v6+: store.state or store.navigationRef
+              state = storeModule.store.state;
+              if (state) stateSource = 'store.state';
+
+              // v6+: Try navigationRef if state is undefined
+              if (!state && storeModule.store.navigationRef?.current) {
+                state = storeModule.store.navigationRef.current.getRootState?.();
+                if (state) stateSource = 'navigationRef.getRootState()';
+              }
+
+              // v3: store.rootState or store.initialState
+              if (!state) {
+                state = storeModule.store.rootState || storeModule.store.initialState;
+                if (state) stateSource = 'store.rootState/initialState';
+              }
+            }
+          } catch {
+            // Store not available
+          }
+        }
+
+        // Method 3: Try accessing via a different export path for v6
+        if (!state) {
+          try {
+            const imperative = require('expo-router/build/imperative-api');
+            if (imperative?.router) {
+              state = imperative.router.getState?.();
+              if (state) stateSource = 'imperative-api';
+            }
+          } catch {
+            // Imperative API not available
+          }
+        }
+
+        if (state) {
+          // Reset error count on success
+          navigationPollingErrors = 0;
+          const screenName = extractScreenNameFromRouterState(state, getScreenNameFromPath, normalizeScreenName);
+          if (screenName && screenName !== lastDetectedScreen) {
+            if (__DEV__) {
+              logger.debug('Screen changed:', lastDetectedScreen, '->', screenName, `(source: ${stateSource})`);
+            }
+            lastDetectedScreen = screenName;
+            trackScreen(screenName);
+          }
+        } else {
+          // Track consecutive failures to get state
+          navigationPollingErrors++;
+          if (__DEV__ && navigationPollingErrors === 1) {
+            logger.debug('Expo Router: Could not get navigation state');
+          }
+          if (navigationPollingErrors >= MAX_POLLING_ERRORS) {
+            // Stop polling after too many errors to save CPU
+            if (__DEV__) {
+              logger.debug('Expo Router: Stopped polling after', MAX_POLLING_ERRORS, 'errors');
+            }
+            cleanupNavigationTracking();
+          }
+        }
+      } catch (e) {
+        // Error - track and potentially stop
+        navigationPollingErrors++;
+        if (__DEV__ && navigationPollingErrors === 1) {
+          logger.debug('Expo Router polling error:', e);
+        }
+        if (navigationPollingErrors >= MAX_POLLING_ERRORS) {
+          cleanupNavigationTracking();
+        }
+      }
+    }, 500); // 500ms polling (reduced from 300ms for lower CPU usage)
+
+    return true;
+  } catch (e) {
+    if (__DEV__) {
+      logger.debug('Expo Router not available:', e);
+    }
+    // expo-router not installed
+    return false;
+  }
+}
+
+/**
+ * Extract screen name from Expo Router navigation state
+ * 
+ * Handles complex nested structures like Drawer → Tabs → Stack
+ * by recursively accumulating segments from each navigation level.
+ */
+function extractScreenNameFromRouterState(
+  state: any,
+  getScreenNameFromPath: (path: string, segments: string[]) => string,
+  normalizeScreenName: (name: string) => string,
+  accumulatedSegments: string[] = []
+): string | null {
+  if (!state?.routes) return null;
+
+  const route = state.routes[state.index ?? state.routes.length - 1];
+  if (!route) return null;
+
+  // Add current route name to accumulated segments
+  const newSegments = [...accumulatedSegments, route.name];
+
+  // If this route has nested state, recurse deeper
+  if (route.state) {
+    return extractScreenNameFromRouterState(
+      route.state,
+      getScreenNameFromPath,
+      normalizeScreenName,
+      newSegments
+    );
+  }
+
+  // We've reached the deepest level - build the screen name
+  // Filter out group markers like (tabs), (main), (auth)
+  const cleanSegments = newSegments.filter(s => !s.startsWith('(') && !s.endsWith(')'));
+
+  // If after filtering we have no segments, use the last meaningful name
+  if (cleanSegments.length === 0) {
+    // Find the last non-group segment
+    for (let i = newSegments.length - 1; i >= 0; i--) {
+      const seg = newSegments[i];
+      if (seg && !seg.startsWith('(') && !seg.endsWith(')')) {
+        cleanSegments.push(seg);
+        break;
+      }
+    }
+  }
+
+  const pathname = '/' + cleanSegments.join('/');
+  return getScreenNameFromPath(pathname, newSegments);
+}
+
+/**
+ * Cleanup navigation tracking
+ */
+function cleanupNavigationTracking(): void {
+  if (navigationPollingInterval) {
+    clearInterval(navigationPollingInterval);
+    navigationPollingInterval = null;
+  }
+  navigationSetupDone = false;
+  lastDetectedScreen = '';
+  navigationPollingErrors = 0;
+}
+
+/**
+ * Track a screen view
+ * This updates JS metrics AND notifies the native module to send to backend
+ */
+export function trackScreen(screenName: string): void {
+  if (!isInitialized) {
+    if (__DEV__) {
+      logger.debug('trackScreen called but not initialized, screen:', screenName);
+    }
+    return;
+  }
+
+  const previousScreen = currentScreen;
+  currentScreen = screenName;
+  // Add to screens visited (only track for unique set, avoid large array copies)
+  screensVisited.push(screenName);
+
+  // Update unique screens count
+  const uniqueScreens = new Set(screensVisited);
+  metrics.uniqueScreensCount = uniqueScreens.size;
+
+  // Update navigation count
+  metrics.navigationCount++;
+  metrics.totalEvents++;
+
+  if (__DEV__) {
+    logger.debug('trackScreen:', screenName, '(total screens:', metrics.uniqueScreensCount, ')');
+  }
+
+  // Notify callback
+  if (onScreenChange) {
+    onScreenChange(screenName, previousScreen);
+  }
+
+  // IMPORTANT: Also notify native module to send to backend
+  // This is the key fix - without this, screens don't get recorded!
+  try {
+    const RejourneyNative = getRejourneyNativeModule();
+    if (RejourneyNative?.screenChanged) {
+      if (__DEV__) {
+        logger.debug('Notifying native screenChanged:', screenName);
+      }
+      RejourneyNative.screenChanged(screenName).catch((e: Error) => {
+        if (__DEV__) {
+          logger.debug('Native screenChanged error:', e);
+        }
+      });
+    } else if (__DEV__) {
+      logger.debug('Native screenChanged method not available');
+    }
+  } catch (e) {
+    if (__DEV__) {
+      logger.debug('trackScreen native call error:', e);
+    }
+  }
+}
+
+// =============================================================================
+// API Metrics Tracking
+// =============================================================================
+
+/**
+ * Track an API request with timing data
+ */
+export function trackAPIRequest(
+  success: boolean,
+  _statusCode: number,
+  durationMs: number = 0,
+  responseBytes: number = 0
+): void {
+  if (!isInitialized) return;
+
+  metrics.apiTotalCount++;
+
+  // Accumulate timing and size for avg calculation
+  if (durationMs > 0) {
+    metrics.netTotalDurationMs += durationMs;
+  }
+  if (responseBytes > 0) {
+    metrics.netTotalBytes += responseBytes;
+  }
+
+  if (success) {
+    metrics.apiSuccessCount++;
+  } else {
+    metrics.apiErrorCount++;
+
+    // API errors also count toward error count for UX score
+    metrics.errorCount++;
+  }
+}
+
+// =============================================================================
+// Session Metrics
+// =============================================================================
+
+/**
+ * Create empty metrics object
+ */
+function createEmptyMetrics(): SessionMetrics {
+  return {
+    totalEvents: 0,
+    touchCount: 0,
+    scrollCount: 0,
+    gestureCount: 0,
+    inputCount: 0,
+    navigationCount: 0,
+    errorCount: 0,
+    rageTapCount: 0,
+    apiSuccessCount: 0,
+    apiErrorCount: 0,
+    apiTotalCount: 0,
+    netTotalDurationMs: 0,
+    netTotalBytes: 0,
+    screensVisited: [],
+    uniqueScreensCount: 0,
+    interactionScore: 100,
+    explorationScore: 100,
+    uxScore: 100,
+  };
+}
+
+/**
+ * Track a scroll event
+ */
+export function trackScroll(): void {
+  if (!isInitialized) return;
+  metrics.scrollCount++;
+  metrics.totalEvents++;
+}
+
+/**
+ * Track a gesture event
+ */
+export function trackGesture(): void {
+  if (!isInitialized) return;
+  metrics.gestureCount++;
+  metrics.totalEvents++;
+}
+
+/**
+ * Track an input event (keyboard)
+ */
+export function trackInput(): void {
+  if (!isInitialized) return;
+  metrics.inputCount++;
+  metrics.totalEvents++;
+}
+
+/**
+ * Get current session metrics
+ */
+export function getSessionMetrics(): SessionMetrics & { netAvgDurationMs: number } {
+  // Calculate scores before returning
+  calculateScores();
+
+  // Compute average API response time
+  const netAvgDurationMs = metrics.apiTotalCount > 0
+    ? Math.round(metrics.netTotalDurationMs / metrics.apiTotalCount)
+    : 0;
+
+  // Lazily populate screensVisited only when metrics are retrieved
+  // This avoids expensive array copies on every screen change
+  return {
+    ...metrics,
+    screensVisited: [...screensVisited], // Only copy here when needed
+    netAvgDurationMs,
+  };
+}
+
+/**
+ * Calculate session scores
+ */
+function calculateScores(): void {
+  // Interaction Score (0-100)
+  // Based on total interactions normalized to a baseline
+  const totalInteractions =
+    metrics.touchCount +
+    metrics.scrollCount +
+    metrics.gestureCount +
+    metrics.inputCount;
+
+  // Assume 50 interactions is "average" for a session
+  const avgInteractions = 50;
+  metrics.interactionScore = Math.min(100, Math.round((totalInteractions / avgInteractions) * 100));
+
+  // Exploration Score (0-100)
+  // Based on unique screens visited
+  // Assume 5 screens is "average" exploration
+  const avgScreens = 5;
+  metrics.explorationScore = Math.min(100, Math.round((metrics.uniqueScreensCount / avgScreens) * 100));
+
+  // UX Score (0-100)
+  // Starts at 100, deducts for issues
+  let uxScore = 100;
+
+  // Deduct for errors
+  uxScore -= Math.min(30, metrics.errorCount * 15); // Max 30 point deduction
+
+  // Deduct for rage taps
+  uxScore -= Math.min(24, metrics.rageTapCount * 8); // Max 24 point deduction
+
+  // Deduct for API errors
+  uxScore -= Math.min(20, metrics.apiErrorCount * 10); // Max 20 point deduction
+
+  // Bonus for completing funnel (if screens > 3)
+  if (metrics.uniqueScreensCount >= 3) {
+    uxScore += 5;
+  }
+
+  metrics.uxScore = Math.max(0, Math.min(100, uxScore));
+}
+
+/**
+ * Reset metrics for new session
+ */
+export function resetMetrics(): void {
+  metrics = createEmptyMetrics();
+  screensVisited = [];
+  currentScreen = '';
+  tapHead = 0;
+  tapCount = 0;
+  sessionStartTime = Date.now();
+}
+
+// =============================================================================
+// Session duration helpers
+// =============================================================================
+
+/** Clamp and set max session duration in minutes (1–10). Defaults to 10. */
+export function setMaxSessionDurationMinutes(minutes?: number): void {
+  const clampedMinutes = Math.min(10, Math.max(1, minutes ?? 10));
+  maxSessionDurationMs = clampedMinutes * 60 * 1000;
+}
+
+/** Returns true if the current session exceeded the configured max duration. */
+export function hasExceededMaxSessionDuration(): boolean {
+  if (!sessionStartTime) return false;
+  return Date.now() - sessionStartTime >= maxSessionDurationMs;
+}
+
+/** Returns remaining milliseconds until the session should stop. */
+export function getRemainingSessionDurationMs(): number {
+  if (!sessionStartTime) return maxSessionDurationMs;
+  const remaining = maxSessionDurationMs - (Date.now() - sessionStartTime);
+  return Math.max(0, remaining);
+}
+
+// =============================================================================
+// Device Info Collection
+// =============================================================================
+
+/**
+ * Collect device information
+ */
+export function collectDeviceInfo(): DeviceInfo {
+  const Dimensions = getDimensions();
+  const Platform = getPlatform();
+  const NativeModules = getNativeModules();
+  
+  // Default values if react-native isn't available
+  let width = 0, height = 0, scale = 1;
+  
+  if (Dimensions) {
+    const windowDims = Dimensions.get('window');
+    const screenDims = Dimensions.get('screen');
+    width = windowDims?.width || 0;
+    height = windowDims?.height || 0;
+    scale = screenDims?.scale || 1;
+  }
+
+  // Get device model - this varies by platform
+  let model = 'Unknown';
+  let manufacturer: string | undefined;
+  let osVersion = 'Unknown';
+  let appVersion: string | undefined;
+  let appId: string | undefined;
+  let locale: string | undefined;
+  let timezone: string | undefined;
+
+  try {
+    // Try to get from react-native-device-info if available
+    // This is optional - falls back to basic info if not installed
+    const DeviceInfo = require('react-native-device-info');
+    model = DeviceInfo.getModel?.() || model;
+    manufacturer = DeviceInfo.getBrand?.() || undefined;
+    osVersion = DeviceInfo.getSystemVersion?.() || osVersion;
+    appVersion = DeviceInfo.getVersion?.() || undefined;
+    appId = DeviceInfo.getBundleId?.() || undefined;
+    locale = DeviceInfo.getDeviceLocale?.() || undefined;
+    timezone = DeviceInfo.getTimezone?.() || undefined;
+  } catch {
+    // react-native-device-info not installed, try Expo packages
+    try {
+      // Try expo-application for app version/id
+      const Application = require('expo-application');
+      appVersion = Application.nativeApplicationVersion || Application.applicationVersion || undefined;
+      appId = Application.applicationId || undefined;
+    } catch {
+      // expo-application not available
+    }
+
+    try {
+      // Try expo-constants for additional info
+      const Constants = require('expo-constants');
+      const expoConfig = Constants.expoConfig || Constants.manifest2?.extra?.expoClient || Constants.manifest;
+      if (!appVersion && expoConfig?.version) {
+        appVersion = expoConfig.version;
+      }
+      if (!appId && (expoConfig?.ios?.bundleIdentifier || expoConfig?.android?.package)) {
+        appId = Platform?.OS === 'ios'
+          ? expoConfig?.ios?.bundleIdentifier
+          : expoConfig?.android?.package;
+      }
+    } catch {
+      // expo-constants not available
+    }
+
+    // Fall back to basic platform info
+    if (Platform?.OS === 'ios') {
+      // Get basic info from constants
+      const PlatformConstants = NativeModules?.PlatformConstants;
+      osVersion = Platform.Version?.toString() || osVersion;
+      model = PlatformConstants?.interfaceIdiom === 'pad' ? 'iPad' : 'iPhone';
+    } else if (Platform?.OS === 'android') {
+      osVersion = Platform.Version?.toString() || osVersion;
+      model = 'Android Device';
+    }
+  }
+
+  // Get timezone
+  if (!timezone) {
+    try {
+      timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    } catch {
+      timezone = undefined;
+    }
+  }
+
+  // Get locale
+  if (!locale) {
+    try {
+      locale = Intl.DateTimeFormat().resolvedOptions().locale;
+    } catch {
+      locale = undefined;
+    }
+  }
+
+  return {
+    model,
+    manufacturer,
+    os: (Platform?.OS || 'ios') as 'ios' | 'android',
+    osVersion,
+    screenWidth: Math.round(width),
+    screenHeight: Math.round(height),
+    pixelRatio: scale,
+    appVersion,
+    appId,
+    locale,
+    timezone,
+  };
+}
+
+// =============================================================================
+// Anonymous ID Generation
+// =============================================================================
+
+// Storage key for anonymous ID
+const ANONYMOUS_ID_KEY = '@rejourney_anonymous_id';
+
+/**
+ * Generate a persistent anonymous ID
+ */
+function generateAnonymousId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 15);
+  return `anon_${timestamp}_${random}`;
+}
+
+/**
+ * Initialize anonymous ID - tries to load from storage, generates new if not found
+ * This is called internally and runs asynchronously
+ */
+async function initAnonymousId(): Promise<void> {
+  try {
+    // Try to load from AsyncStorage
+    const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+    const storedId = await AsyncStorage.getItem(ANONYMOUS_ID_KEY);
+
+    if (storedId) {
+      anonymousId = storedId;
+    } else {
+      // Generate new ID and persist
+      anonymousId = generateAnonymousId();
+      await AsyncStorage.setItem(ANONYMOUS_ID_KEY, anonymousId);
+    }
+  } catch {
+    // AsyncStorage not available or error - just generate without persistence
+    if (!anonymousId) {
+      anonymousId = generateAnonymousId();
+    }
+  }
+}
+
+/**
+ * Get the anonymous ID (synchronous - returns generated ID immediately)
+ * For persistent ID, call initAnonymousId() first
+ */
+export function getAnonymousId(): string {
+  if (!anonymousId) {
+    anonymousId = generateAnonymousId();
+    // Try to persist asynchronously (fire and forget)
+    initAnonymousId().catch(() => { });
+  }
+  return anonymousId;
+}
+
+/**
+ * Ensure a stable, persisted anonymous/device ID is available.
+ * Returns the stored ID if present, otherwise generates and persists one.
+ */
+export async function ensurePersistentAnonymousId(): Promise<string> {
+  if (anonymousId) return anonymousId;
+  if (!anonymousIdPromise) {
+    anonymousIdPromise = (async () => {
+      await initAnonymousId();
+      if (!anonymousId) {
+        anonymousId = generateAnonymousId();
+      }
+      return anonymousId;
+    })();
+  }
+  return anonymousIdPromise;
+}
+
+/**
+ * Load anonymous ID from persistent storage
+ * Call this at app startup for best results
+ */
+export async function loadAnonymousId(): Promise<string> {
+  await initAnonymousId();
+  return anonymousId || generateAnonymousId();
+}
+
+/**
+ * Set a custom anonymous ID (e.g., from persistent storage)
+ */
+export function setAnonymousId(id: string): void {
+  anonymousId = id;
+  // Try to persist asynchronously
+  try {
+    const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+    AsyncStorage.setItem(ANONYMOUS_ID_KEY, id).catch(() => { });
+  } catch {
+    // Ignore if AsyncStorage not available
+  }
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export default {
+  init: initAutoTracking,
+  cleanup: cleanupAutoTracking,
+  trackTap,
+  trackScroll,
+  trackGesture,
+  trackInput,
+  trackScreen,
+  trackAPIRequest,
+  captureError,
+  getMetrics: getSessionMetrics,
+  resetMetrics,
+  collectDeviceInfo,
+  getAnonymousId,
+  setAnonymousId,
+};