@datalyr/react-native 1.6.4 → 1.7.0

package/README.md

@@ -27,6 +27,7 @@ Mobile analytics and attribution SDK for React Native and Expo. Track events, id
   - [Deferred Attribution](#deferred-attribution)
 - [Customer Journey](#customer-journey)
 - [Event Queue](#event-queue)
+- [Automatic Screen Tracking](#automatic-screen-tracking)
 - [Auto Events](#auto-events)
 - [SKAdNetwork](#skadnetwork)
 - [Platform Integrations](#platform-integrations)
@@ -178,10 +179,10 @@ await Datalyr.initialize({
 
 ```typescript
 interface AutoEventConfig {
-  trackSessions?: boolean;       // Track session_start / session_end
-  trackScreenViews?: boolean;    // Track screen views automatically
-  trackAppUpdates?: boolean;     // Track app_update events
-  trackPerformance?: boolean;    // Track performance metrics
+  trackSessions?: boolean;       // Track session_start / session_end (default: true)
+  trackScreenViews?: boolean;    // Enable screen view events via screen() (default: true)
+  trackAppUpdates?: boolean;     // Track app_update events (default: true)
+  trackPerformance?: boolean;    // Track performance metrics (default: false)
   sessionTimeoutMs?: number;     // Session timeout in ms
 }
 ```
@@ -233,6 +234,8 @@ await Datalyr.screen('Product Details', {
 });
 ```
 
+Each `screen()` call fires a single `pageview` event with the `screen` property set. Session data (`session_id`, `pageviews_in_session`, `previous_screen`) is automatically attached.
+
 ### E-Commerce Events
 
 Standard e-commerce events:
@@ -504,6 +507,98 @@ When the device is offline:
 
 ---
 
+## Automatic Screen Tracking
+
+Track screen views automatically when using React Navigation (v5+/v6+). The `datalyrScreenTracking` helper wires into the navigation container and fires a `pageview` event on every route change.
+
+### React Navigation
+
+```tsx
+import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+import { datalyrScreenTracking } from '@datalyr/react-native';
+
+function App() {
+  const navigationRef = useNavigationContainerRef();
+  const screenTracking = datalyrScreenTracking(navigationRef);
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={screenTracking.onReady}
+      onStateChange={screenTracking.onStateChange}
+    >
+      {/* ...screens */}
+    </NavigationContainer>
+  );
+}
+```
+
+### Expo with React Navigation
+
+For Expo projects using React Navigation, import from the Expo entry point:
+
+```tsx
+import { datalyrScreenTracking } from '@datalyr/react-native/expo';
+```
+
+The API is identical to the React Navigation example above.
+
+### Expo Router
+
+Expo Router does not expose a `NavigationContainer`, so automatic tracking is not available. Use `datalyr.screen()` manually in your layout files instead:
+
+```tsx
+import { datalyr } from '@datalyr/react-native/expo';
+import { usePathname } from 'expo-router';
+import { useEffect } from 'react';
+
+export default function RootLayout() {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    datalyr.screen(pathname);
+  }, [pathname]);
+
+  return <Slot />;
+}
+```
+
+### Configuration
+
+You can customize screen name transforms, filtering, and property extraction:
+
+```typescript
+const screenTracking = datalyrScreenTracking(navigationRef, {
+  // Clean up route names
+  transformScreenName: (name) => name.replace('Screen', ''),
+
+  // Skip certain screens
+  shouldTrackScreen: (name) => !['Splash', 'Loading'].includes(name),
+
+  // Extract route params as event properties
+  extractProperties: (name, params) => ({
+    product_id: params?.productId,
+  }),
+});
+```
+
+### Advanced: Custom Tracking Function
+
+If you need to control which SDK instance is used, use `createScreenTrackingListeners` instead:
+
+```typescript
+import { createScreenTrackingListeners } from '@datalyr/react-native';
+
+const { onReady, onStateChange } = createScreenTrackingListeners(
+  navigationRef,
+  (screenName, properties) => myCustomSdk.screen(screenName, properties),
+);
+```
+
+> **Note:** If you enable automatic screen tracking, avoid also calling `Datalyr.screen()` manually for the same screens, as this will produce duplicate events.
+
+---
+
 ## Auto Events
 
 Enable automatic lifecycle tracking:

package/lib/auto-events.d.ts

@@ -45,9 +45,16 @@ export declare class AutoEventsManager {
      */
     handleAppBackground(): Promise<void>;
     /**
-     * Track automatic pageview
+     * Update session counters for a screen view.
+     * The actual pageview event is fired by the SDK's screen() method —
+     * this only updates internal session state to avoid double-firing.
      */
-    trackScreenView(screenName: string, properties?: Record<string, any>): Promise<void>;
+    recordScreenView(screenName: string): Promise<void>;
+    /**
+     * Get session data to enrich a pageview event.
+     * Called by the SDK's screen() method to attach session info.
+     */
+    getScreenViewEnrichment(): Record<string, any> | null;
     /**
      * Track app launch performance
      */

package/lib/auto-events.js

@@ -155,35 +155,42 @@ export class AutoEventsManager {
         }
     }
     /**
-     * Track automatic pageview
+     * Update session counters for a screen view.
+     * The actual pageview event is fired by the SDK's screen() method —
+     * this only updates internal session state to avoid double-firing.
      */
-    async trackScreenView(screenName, properties) {
+    async recordScreenView(screenName) {
         try {
             if (!this.config.trackScreenViews)
                 return;
-            // Don't track the same screen twice in a row
+            // Don't count the same screen twice in a row
             if (this.lastScreenName === screenName)
                 return;
-            const screenProperties = {
-                screen_name: screenName,
-                previous_screen: this.lastScreenName,
-                timestamp: Date.now(),
-                ...properties,
-            };
-            // Add session data if available
+            // Update session counters (no event fired here)
             if (this.currentSession) {
                 this.currentSession.screenViews++;
-                screenProperties.session_id = this.currentSession.sessionId;
-                screenProperties.pageviews_in_session = this.currentSession.screenViews;
+                this.currentSession.lastActivity = Date.now();
             }
-            await this.trackEvent('pageview', screenProperties);
             this.lastScreenName = screenName;
-            debugLog('Pageview tracked:', screenName);
+            debugLog('Screen view counted:', screenName);
         }
         catch (error) {
-            errorLog('Error tracking screen view:', error);
+            errorLog('Error updating screen view:', error);
         }
     }
+    /**
+     * Get session data to enrich a pageview event.
+     * Called by the SDK's screen() method to attach session info.
+     */
+    getScreenViewEnrichment() {
+        if (!this.currentSession)
+            return null;
+        return {
+            session_id: this.currentSession.sessionId,
+            pageviews_in_session: this.currentSession.screenViews,
+            previous_screen: this.lastScreenName,
+        };
+    }
     /**
      * Track app launch performance
      */

package/lib/datalyr-sdk.js

@@ -177,7 +177,7 @@ export class DatalyrSDK {
                 const installData = await attributionManager.trackInstall();
                 await this.track('app_install', {
                     platform: Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : 'android',
-                    sdk_version: '1.6.1',
+                    sdk_version: '1.7.0',
                     ...installData,
                 });
             }
@@ -226,11 +226,21 @@ export class DatalyrSDK {
             screen: screenName,
             ...properties,
         };
-        await this.track('pageview', screenData);
-        // Also notify auto-events manager for automatic screen tracking
+        // Enrich with session data (pageview count, previous screen) if available.
+        // User-provided properties take precedence over enrichment.
         if (this.autoEventsManager) {
-            await this.autoEventsManager.trackScreenView(screenName, properties);
+            const enrichment = this.autoEventsManager.getScreenViewEnrichment();
+            if (enrichment) {
+                for (const [key, value] of Object.entries(enrichment)) {
+                    if (!(key in screenData)) {
+                        screenData[key] = value;
+                    }
+                }
+            }
+            // Update session counters (does NOT fire a second event)
+            await this.autoEventsManager.recordScreenView(screenName);
         }
+        await this.track('pageview', screenData);
     }
     /**
      * Identify a user
@@ -898,7 +908,7 @@ export class DatalyrSDK {
                 carrier: deviceInfo.carrier,
                 network_type: getNetworkType(),
                 timestamp: Date.now(),
-                sdk_version: '1.6.1',
+                sdk_version: '1.7.0',
                 // Advertiser data (IDFA/GAID, ATT status) for server-side postback
                 ...(advertiserInfo ? {
                     idfa: advertiserInfo.idfa,

package/lib/index.d.ts

@@ -10,6 +10,8 @@ export * from './utils';
 export * from './http-client';
 export * from './event-queue';
 export { DatalyrSDK };
+export { datalyrScreenTracking, createScreenTrackingListeners, } from './screen-tracking';
+export type { ScreenTrackingConfig, NavigationContainerRef } from './screen-tracking';
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
 export { appleSearchAdsIntegration, playInstallReferrerIntegration } from './integrations';

package/lib/index.js

@@ -16,6 +16,8 @@ export * from './http-client';
 export * from './event-queue';
 // Also export the SDK class for advanced usage
 export { DatalyrSDK };
+// Export automatic screen tracking for React Navigation
+export { datalyrScreenTracking, createScreenTrackingListeners, } from './screen-tracking';
 // Export SKAdNetwork components
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';

package/lib/screen-tracking.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Automatic screen tracking for React Navigation (v5+ / v6+).
+ *
+ * The simplest integration — just spread onto your NavigationContainer:
+ *
+ * ```tsx
+ * import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+ * import { datalyrScreenTracking } from '@datalyr/react-native';
+ *
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ *
+ * Note: If you enable automatic screen tracking, avoid also calling
+ * `Datalyr.screen()` / `datalyr.screen()` manually for the same screens,
+ * as this will produce duplicate events.
+ *
+ * For Expo Router (file-based routing), automatic tracking is not needed.
+ * Use the `datalyr.screen()` method in your layout files instead.
+ */
+/** Minimal subset of React Navigation's NavigationContainerRef that we need. */
+export interface NavigationContainerRef {
+    getCurrentRoute(): {
+        name: string;
+        params?: Record<string, any>;
+    } | undefined;
+}
+export interface ScreenTrackingConfig {
+    /**
+     * Transform the route name before tracking.
+     * Useful for cleaning up or grouping screen names.
+     * @example (name) => name.replace('Screen', '')
+     */
+    transformScreenName?: (routeName: string) => string;
+    /**
+     * Filter which screens should be tracked.
+     * Return false to skip tracking for a given screen.
+     * @example (name) => !['Loading', 'Splash'].includes(name)
+     */
+    shouldTrackScreen?: (routeName: string) => boolean;
+    /**
+     * Extract additional properties from the route to include in the screen event.
+     * @example (name, params) => ({ product_id: params?.productId })
+     */
+    extractProperties?: (routeName: string, params?: Record<string, any>) => Record<string, any>;
+}
+/**
+ * Create `onReady` and `onStateChange` callbacks that automatically
+ * fire screen events through the Datalyr SDK whenever the active
+ * React Navigation route changes.
+ *
+ * @param navigationRef  A React Navigation `NavigationContainerRef`
+ *                       (from `useNavigationContainerRef()` or
+ *                       `createNavigationContainerRef()`).
+ * @param trackScreen    The function that records a screen event.
+ *                       Pass `datalyr.screen.bind(datalyr)` or the
+ *                       Datalyr static class's `Datalyr.screen`.
+ *                       If omitted, the default singleton is used.
+ * @param config         Optional filtering / transform config.
+ */
+export declare function createScreenTrackingListeners(navigationRef: NavigationContainerRef, trackScreen: (screenName: string, properties?: Record<string, any>) => Promise<void>, config?: ScreenTrackingConfig): {
+    onReady: () => void;
+    onStateChange: () => void;
+};
+/**
+ * Auto-wire screen tracking to the default Datalyr singleton.
+ * This is the recommended API for most users.
+ *
+ * ```tsx
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ *
+ * @param navigationRef  React Navigation container ref
+ * @param config         Optional screen name transforms and filters
+ */
+export declare function datalyrScreenTracking(navigationRef: NavigationContainerRef, config?: ScreenTrackingConfig): {
+    onReady: () => void;
+    onStateChange: () => void;
+};

package/lib/screen-tracking.js

@@ -0,0 +1,130 @@
+/**
+ * Automatic screen tracking for React Navigation (v5+ / v6+).
+ *
+ * The simplest integration — just spread onto your NavigationContainer:
+ *
+ * ```tsx
+ * import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+ * import { datalyrScreenTracking } from '@datalyr/react-native';
+ *
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ *
+ * Note: If you enable automatic screen tracking, avoid also calling
+ * `Datalyr.screen()` / `datalyr.screen()` manually for the same screens,
+ * as this will produce duplicate events.
+ *
+ * For Expo Router (file-based routing), automatic tracking is not needed.
+ * Use the `datalyr.screen()` method in your layout files instead.
+ */
+import { debugLog, errorLog } from './utils';
+// ---------------------------------------------------------------------------
+// Core implementation
+// ---------------------------------------------------------------------------
+/**
+ * Create `onReady` and `onStateChange` callbacks that automatically
+ * fire screen events through the Datalyr SDK whenever the active
+ * React Navigation route changes.
+ *
+ * @param navigationRef  A React Navigation `NavigationContainerRef`
+ *                       (from `useNavigationContainerRef()` or
+ *                       `createNavigationContainerRef()`).
+ * @param trackScreen    The function that records a screen event.
+ *                       Pass `datalyr.screen.bind(datalyr)` or the
+ *                       Datalyr static class's `Datalyr.screen`.
+ *                       If omitted, the default singleton is used.
+ * @param config         Optional filtering / transform config.
+ */
+export function createScreenTrackingListeners(navigationRef, trackScreen, config) {
+    let currentRouteName;
+    const resolveScreenName = (routeName) => (config === null || config === void 0 ? void 0 : config.transformScreenName) ? config.transformScreenName(routeName) : routeName;
+    const buildProperties = (routeName, params, previousRouteName) => {
+        const props = { source: 'auto_navigation' };
+        if (previousRouteName) {
+            props.previous_screen = resolveScreenName(previousRouteName);
+        }
+        if (config === null || config === void 0 ? void 0 : config.extractProperties) {
+            Object.assign(props, config.extractProperties(routeName, params));
+        }
+        return props;
+    };
+    const shouldTrack = (routeName) => !(config === null || config === void 0 ? void 0 : config.shouldTrackScreen) || config.shouldTrackScreen(routeName);
+    const safeTrack = (screenName, properties) => {
+        try {
+            trackScreen(screenName, properties).catch((err) => {
+                errorLog('Auto screen tracking failed:', err);
+            });
+        }
+        catch (err) {
+            errorLog('Auto screen tracking failed:', err);
+        }
+    };
+    const onReady = () => {
+        const route = navigationRef.getCurrentRoute();
+        if (!route)
+            return;
+        currentRouteName = route.name;
+        if (shouldTrack(route.name)) {
+            const screenName = resolveScreenName(route.name);
+            safeTrack(screenName, buildProperties(route.name, route.params));
+            debugLog('Auto screen tracking: initial screen', screenName);
+        }
+    };
+    const onStateChange = () => {
+        const route = navigationRef.getCurrentRoute();
+        if (!route)
+            return;
+        const previousRouteName = currentRouteName;
+        currentRouteName = route.name;
+        // Don't fire for same-screen param changes
+        if (previousRouteName === currentRouteName)
+            return;
+        if (!shouldTrack(route.name))
+            return;
+        const screenName = resolveScreenName(route.name);
+        safeTrack(screenName, buildProperties(route.name, route.params, previousRouteName));
+        debugLog('Auto screen tracking: navigated to', screenName);
+    };
+    return { onReady, onStateChange };
+}
+// ---------------------------------------------------------------------------
+// Convenience wrapper — wires to the default Datalyr singleton
+// ---------------------------------------------------------------------------
+/**
+ * Auto-wire screen tracking to the default Datalyr singleton.
+ * This is the recommended API for most users.
+ *
+ * ```tsx
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ *
+ * @param navigationRef  React Navigation container ref
+ * @param config         Optional screen name transforms and filters
+ */
+export function datalyrScreenTracking(navigationRef, config) {
+    // Lazily resolved reference to the SDK singleton.
+    // We avoid a top-level import to prevent circular deps (index.ts re-exports this file).
+    let sdk = null;
+    const getSdk = () => {
+        if (!sdk) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            sdk = require('./datalyr-sdk').default;
+        }
+        return sdk;
+    };
+    return createScreenTrackingListeners(navigationRef, (screenName, properties) => getSdk().screen(screenName, properties), config);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/react-native",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "Datalyr SDK for React Native & Expo - Server-side attribution tracking for iOS and Android",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/auto-events.ts

@@ -195,39 +195,44 @@ export class AutoEventsManager {
   }
 
   /**
-   * Track automatic pageview
+   * Update session counters for a screen view.
+   * The actual pageview event is fired by the SDK's screen() method —
+   * this only updates internal session state to avoid double-firing.
    */
-  async trackScreenView(screenName: string, properties?: Record<string, any>): Promise<void> {
+  async recordScreenView(screenName: string): Promise<void> {
     try {
       if (!this.config.trackScreenViews) return;
-      
-      // Don't track the same screen twice in a row
+
+      // Don't count the same screen twice in a row
       if (this.lastScreenName === screenName) return;
-      
-      const screenProperties: Record<string, any> = {
-        screen_name: screenName,
-        previous_screen: this.lastScreenName,
-        timestamp: Date.now(),
-        ...properties,
-      };
 
-      // Add session data if available
+      // Update session counters (no event fired here)
       if (this.currentSession) {
         this.currentSession.screenViews++;
-        screenProperties.session_id = this.currentSession.sessionId;
-        screenProperties.pageviews_in_session = this.currentSession.screenViews;
+        this.currentSession.lastActivity = Date.now();
       }
 
-      await this.trackEvent('pageview', screenProperties);
-      
       this.lastScreenName = screenName;
-      debugLog('Pageview tracked:', screenName);
+      debugLog('Screen view counted:', screenName);
 
     } catch (error) {
-      errorLog('Error tracking screen view:', error as Error);
+      errorLog('Error updating screen view:', error as Error);
     }
   }
 
+  /**
+   * Get session data to enrich a pageview event.
+   * Called by the SDK's screen() method to attach session info.
+   */
+  getScreenViewEnrichment(): Record<string, any> | null {
+    if (!this.currentSession) return null;
+    return {
+      session_id: this.currentSession.sessionId,
+      pageviews_in_session: this.currentSession.screenViews,
+      previous_screen: this.lastScreenName,
+    };
+  }
+
   /**
    * Track app launch performance
    */

package/src/datalyr-sdk-expo.ts

@@ -196,7 +196,7 @@ export class DatalyrSDKExpo {
         const installData = await attributionManager.trackInstall();
         await this.track('app_install', {
           platform: Platform.OS,
-          sdk_version: '1.6.1',
+          sdk_version: '1.7.0',
           sdk_variant: 'expo',
           ...installData,
         });
@@ -248,11 +248,22 @@ export class DatalyrSDKExpo {
       ...properties,
     };
 
-    await this.track('pageview', screenData);
-
+    // Enrich with session data (pageview count, previous screen) if available.
+    // User-provided properties take precedence over enrichment.
     if (this.autoEventsManager) {
-      await this.autoEventsManager.trackScreenView(screenName, properties);
+      const enrichment = this.autoEventsManager.getScreenViewEnrichment();
+      if (enrichment) {
+        for (const [key, value] of Object.entries(enrichment)) {
+          if (!(key in screenData)) {
+            screenData[key] = value;
+          }
+        }
+      }
+      // Update session counters (does NOT fire a second event)
+      await this.autoEventsManager.recordScreenView(screenName);
     }
+
+    await this.track('pageview', screenData);
   }
 
   async identify(userId: string, properties?: UserProperties): Promise<void> {
@@ -781,7 +792,7 @@ export class DatalyrSDKExpo {
         carrier: deviceInfo.carrier,
         network_type: networkType,
         timestamp: Date.now(),
-        sdk_version: '1.6.1',
+        sdk_version: '1.7.0',
         sdk_variant: 'expo',
         // Advertiser data (IDFA/GAID, ATT status) for server-side postback
         ...(advertiserInfo ? {

package/src/datalyr-sdk.ts

@@ -228,7 +228,7 @@ export class DatalyrSDK {
         const installData = await attributionManager.trackInstall();
         await this.track('app_install', {
           platform: Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : 'android',
-          sdk_version: '1.6.1',
+          sdk_version: '1.7.0',
           ...installData,
         });
       }
@@ -285,12 +285,22 @@ export class DatalyrSDK {
       ...properties,
     };
 
-    await this.track('pageview', screenData);
-
-    // Also notify auto-events manager for automatic screen tracking
+    // Enrich with session data (pageview count, previous screen) if available.
+    // User-provided properties take precedence over enrichment.
     if (this.autoEventsManager) {
-      await this.autoEventsManager.trackScreenView(screenName, properties);
+      const enrichment = this.autoEventsManager.getScreenViewEnrichment();
+      if (enrichment) {
+        for (const [key, value] of Object.entries(enrichment)) {
+          if (!(key in screenData)) {
+            screenData[key] = value;
+          }
+        }
+      }
+      // Update session counters (does NOT fire a second event)
+      await this.autoEventsManager.recordScreenView(screenName);
     }
+
+    await this.track('pageview', screenData);
   }
 
   /**
@@ -1076,7 +1086,7 @@ export class DatalyrSDK {
         carrier: deviceInfo.carrier,
         network_type: getNetworkType(),
         timestamp: Date.now(),
-        sdk_version: '1.6.1',
+        sdk_version: '1.7.0',
         // Advertiser data (IDFA/GAID, ATT status) for server-side postback
         ...(advertiserInfo ? {
           idfa: advertiserInfo.idfa,

package/src/expo.ts

@@ -56,6 +56,39 @@ export * from './event-queue';
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
 
+// Export automatic screen tracking for React Navigation
+export { createScreenTrackingListeners } from './screen-tracking';
+export type { ScreenTrackingConfig, NavigationContainerRef } from './screen-tracking';
+
+// Expo-specific convenience: auto-wires to the Expo singleton
+import { createScreenTrackingListeners as _createListeners } from './screen-tracking';
+import type { NavigationContainerRef as _NavRef, ScreenTrackingConfig as _Config } from './screen-tracking';
+
+/**
+ * Auto-wire screen tracking to the Expo Datalyr singleton.
+ *
+ * ```tsx
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ */
+export function datalyrScreenTracking(
+  navigationRef: _NavRef,
+  config?: _Config,
+): { onReady: () => void; onStateChange: () => void } {
+  return _createListeners(
+    navigationRef,
+    (screenName, properties) => datalyrExpo.screen(screenName, properties),
+    config,
+  );
+}
+
 // Export platform integrations
 export { appleSearchAdsIntegration } from './integrations';
 export type { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';

package/src/index.ts

@@ -24,6 +24,13 @@ export * from './event-queue';
 // Also export the SDK class for advanced usage
 export { DatalyrSDK };
 
+// Export automatic screen tracking for React Navigation
+export {
+  datalyrScreenTracking,
+  createScreenTrackingListeners,
+} from './screen-tracking';
+export type { ScreenTrackingConfig, NavigationContainerRef } from './screen-tracking';
+
 // Export SKAdNetwork components
 export { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 export { SKAdNetworkBridge } from './native/SKAdNetworkBridge';

package/src/screen-tracking.ts

@@ -0,0 +1,201 @@
+/**
+ * Automatic screen tracking for React Navigation (v5+ / v6+).
+ *
+ * The simplest integration — just spread onto your NavigationContainer:
+ *
+ * ```tsx
+ * import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+ * import { datalyrScreenTracking } from '@datalyr/react-native';
+ *
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ *
+ * Note: If you enable automatic screen tracking, avoid also calling
+ * `Datalyr.screen()` / `datalyr.screen()` manually for the same screens,
+ * as this will produce duplicate events.
+ *
+ * For Expo Router (file-based routing), automatic tracking is not needed.
+ * Use the `datalyr.screen()` method in your layout files instead.
+ */
+
+import { debugLog, errorLog } from './utils';
+
+// ---------------------------------------------------------------------------
+// Minimal React Navigation types — avoids adding @react-navigation as a
+// peer dependency. Only the methods we actually call are listed here.
+// ---------------------------------------------------------------------------
+
+/** Minimal subset of React Navigation's NavigationContainerRef that we need. */
+export interface NavigationContainerRef {
+  getCurrentRoute(): { name: string; params?: Record<string, any> } | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface ScreenTrackingConfig {
+  /**
+   * Transform the route name before tracking.
+   * Useful for cleaning up or grouping screen names.
+   * @example (name) => name.replace('Screen', '')
+   */
+  transformScreenName?: (routeName: string) => string;
+
+  /**
+   * Filter which screens should be tracked.
+   * Return false to skip tracking for a given screen.
+   * @example (name) => !['Loading', 'Splash'].includes(name)
+   */
+  shouldTrackScreen?: (routeName: string) => boolean;
+
+  /**
+   * Extract additional properties from the route to include in the screen event.
+   * @example (name, params) => ({ product_id: params?.productId })
+   */
+  extractProperties?: (routeName: string, params?: Record<string, any>) => Record<string, any>;
+}
+
+// ---------------------------------------------------------------------------
+// Core implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create `onReady` and `onStateChange` callbacks that automatically
+ * fire screen events through the Datalyr SDK whenever the active
+ * React Navigation route changes.
+ *
+ * @param navigationRef  A React Navigation `NavigationContainerRef`
+ *                       (from `useNavigationContainerRef()` or
+ *                       `createNavigationContainerRef()`).
+ * @param trackScreen    The function that records a screen event.
+ *                       Pass `datalyr.screen.bind(datalyr)` or the
+ *                       Datalyr static class's `Datalyr.screen`.
+ *                       If omitted, the default singleton is used.
+ * @param config         Optional filtering / transform config.
+ */
+export function createScreenTrackingListeners(
+  navigationRef: NavigationContainerRef,
+  trackScreen: (screenName: string, properties?: Record<string, any>) => Promise<void>,
+  config?: ScreenTrackingConfig,
+): { onReady: () => void; onStateChange: () => void } {
+  let currentRouteName: string | undefined;
+
+  const resolveScreenName = (routeName: string): string =>
+    config?.transformScreenName ? config.transformScreenName(routeName) : routeName;
+
+  const buildProperties = (
+    routeName: string,
+    params?: Record<string, any>,
+    previousRouteName?: string,
+  ): Record<string, any> => {
+    const props: Record<string, any> = { source: 'auto_navigation' };
+
+    if (previousRouteName) {
+      props.previous_screen = resolveScreenName(previousRouteName);
+    }
+
+    if (config?.extractProperties) {
+      Object.assign(props, config.extractProperties(routeName, params));
+    }
+
+    return props;
+  };
+
+  const shouldTrack = (routeName: string): boolean =>
+    !config?.shouldTrackScreen || config.shouldTrackScreen(routeName);
+
+  const safeTrack = (screenName: string, properties: Record<string, any>) => {
+    try {
+      trackScreen(screenName, properties).catch((err) => {
+        errorLog('Auto screen tracking failed:', err as Error);
+      });
+    } catch (err) {
+      errorLog('Auto screen tracking failed:', err as Error);
+    }
+  };
+
+  const onReady = () => {
+    const route = navigationRef.getCurrentRoute();
+    if (!route) return;
+
+    currentRouteName = route.name;
+
+    if (shouldTrack(route.name)) {
+      const screenName = resolveScreenName(route.name);
+      safeTrack(screenName, buildProperties(route.name, route.params));
+      debugLog('Auto screen tracking: initial screen', screenName);
+    }
+  };
+
+  const onStateChange = () => {
+    const route = navigationRef.getCurrentRoute();
+    if (!route) return;
+
+    const previousRouteName = currentRouteName;
+    currentRouteName = route.name;
+
+    // Don't fire for same-screen param changes
+    if (previousRouteName === currentRouteName) return;
+
+    if (!shouldTrack(route.name)) return;
+
+    const screenName = resolveScreenName(route.name);
+    safeTrack(screenName, buildProperties(route.name, route.params, previousRouteName));
+    debugLog('Auto screen tracking: navigated to', screenName);
+  };
+
+  return { onReady, onStateChange };
+}
+
+// ---------------------------------------------------------------------------
+// Convenience wrapper — wires to the default Datalyr singleton
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-wire screen tracking to the default Datalyr singleton.
+ * This is the recommended API for most users.
+ *
+ * ```tsx
+ * const navigationRef = useNavigationContainerRef();
+ * const screenTracking = datalyrScreenTracking(navigationRef);
+ *
+ * <NavigationContainer
+ *   ref={navigationRef}
+ *   onReady={screenTracking.onReady}
+ *   onStateChange={screenTracking.onStateChange}
+ * />
+ * ```
+ *
+ * @param navigationRef  React Navigation container ref
+ * @param config         Optional screen name transforms and filters
+ */
+export function datalyrScreenTracking(
+  navigationRef: NavigationContainerRef,
+  config?: ScreenTrackingConfig,
+): { onReady: () => void; onStateChange: () => void } {
+  // Lazily resolved reference to the SDK singleton.
+  // We avoid a top-level import to prevent circular deps (index.ts re-exports this file).
+  let sdk: { screen: (name: string, props?: Record<string, any>) => Promise<void> } | null = null;
+
+  const getSdk = () => {
+    if (!sdk) {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      sdk = (require('./datalyr-sdk') as { default: typeof sdk }).default;
+    }
+    return sdk!;
+  };
+
+  return createScreenTrackingListeners(
+    navigationRef,
+    (screenName, properties) => getSdk().screen(screenName, properties),
+    config,
+  );
+}