@datalyr/react-native 1.7.0 → 1.7.2

package/README.md

@@ -545,22 +545,43 @@ 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:
+For Expo Router apps, use the `useDatalyrScreenTracking` hook in your root layout. It automatically tracks every route change as a `pageview` event:
 
 ```tsx
-import { datalyr } from '@datalyr/react-native/expo';
-import { usePathname } from 'expo-router';
-import { useEffect } from 'react';
+// app/_layout.tsx
+import { useDatalyrScreenTracking } from '@datalyr/react-native/expo';
+import { Stack } from 'expo-router';
 
 export default function RootLayout() {
-  const pathname = usePathname();
+  useDatalyrScreenTracking();
+  return <Stack />;
+}
+```
 
-  useEffect(() => {
-    datalyr.screen(pathname);
-  }, [pathname]);
+Screen names are raw pathnames (e.g. `/onboarding/paywall`, `/(app)/chat`). You can map specific paths to friendly names:
 
-  return <Slot />;
-}
+```tsx
+useDatalyrScreenTracking({
+  screenNames: {
+    '/onboarding/paywall': 'Paywall',
+    '/(app)/chat': 'Chat',
+  },
+});
+```
+
+Additional options:
+
+```tsx
+useDatalyrScreenTracking({
+  // Map specific paths to friendly names (checked first)
+  screenNames: { '/': 'Home' },
+
+  // Transform all other pathnames (e.g. strip route groups)
+  transformPathname: (path) => path.replace(/\(.*?\)\//g, ''),
+
+  // Skip tracking for certain paths
+  shouldTrackPath: (path) => !path.startsWith('/modal'),
+});
 ```
 
 ### Configuration

package/lib/auto-events.d.ts

@@ -52,7 +52,8 @@ export declare class AutoEventsManager {
     recordScreenView(screenName: string): Promise<void>;
     /**
      * Get session data to enrich a pageview event.
-     * Called by the SDK's screen() method to attach session info.
+     * Called by the SDK's screen() method *before* recordScreenView(),
+     * so we add 1 to account for the current view being tracked.
      */
     getScreenViewEnrichment(): Record<string, any> | null;
     /**

package/lib/auto-events.js

@@ -180,14 +180,15 @@ export class AutoEventsManager {
     }
     /**
      * Get session data to enrich a pageview event.
-     * Called by the SDK's screen() method to attach session info.
+     * Called by the SDK's screen() method *before* recordScreenView(),
+     * so we add 1 to account for the current view being tracked.
      */
     getScreenViewEnrichment() {
         if (!this.currentSession)
             return null;
         return {
             session_id: this.currentSession.sessionId,
-            pageviews_in_session: this.currentSession.screenViews,
+            pageviews_in_session: this.currentSession.screenViews + 1,
             previous_screen: this.lastScreenName,
         };
     }

package/lib/datalyr-sdk.d.ts

@@ -12,6 +12,9 @@ export declare class DatalyrSDK {
     private cachedAdvertiserInfo;
     private static conversionEncoder?;
     private static debugEnabled;
+    /** Events that arrived before initialize() completed. Flushed once init finishes. */
+    private preInitQueue;
+    private static readonly PRE_INIT_QUEUE_MAX;
     constructor();
     /**
      * Initialize the SDK with configuration

package/lib/datalyr-sdk.js

@@ -16,6 +16,8 @@ export class DatalyrSDK {
         this.appStateSubscription = null;
         this.networkStatusUnsubscribe = null;
         this.cachedAdvertiserInfo = null;
+        /** Events that arrived before initialize() completed. Flushed once init finishes. */
+        this.preInitQueue = [];
         // Initialize state with defaults
         this.state = {
             initialized: false,
@@ -167,6 +169,15 @@ export class DatalyrSDK {
             });
             // SDK initialized successfully - set state before tracking install event
             this.state.initialized = true;
+            // Flush any events that were queued before init completed (e.g. screen tracking)
+            if (this.preInitQueue.length > 0) {
+                debugLog(`Flushing ${this.preInitQueue.length} pre-init event(s)`);
+                const queued = [...this.preInitQueue];
+                this.preInitQueue = [];
+                for (const { eventName, eventData } of queued) {
+                    await this.track(eventName, eventData);
+                }
+            }
             // Check for app install (after SDK is marked as initialized)
             if (attributionManager.isInstall()) {
                 // iOS: Attempt deferred web-to-app attribution via IP matching before tracking install
@@ -177,7 +188,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.7.0',
+                    sdk_version: '1.7.2',
                     ...installData,
                 });
             }
@@ -199,7 +210,14 @@ export class DatalyrSDK {
     async track(eventName, eventData) {
         try {
             if (!this.state.initialized) {
-                errorLog('SDK not initialized. Call initialize() first.');
+                // Queue events that arrive before init completes instead of dropping them
+                if (this.preInitQueue.length < DatalyrSDK.PRE_INIT_QUEUE_MAX) {
+                    debugLog(`Queuing pre-init event: ${eventName}`);
+                    this.preInitQueue.push({ eventName, eventData });
+                }
+                else {
+                    errorLog('Pre-init event queue full, dropping event:', eventName);
+                }
                 return;
             }
             if (!validateEventName(eventName)) {
@@ -908,7 +926,7 @@ export class DatalyrSDK {
                 carrier: deviceInfo.carrier,
                 network_type: getNetworkType(),
                 timestamp: Date.now(),
-                sdk_version: '1.7.0',
+                sdk_version: '1.7.2',
                 // Advertiser data (IDFA/GAID, ATT status) for server-side postback
                 ...(advertiserInfo ? {
                     idfa: advertiserInfo.idfa,
@@ -1089,6 +1107,7 @@ export class DatalyrSDK {
     }
 }
 DatalyrSDK.debugEnabled = false;
+DatalyrSDK.PRE_INIT_QUEUE_MAX = 50;
 // Create singleton instance
 const datalyr = new DatalyrSDK();
 // Export enhanced Datalyr class with static methods

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/react-native",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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

@@ -222,13 +222,14 @@ export class AutoEventsManager {
 
   /**
    * Get session data to enrich a pageview event.
-   * Called by the SDK's screen() method to attach session info.
+   * Called by the SDK's screen() method *before* recordScreenView(),
+   * so we add 1 to account for the current view being tracked.
    */
   getScreenViewEnrichment(): Record<string, any> | null {
     if (!this.currentSession) return null;
     return {
       session_id: this.currentSession.sessionId,
-      pageviews_in_session: this.currentSession.screenViews,
+      pageviews_in_session: this.currentSession.screenViews + 1,
       previous_screen: this.lastScreenName,
     };
   }

package/src/datalyr-sdk-expo.ts

@@ -47,6 +47,9 @@ export class DatalyrSDKExpo {
   private cachedAdvertiserInfo: any = null;
   private static conversionEncoder?: ConversionValueEncoder;
   private static debugEnabled = false;
+  /** Events that arrived before initialize() completed. Flushed once init finishes. */
+  private preInitQueue: Array<{ eventName: string; eventData?: EventData }> = [];
+  private static readonly PRE_INIT_QUEUE_MAX = 50;
 
   constructor() {
     this.state = {
@@ -192,11 +195,21 @@ export class DatalyrSDKExpo {
 
       this.state.initialized = true;
 
+      // Flush any events that were queued before init completed (e.g. screen tracking)
+      if (this.preInitQueue.length > 0) {
+        debugLog(`Flushing ${this.preInitQueue.length} pre-init event(s)`);
+        const queued = [...this.preInitQueue];
+        this.preInitQueue = [];
+        for (const { eventName, eventData } of queued) {
+          await this.track(eventName, eventData);
+        }
+      }
+
       if (attributionManager.isInstall()) {
         const installData = await attributionManager.trackInstall();
         await this.track('app_install', {
           platform: Platform.OS,
-          sdk_version: '1.7.0',
+          sdk_version: '1.7.2',
           sdk_variant: 'expo',
           ...installData,
         });
@@ -218,7 +231,12 @@ export class DatalyrSDKExpo {
   async track(eventName: string, eventData?: EventData): Promise<void> {
     try {
       if (!this.state.initialized) {
-        errorLog('SDK not initialized. Call initialize() first.');
+        if (this.preInitQueue.length < DatalyrSDKExpo.PRE_INIT_QUEUE_MAX) {
+          debugLog(`Queuing pre-init event: ${eventName}`);
+          this.preInitQueue.push({ eventName, eventData });
+        } else {
+          errorLog('Pre-init event queue full, dropping event:', eventName as unknown as Error);
+        }
         return;
       }
 
@@ -792,7 +810,7 @@ export class DatalyrSDKExpo {
         carrier: deviceInfo.carrier,
         network_type: networkType,
         timestamp: Date.now(),
-        sdk_version: '1.7.0',
+        sdk_version: '1.7.2',
         sdk_variant: 'expo',
         // Advertiser data (IDFA/GAID, ATT status) for server-side postback
         ...(advertiserInfo ? {

package/src/datalyr-sdk.ts

@@ -45,6 +45,9 @@ export class DatalyrSDK {
   private cachedAdvertiserInfo: any = null;
   private static conversionEncoder?: ConversionValueEncoder;
   private static debugEnabled = false;
+  /** Events that arrived before initialize() completed. Flushed once init finishes. */
+  private preInitQueue: Array<{ eventName: string; eventData?: EventData }> = [];
+  private static readonly PRE_INIT_QUEUE_MAX = 50;
 
   constructor() {
     // Initialize state with defaults
@@ -217,6 +220,16 @@ export class DatalyrSDK {
       // SDK initialized successfully - set state before tracking install event
       this.state.initialized = true;
 
+      // Flush any events that were queued before init completed (e.g. screen tracking)
+      if (this.preInitQueue.length > 0) {
+        debugLog(`Flushing ${this.preInitQueue.length} pre-init event(s)`);
+        const queued = [...this.preInitQueue];
+        this.preInitQueue = [];
+        for (const { eventName, eventData } of queued) {
+          await this.track(eventName, eventData);
+        }
+      }
+
       // Check for app install (after SDK is marked as initialized)
       if (attributionManager.isInstall()) {
         // iOS: Attempt deferred web-to-app attribution via IP matching before tracking install
@@ -228,7 +241,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.7.0',
+          sdk_version: '1.7.2',
           ...installData,
         });
       }
@@ -252,7 +265,13 @@ export class DatalyrSDK {
   async track(eventName: string, eventData?: EventData): Promise<void> {
     try {
       if (!this.state.initialized) {
-        errorLog('SDK not initialized. Call initialize() first.');
+        // Queue events that arrive before init completes instead of dropping them
+        if (this.preInitQueue.length < DatalyrSDK.PRE_INIT_QUEUE_MAX) {
+          debugLog(`Queuing pre-init event: ${eventName}`);
+          this.preInitQueue.push({ eventName, eventData });
+        } else {
+          errorLog('Pre-init event queue full, dropping event:', eventName as unknown as Error);
+        }
         return;
       }
 
@@ -1086,7 +1105,7 @@ export class DatalyrSDK {
         carrier: deviceInfo.carrier,
         network_type: getNetworkType(),
         timestamp: Date.now(),
-        sdk_version: '1.7.0',
+        sdk_version: '1.7.2',
         // Advertiser data (IDFA/GAID, ATT status) for server-side postback
         ...(advertiserInfo ? {
           idfa: advertiserInfo.idfa,

package/src/expo-router-tracking.ts

@@ -0,0 +1,108 @@
+/**
+ * Automatic screen tracking for Expo Router.
+ *
+ * Expo Router uses file-based routing and does not expose a
+ * NavigationContainerRef, so we use the `usePathname()` hook to
+ * detect route changes and fire pageview events automatically.
+ *
+ * ```tsx
+ * // app/_layout.tsx
+ * import { useDatalyrScreenTracking } from '@datalyr/react-native/expo';
+ *
+ * export default function RootLayout() {
+ *   useDatalyrScreenTracking();
+ *   return <Stack />;
+ * }
+ * ```
+ *
+ * Screen names are the raw pathname (e.g. "/onboarding/paywall", "/(app)/chat").
+ * These are consistent and easy to filter in the Datalyr dashboard.
+ */
+
+import { useEffect, useRef } from 'react';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+export interface ExpoRouterTrackingConfig {
+  /**
+   * Map specific pathnames to friendly screen names.
+   * Paths not in this map use the raw pathname (or `transformPathname` if set).
+   * @example { '/onboarding/paywall': 'Paywall', '/(app)/chat': 'Chat' }
+   */
+  screenNames?: Record<string, string>;
+
+  /**
+   * Transform the pathname before tracking.
+   * Applied only when the path is NOT in `screenNames`.
+   * @example (path) => path.replace(/\(.*?\)\//g, '')  // strip route groups
+   */
+  transformPathname?: (pathname: string) => string;
+
+  /**
+   * Filter which paths should be tracked.
+   * Return false to skip tracking for a given path.
+   * @example (path) => !path.startsWith('/modal')
+   */
+  shouldTrackPath?: (pathname: string) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Core hook
+// ---------------------------------------------------------------------------
+
+/**
+ * React hook that automatically tracks screen views when the Expo Router
+ * pathname changes. Drop this into your root `_layout.tsx`.
+ *
+ * @param trackScreen  The function that records a screen event.
+ *                     Receives `(pathname, properties)`.
+ * @param usePathname  The `usePathname` hook from `expo-router`.
+ *                     Passed in to avoid a hard dependency on expo-router.
+ * @param config       Optional filtering / transform config.
+ */
+export function useExpoRouterTracking(
+  trackScreen: (screenName: string, properties?: Record<string, any>) => Promise<void>,
+  usePathname: () => string,
+  config?: ExpoRouterTrackingConfig,
+): void {
+  const pathname = usePathname();
+  const previousPathname = useRef<string | undefined>(undefined);
+
+  // Keep mutable refs so the effect always sees the latest values
+  // without needing them in the dependency array (which would re-fire on every render).
+  const trackScreenRef = useRef(trackScreen);
+  trackScreenRef.current = trackScreen;
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  useEffect(() => {
+    if (!pathname) return;
+    if (previousPathname.current === pathname) return;
+
+    const prevPath = previousPathname.current;
+    previousPathname.current = pathname;
+
+    const cfg = configRef.current;
+
+    // Apply filter
+    if (cfg?.shouldTrackPath && !cfg.shouldTrackPath(pathname)) return;
+
+    // Resolve screen name: screenNames map → transformPathname → raw pathname
+    const resolve = (path: string): string =>
+      cfg?.screenNames?.[path]
+        ?? (cfg?.transformPathname ? cfg.transformPathname(path) : path);
+
+    const screenName = resolve(pathname);
+
+    const properties: Record<string, any> = { source: 'auto_expo_router' };
+    if (prevPath) {
+      properties.previous_screen = resolve(prevPath);
+    }
+
+    trackScreenRef.current(screenName, properties).catch(() => {
+      // Silently ignore — SDK logs internally
+    });
+  }, [pathname]);
+}

package/src/expo.ts

@@ -89,6 +89,49 @@ export function datalyrScreenTracking(
   );
 }
 
+// Export automatic screen tracking for Expo Router
+export { useExpoRouterTracking } from './expo-router-tracking';
+export type { ExpoRouterTrackingConfig } from './expo-router-tracking';
+
+import { useExpoRouterTracking as _useExpoRouterTracking } from './expo-router-tracking';
+import type { ExpoRouterTrackingConfig as _ExpoRouterConfig } from './expo-router-tracking';
+
+// Lazy-resolved expo-router hook. Resolved once at first call, not inside the
+// hook body, so that hook call count stays stable across renders.
+let _usePathname: (() => string) | null = null;
+function getUsePathname(): () => string {
+  if (!_usePathname) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    _usePathname = (require('expo-router') as { usePathname: () => string }).usePathname;
+  }
+  return _usePathname;
+}
+
+/**
+ * Drop-in screen tracking for Expo Router — wires to the Expo Datalyr singleton.
+ *
+ * ```tsx
+ * // app/_layout.tsx
+ * import { useDatalyrScreenTracking } from '@datalyr/react-native/expo';
+ *
+ * export default function RootLayout() {
+ *   useDatalyrScreenTracking();
+ *   return <Stack />;
+ * }
+ * ```
+ *
+ * Screen names are raw pathnames (e.g. "/onboarding/paywall").
+ *
+ * @param config  Optional path transforms and filters.
+ */
+export function useDatalyrScreenTracking(config?: _ExpoRouterConfig): void {
+  _useExpoRouterTracking(
+    (screenName, properties) => datalyrExpo.screen(screenName, properties),
+    getUsePathname(),
+    config,
+  );
+}
+
 // Export platform integrations
 export { appleSearchAdsIntegration } from './integrations';
 export type { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';