@grafana/faro-react-native 1.0.0-alpha.1 → 1.0.0

package/src/instrumentations/errors/index.ts

@@ -60,10 +60,9 @@ interface ErrorFingerprint {
  *
  * @example
  * ```tsx
- * import { initializeFaro } from '@grafana/faro-react-native';
- * import { ErrorsInstrumentation } from '@grafana/faro-react-native';
+ * import { ErrorsInstrumentation, initializeFaro } from '@grafana/faro-react-native';
  *
- * initializeFaro({
+ * await initializeFaro({
  *   // ...config
  *   instrumentations: [
  *     new ErrorsInstrumentation({
@@ -95,8 +94,6 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
   }
 
   initialize(): void {
-    this.logInfo('Initializing errors instrumentation');
-
     // Capture unhandled JavaScript errors
     this.setupGlobalErrorHandler();
 
@@ -113,13 +110,11 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
       try {
         // Check if error should be ignored
         if (this.shouldIgnoreError(error)) {
-          this.logDebug('Ignoring error based on ignoreErrors patterns', { message: error.message });
           return;
         }
 
         // Check for duplicate errors
         if (this.options.enableDeduplication && this.isDuplicateError(error)) {
-          this.logDebug('Ignoring duplicate error', { message: error.message });
           return;
         }
 
@@ -144,9 +139,8 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
         if (this.options.enableDeduplication) {
           this.addErrorFingerprint(error);
         }
-      } catch (e) {
+      } catch (_e) {
         // Don't let error reporting cause more errors
-        this.logError('Failed to report error to Faro', e);
       } finally {
         // Always call the original handler to maintain normal error behavior
         if (this.originalErrorHandler) {
@@ -175,13 +169,11 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
 
         // Check if error should be ignored
         if (this.shouldIgnoreError(error)) {
-          this.logDebug('Ignoring unhandled rejection based on ignoreErrors patterns', { message: error.message });
           return;
         }
 
         // Check for duplicate errors
         if (this.options.enableDeduplication && this.isDuplicateError(error)) {
-          this.logDebug('Ignoring duplicate unhandled rejection', { message: error.message });
           return;
         }
 
@@ -207,8 +199,8 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
         if (this.options.enableDeduplication) {
           this.addErrorFingerprint(error);
         }
-      } catch (e) {
-        this.logError('Failed to report unhandled rejection to Faro', e);
+      } catch (_e) {
+        // Don't let error reporting cause more errors
       }
     };
 

package/src/instrumentations/session/beforeSendHook.test.ts

@@ -0,0 +1,129 @@
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { initializeFaro } from '../../initialize';
+
+import { SessionInstrumentation } from './index';
+
+function testEventItems(transport: MockTransport) {
+  return transport.items.filter((i) => i.type === 'event' && i.payload.name === 'test_event');
+}
+
+describe('SessionInstrumentation beforeSend hook', () => {
+  let transport: MockTransport;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should pass through items when session is sampled (isSampled="true")', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Manually set session with isSampled='true'
+    faro.api.setSession({
+      id: 'test-session-id',
+      attributes: { isSampled: 'true' },
+    });
+
+    // Push an event
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should send the item (after removing isSampled attribute); ignore session_start from init / setSession
+    const testEvents = testEventItems(transport);
+    expect(testEvents).toHaveLength(1);
+    expect(testEvents[0].meta.session?.id).toBe('test-session-id');
+    expect(testEvents[0].meta.session?.attributes?.['isSampled']).toBeUndefined();
+  });
+
+  it('should drop items when session is not sampled (isSampled="false")', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Manually set session with isSampled='false'
+    faro.api.setSession({
+      id: 'test-session-id',
+      attributes: { isSampled: 'false' },
+    });
+
+    // Push an event
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should NOT send the test event (session_start may still be emitted before setSession)
+    expect(testEventItems(transport)).toHaveLength(0);
+  });
+
+  it('should pass through items when no isSampled attribute exists', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Manually set session WITHOUT isSampled attribute
+    faro.api.setSession({
+      id: 'test-session-id',
+      attributes: { customAttr: 'value' },
+    });
+
+    // Push an event
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should send the item unchanged
+    const testEvents = testEventItems(transport);
+    expect(testEvents).toHaveLength(1);
+    expect(testEvents[0].meta.session?.id).toBe('test-session-id');
+    expect(testEvents[0].meta.session?.attributes?.['customAttr']).toBe('value');
+  });
+
+  it('should pass through items when no session exists', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Push an event without setting any session
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should send the test event (session is set at init)
+    expect(testEventItems(transport)).toHaveLength(1);
+  });
+});

package/src/instrumentations/session/index.ts

@@ -1,11 +1,10 @@
 import { BaseInstrumentation, dateNow, EVENT_SESSION_START, genShortID, VERSION } from '@grafana/faro-core';
 import type { Config, Meta, MetaSession, TransportItem } from '@grafana/faro-core';
 
-import type { ReactNativeSessionTrackingConfig } from '../../config/types';
+import type { ReactNativeFullConfig, ReactNativeSessionTrackingConfig } from '../../config/types';
 
-import { getSessionAttributes } from './sessionAttributes';
+import { minimalSessionDeviceAttributes, type SessionAttributes } from './sessionAttributes';
 import { type FaroUserSession, getSessionManagerByConfig, isSampled } from './sessionManager';
-import { PersistentSessionsManager } from './sessionManager/PersistentSessionsManager';
 import { MAX_SESSION_PERSISTENCE_TIME } from './sessionManager/sessionConstants';
 import { createUserSessionObject, isUserSessionValid } from './sessionManager/sessionManagerUtils';
 import type { SessionManager } from './sessionManager/types';
@@ -23,6 +22,14 @@ export class SessionInstrumentation extends BaseInstrumentation {
   private notifiedSession: MetaSession | undefined;
   private sessionManagerInstance: InstanceType<SessionManager> | undefined;
 
+  private getDefaultSessionDeviceAttributes(): SessionAttributes {
+    const cfg = this.config as ReactNativeFullConfig;
+    if (cfg.preloadedSessionDeviceAttributes != null) {
+      return cfg.preloadedSessionDeviceAttributes;
+    }
+    return minimalSessionDeviceAttributes();
+  }
+
   private sendSessionStartEvent(meta: Meta): void {
     const session = meta.session;
 
@@ -34,14 +41,14 @@ export class SessionInstrumentation extends BaseInstrumentation {
     }
   }
 
-  private async createInitialSession(
-    SessionManager: SessionManager,
+  private createInitialSession(
+    SessionManagerClass: SessionManager,
     sessionsConfig: Required<Config>['sessionTracking']
-  ): Promise<{
+  ): {
     initialSession: FaroUserSession;
     emitSessionStartOnInit: boolean;
-  }> {
-    let storedUserSession: FaroUserSession | null = await SessionManager.fetchUserSession();
+  } {
+    let storedUserSession = SessionManagerClass.fetchUserSession();
 
     const sessionsConfigTyped = sessionsConfig as ReactNativeSessionTrackingConfig;
     const maxPersistenceMs = sessionsConfigTyped.maxSessionPersistenceTime ?? MAX_SESSION_PERSISTENCE_TIME;
@@ -51,14 +58,12 @@ export class SessionInstrumentation extends BaseInstrumentation {
       const shouldClearPersistentSession = storedUserSession.lastActivity < now - maxPersistenceMs;
 
       if (shouldClearPersistentSession) {
-        await PersistentSessionsManager.removeUserSession();
+        SessionManagerClass.removeUserSession();
         storedUserSession = null;
       }
     }
 
-    // Get default session attributes (device info, SDK version, etc.)
-    // These match the Flutter SDK's default session attributes
-    const defaultAttributes = await getSessionAttributes();
+    const defaultAttributes = this.getDefaultSessionDeviceAttributes();
 
     let emitSessionStartOnInit: boolean;
     let initialSession: FaroUserSession;
@@ -68,7 +73,7 @@ export class SessionInstrumentation extends BaseInstrumentation {
 
       initialSession = createUserSessionObject({
         sessionId,
-        isSampled: storedUserSession!.isSampled || false,
+        isSampled: storedUserSession?.isSampled || false,
         started: storedUserSession?.started,
       });
 
@@ -124,15 +129,24 @@ export class SessionInstrumentation extends BaseInstrumentation {
     return { initialSession, emitSessionStartOnInit };
   }
 
-  private registerBeforeSendHook(SessionManager: SessionManager) {
-    const { updateSession } = new SessionManager();
+  private registerBeforeSendHook(SessionManagerClass: SessionManager) {
+    const { updateSession } = new SessionManagerClass();
 
     this.transports?.addBeforeSendHooks((item: TransportItem) => {
       updateSession();
 
       const attributes = item.meta.session?.attributes;
 
-      if (attributes && attributes?.['isSampled'] === 'true') {
+      // Only filter out items when session is explicitly NOT sampled (isSampled='false')
+      // If isSampled='true', remove the attribute before sending (it's internal)
+      // If no isSampled attribute, pass through the item unchanged
+      if (attributes?.['isSampled'] === 'false') {
+        // Session is not sampled - drop this item
+        return null;
+      }
+
+      if (attributes?.['isSampled'] === 'true') {
+        // Session is sampled - remove internal isSampled attribute before sending
         let newItem: TransportItem = JSON.parse(JSON.stringify(item));
 
         const newAttributes = newItem.meta.session?.attributes;
@@ -145,38 +159,37 @@ export class SessionInstrumentation extends BaseInstrumentation {
         return newItem;
       }
 
-      return null;
+      // No isSampled attribute or other value - pass through unchanged
+      return item;
     });
   }
 
-  async initialize(): Promise<void> {
-    this.logDebug('init session instrumentation');
-
+  initialize(): void {
     const sessionTrackingConfig = this.config.sessionTracking;
 
-    if (sessionTrackingConfig?.enabled) {
-      const SessionManager = getSessionManagerByConfig(sessionTrackingConfig);
-
-      this.registerBeforeSendHook(SessionManager);
+    if (!sessionTrackingConfig?.enabled) {
+      this.metas.addListener(this.sendSessionStartEvent.bind(this));
+      return;
+    }
 
-      const { initialSession, emitSessionStartOnInit } = await this.createInitialSession(
-        SessionManager,
-        sessionTrackingConfig
-      );
+    const SessionManagerClass = getSessionManagerByConfig(sessionTrackingConfig);
 
-      await SessionManager.storeUserSession(initialSession);
+    this.registerBeforeSendHook(SessionManagerClass);
 
-      const initialSessionMeta = initialSession.sessionMeta;
+    const { initialSession, emitSessionStartOnInit } = this.createInitialSession(
+      SessionManagerClass,
+      sessionTrackingConfig
+    );
+    SessionManagerClass.storeUserSession(initialSession);
 
-      this.notifiedSession = initialSessionMeta;
-      this.api.setSession(initialSessionMeta);
+    const initialSessionMeta = initialSession.sessionMeta;
+    this.notifiedSession = initialSessionMeta;
+    this.api.setSession(initialSessionMeta);
 
-      // Store the session manager instance for cleanup
-      this.sessionManagerInstance = new SessionManager();
+    this.sessionManagerInstance = new SessionManagerClass();
 
-      if (emitSessionStartOnInit) {
-        this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
-      }
+    if (emitSessionStartOnInit) {
+      this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
     }
 
     this.metas.addListener(this.sendSessionStartEvent.bind(this));

package/src/instrumentations/session/sessionAttributes.test.ts

@@ -1,8 +1,6 @@
 import { Platform } from 'react-native';
 import DeviceInfo from 'react-native-device-info';
 
-import { VERSION } from '@grafana/faro-core';
-
 import { getSessionAttributes } from './sessionAttributes';
 
 // Mock react-native-device-info
@@ -66,7 +64,6 @@ describe('sessionAttributes', () => {
         const attributes = await getSessionAttributes();
 
         expect(attributes).toEqual({
-          faro_sdk_version: VERSION,
           react_native_version: '0.75.1',
           device_os: 'iOS',
           device_os_version: '17.0',
@@ -163,7 +160,6 @@ describe('sessionAttributes', () => {
         const attributes = await getSessionAttributes();
 
         expect(attributes).toEqual({
-          faro_sdk_version: VERSION,
           react_native_version: '0.75.1',
           device_os: 'Android',
           device_os_version: '15',
@@ -302,23 +298,12 @@ describe('sessionAttributes', () => {
 
         const attributes = await getSessionAttributes();
 
-        // Should return minimal attributes with fallbacks
+        // Device info is omitted when collection fails so nothing partial is sent to Faro
         expect(attributes).toEqual({
-          faro_sdk_version: VERSION,
           react_native_version: expect.any(String),
-          device_os: expect.stringMatching(/iOS|Android/),
-          device_os_version: 'unknown',
-          device_os_detail: 'unknown',
-          device_manufacturer: 'unknown',
-          device_model: 'unknown',
-          device_model_name: 'unknown',
-          device_brand: 'unknown',
-          device_is_physical: 'true',
-          device_id: 'unknown',
-          device_type: 'mobile',
-          device_memory_total: '0',
-          device_memory_used: '0',
         });
+        expect(attributes.device_id).toBeUndefined();
+        expect(attributes.device_os).toBeUndefined();
       });
 
       it('should handle partial DeviceInfo failures', async () => {
@@ -337,12 +322,13 @@ describe('sessionAttributes', () => {
 
         const attributes = await getSessionAttributes();
 
-        // Due to the catch-all error handling, when any method throws,
-        // the entire function returns fallback values
-        expect(attributes.device_id).toBe('unknown');
-        expect(attributes.device_os).toMatch(/iOS|Android/);
-        expect(attributes.device_model).toBe('unknown');
-        expect(attributes.device_manufacturer).toBe('unknown');
+        // Any synchronous DeviceInfo failure skips all device fields (minimal payload only)
+        expect(attributes).toEqual({
+          react_native_version: expect.any(String),
+        });
+        expect(attributes.device_id).toBeUndefined();
+        expect(attributes.device_manufacturer).toBeUndefined();
+        expect(attributes.device_model).toBeUndefined();
       });
     });
 
@@ -385,23 +371,5 @@ describe('sessionAttributes', () => {
         expect(attributes.device_manufacturer).toBe('oneplus');
       });
     });
-
-    describe('SDK version', () => {
-      it('should always include SDK version from @grafana/faro-core', async () => {
-        (DeviceInfo.getUniqueId as jest.Mock).mockResolvedValue('uuid');
-        (DeviceInfo.getSystemName as jest.Mock).mockReturnValue('iOS');
-        (DeviceInfo.getSystemVersion as jest.Mock).mockReturnValue('17.0');
-        (DeviceInfo.getManufacturerSync as jest.Mock).mockReturnValue('Apple');
-        (DeviceInfo.getModel as jest.Mock).mockReturnValue('iPhone16,1');
-        (DeviceInfo.getDeviceNameSync as jest.Mock).mockReturnValue('iPhone 15 Pro');
-        (DeviceInfo.getBrand as jest.Mock).mockReturnValue('Apple');
-        (DeviceInfo.isEmulatorSync as jest.Mock).mockReturnValue(false);
-
-        const attributes = await getSessionAttributes();
-
-        expect(attributes.faro_sdk_version).toBe(VERSION);
-        expect(attributes.faro_sdk_version).toMatch(/^\d+\.\d+\.\d+/);
-      });
-    });
   });
 });

package/src/instrumentations/session/sessionAttributes.ts

@@ -1,57 +1,56 @@
 import { Platform } from 'react-native';
 import DeviceInfo from 'react-native-device-info';
 
-import { VERSION } from '@grafana/faro-core';
-
 /**
  * Session attributes for React Native
  * These attributes are automatically included with every telemetry event
  *
  * Core attributes match Flutter SDK format, with additional mobile-specific
  * monitoring fields (memory, device type, battery, etc.)
+ *
+ * SDK name, core version, and npm adapter are on Faro meta `sdk` (`getSdkMeta` in `metas/sdk.ts`).
+ *
+ * `react_native_version` is the host app's React Native **framework** version from `Platform`, not the Faro package.
  */
 export interface SessionAttributes {
-  /** SDK version (e.g., "2.0.2") */
-  faro_sdk_version: string;
-
-  /** React Native version (e.g., "0.75.1") */
+  /** Host app's React Native framework version (e.g. "0.75.1") from `Platform.constants`. */
   react_native_version: string;
 
   /** Operating system ("iOS" or "Android") */
-  device_os: string;
+  device_os?: string;
 
   /** OS version (e.g., "17.0" for iOS, "15" for Android) */
-  device_os_version: string;
+  device_os_version?: string;
 
   /** Detailed OS info (e.g., "iOS 17.0" or "Android 15 (SDK 35)") */
-  device_os_detail: string;
+  device_os_detail?: string;
 
   /** Device manufacturer (e.g., "apple", "samsung") */
-  device_manufacturer: string;
+  device_manufacturer?: string;
 
   /** Raw model identifier (e.g., "iPhone16,1", "SM-A155F") */
-  device_model: string;
+  device_model?: string;
 
   /** Human-readable model name (e.g., "iPhone 15 Pro") */
-  device_model_name: string;
+  device_model_name?: string;
 
   /** Device brand (e.g., "iPhone", "samsung") */
-  device_brand: string;
+  device_brand?: string;
 
   /** Whether device is physical or emulator ("true" or "false") */
-  device_is_physical: string;
+  device_is_physical?: string;
 
   /** Unique device ID (UUID) */
-  device_id: string;
+  device_id?: string;
 
   /** Device type ("mobile" or "tablet") */
-  device_type: string;
+  device_type?: string;
 
   /** Total device memory in bytes */
-  device_memory_total: string;
+  device_memory_total?: string;
 
   /** Currently used memory in bytes */
-  device_memory_used: string;
+  device_memory_used?: string;
 
   /** Battery level percentage (e.g., "85") - empty if unavailable */
   device_battery_level?: string;
@@ -67,12 +66,10 @@ export interface SessionAttributes {
 }
 
 /**
- * Get React Native version from Platform
- * Returns "unknown" if not available
+ * React Native framework version from `Platform.constants` (host app runtime), not `@grafana/faro-react-native` semver.
  */
 function getReactNativeVersion(): string {
   try {
-    // Platform.constants.reactNativeVersion is an object like { major: 0, minor: 75, patch: 1 }
     const version = Platform.constants.reactNativeVersion;
     if (version && typeof version === 'object') {
       const { major, minor, patch, prerelease } = version as {
@@ -127,12 +124,22 @@ async function getDeviceOsDetail(): Promise<string> {
   return `${systemName} ${systemVersion}`;
 }
 
+/**
+ * Session attributes without device props when async collection or DeviceInfo is unavailable.
+ * No synchronous DeviceInfo reads — use {@link getSessionAttributes} or the package async `initializeFaro`.
+ */
+export function minimalSessionDeviceAttributes(): SessionAttributes {
+  return {
+    react_native_version: getReactNativeVersion(),
+  };
+}
+
 /**
  * Get all session attributes
  * These attributes are automatically included with every telemetry event
  *
  * Core attributes matching Flutter SDK:
- * - faro_sdk_version, react_native_version
+ * - react_native_version (RN framework in the host app)
  * - device_os, device_os_version, device_os_detail
  * - device_manufacturer, device_model, device_model_name
  * - device_brand, device_is_physical, device_id
@@ -162,8 +169,6 @@ export async function getSessionAttributes(): Promise<SessionAttributes> {
     // Memory info
     const totalMemory = DeviceInfo.getTotalMemorySync();
     const usedMemory = DeviceInfo.getUsedMemorySync();
-
-    // React Native version (equivalent to dart_version in Flutter)
     const reactNativeVersion = getReactNativeVersion();
 
     // Try to get async device info (battery, carrier)
@@ -207,7 +212,6 @@ export async function getSessionAttributes(): Promise<SessionAttributes> {
     }
 
     const attributes: SessionAttributes = {
-      faro_sdk_version: VERSION,
       react_native_version: reactNativeVersion,
       device_os: systemName,
       device_os_version: systemVersion,
@@ -229,22 +233,18 @@ export async function getSessionAttributes(): Promise<SessionAttributes> {
 
     return attributes;
   } catch (_error) {
-    // If anything fails, return minimal attributes
-    return {
-      faro_sdk_version: VERSION,
-      react_native_version: getReactNativeVersion(),
-      device_os: Platform.OS === 'ios' ? 'iOS' : 'Android',
-      device_os_version: 'unknown',
-      device_os_detail: 'unknown',
-      device_manufacturer: 'unknown',
-      device_model: 'unknown',
-      device_model_name: 'unknown',
-      device_brand: 'unknown',
-      device_is_physical: 'true',
-      device_id: 'unknown',
-      device_type: 'mobile',
-      device_memory_total: '0',
-      device_memory_used: '0',
-    };
+    return minimalSessionDeviceAttributes();
+  }
+}
+
+/**
+ * Await full async session device attributes (battery, carrier, etc.), then fall back to
+ * {@link minimalSessionDeviceAttributes} if anything throws. Used by async `initializeFaro`.
+ */
+export async function loadSessionDeviceAttributesForInit(): Promise<SessionAttributes> {
+  try {
+    return await getSessionAttributes();
+  } catch {
+    return minimalSessionDeviceAttributes();
   }
 }