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

package/dist/types/index.d.ts

@@ -7,6 +7,8 @@ export { ErrorMechanism, ErrorsInstrumentation } from './instrumentations/errors
 export type { ErrorMechanismType, ErrorsInstrumentationOptions } from './instrumentations/errors';
 export { ConsoleInstrumentation } from './instrumentations/console';
 export { SessionInstrumentation } from './instrumentations/session';
+export { getSessionAttributes, loadSessionDeviceAttributesForInit, minimalSessionDeviceAttributes, } from './instrumentations/session/sessionAttributes';
+export type { SessionAttributes } from './instrumentations/session/sessionAttributes';
 export { ViewInstrumentation } from './instrumentations/view';
 export { AppStateInstrumentation } from './instrumentations/appState';
 export { UserActionInstrumentation } from './instrumentations/userActions';
@@ -45,4 +47,4 @@ export { ReactNativeNavigationIntegration } from './navigation/v6';
 export { useFaroNavigation, createNavigationStateChangeHandler, getCurrentRoute, getRouteName, onNavigationStateChange, } from './navigation';
 export type { ReactNavigationDependencies, ReactNavigationConfig } from './navigation/types';
 export type { Config, Faro, Instrumentation, Meta, Transport, PushErrorOptions, PushEventOptions, PushLogOptions, PushMeasurementOptions, } from '@grafana/faro-core';
-export { LogLevel } from '@grafana/faro-core';
+export { LogLevel, InternalLoggerLevel, allLogLevels, defaultLogLevel } from './internalLogger';

package/dist/types/initialize.d.ts

@@ -1,3 +1,7 @@
 import { type Faro } from '@grafana/faro-core';
 import type { ReactNativeConfig } from './config/types';
-export declare function initializeFaro(config: ReactNativeConfig): Faro;
+/**
+ * Awaits async device/session attribute collection, then initializes Faro with core `initializeFaro`.
+ * On failure during collection, uses `minimalSessionDeviceAttributes` before init.
+ */
+export declare function initializeFaro(config: ReactNativeConfig): Promise<Faro>;

package/dist/types/instrumentations/anr/instrumentation.d.ts

@@ -31,7 +31,7 @@ import type { ANRInstrumentationOptions } from './types';
  */
 export declare class ANRInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-anr";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private readonly options;
     private pollingIntervalId;
     constructor(options?: ANRInstrumentationOptions);

package/dist/types/instrumentations/appState/index.d.ts

@@ -10,7 +10,7 @@ export declare const EVENT_APP_STATE_CHANGED = "app_lifecycle_changed";
  */
 export declare class AppStateInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-appstate";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private currentState;
     private stateStartTime;
     private appStateSubscription;

package/dist/types/instrumentations/console/index.d.ts

@@ -11,12 +11,13 @@ import { BaseInstrumentation, LogLevel } from '@grafana/faro-core';
  */
 export declare class ConsoleInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-console";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     static defaultDisabledLevels: LogLevel[];
     static consoleErrorPrefix: string;
     private originalConsole;
     private errorSerializer;
     private patchedLevels;
+    private isProcessing;
     initialize(): void;
     /**
      * Restore original console methods

package/dist/types/instrumentations/crashReporting/instrumentation.d.ts

@@ -28,7 +28,7 @@ import type { CrashReportingOptions } from './types';
  */
 export declare class CrashReportingInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-crash";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private readonly options;
     constructor(options?: CrashReportingOptions);
     initialize(): Promise<void>;

package/dist/types/instrumentations/errors/index.d.ts

@@ -35,10 +35,9 @@ export interface ErrorsInstrumentationOptions {
  *
  * @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({

package/dist/types/instrumentations/frameMonitoring/instrumentation.d.ts

@@ -40,7 +40,7 @@ import type { FrameMonitoringOptions } from './types';
  */
 export declare class FrameMonitoringInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-frame-monitoring";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private readonly options;
     private pollingIntervalId;
     private eventEmitter;

package/dist/types/instrumentations/http/index.d.ts

@@ -29,7 +29,7 @@ export type { HttpRequestPayload } from './utils';
  */
 export declare class HttpInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-http";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private originalFetch?;
     private ignoredUrls;
     private requests;

package/dist/types/instrumentations/performance/index.d.ts

@@ -43,7 +43,7 @@ import type { PerformanceInstrumentationOptions } from './types';
  */
 export declare class PerformanceInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-performance";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private options;
     private intervalId;
     constructor(options?: PerformanceInstrumentationOptions);

package/dist/types/instrumentations/session/index.d.ts

@@ -5,13 +5,14 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class SessionInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-session";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private notifiedSession;
     private sessionManagerInstance;
+    private getDefaultSessionDeviceAttributes;
     private sendSessionStartEvent;
     private createInitialSession;
     private registerBeforeSendHook;
-    initialize(): Promise<void>;
+    initialize(): void;
     /**
      * Clean up session manager listeners
      */

package/dist/types/instrumentations/session/sessionAttributes.d.ts

@@ -4,36 +4,38 @@
  *
  * 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;
     /** Whether device is charging ("true" or "false") - empty if unavailable */
@@ -43,12 +45,17 @@ export interface SessionAttributes {
     /** Mobile carrier name (e.g., "Verizon") - empty if unavailable */
     device_carrier?: string;
 }
+/**
+ * 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 declare function minimalSessionDeviceAttributes(): SessionAttributes;
 /**
  * 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
@@ -60,3 +67,8 @@ export interface SessionAttributes {
  * - device_carrier
  */
 export declare function getSessionAttributes(): Promise<SessionAttributes>;
+/**
+ * Await full async session device attributes (battery, carrier, etc.), then fall back to
+ * {@link minimalSessionDeviceAttributes} if anything throws. Used by async `initializeFaro`.
+ */
+export declare function loadSessionDeviceAttributesForInit(): Promise<SessionAttributes>;

package/dist/types/instrumentations/session/sessionManager/MmkvPersistentSessionsManager.d.ts

@@ -0,0 +1,20 @@
+import type { FaroUserSession } from './types';
+/** @internal */
+export declare function resetMmkvSingletonForTests(): void;
+/**
+ * Persistent session storage backed by MMKV (synchronous reads/writes).
+ * Used when `sessionTracking.persistent` is true.
+ */
+export declare class MmkvPersistentSessionsManager {
+    private updateUserSession;
+    private appStateSubscription;
+    private metaUnsubscribe;
+    constructor();
+    static removeUserSession(): void;
+    static storeUserSession(session: FaroUserSession): void;
+    static fetchUserSession(): FaroUserSession | null;
+    updateSession: () => Promise<void>;
+    private handleAppStateChange;
+    private init;
+    unpatch(): void;
+}

package/dist/types/instrumentations/session/sessionManager/index.d.ts

@@ -1,5 +1,5 @@
 export { getSessionManagerByConfig } from './getSessionManagerByConfig';
-export { PersistentSessionsManager } from './PersistentSessionsManager';
+export { MmkvPersistentSessionsManager } from './MmkvPersistentSessionsManager';
 export { isSampled } from './sampling';
 export * from './sessionConstants';
 export * from './sessionManagerUtils';

package/dist/types/instrumentations/session/sessionManager/types.d.ts

@@ -1,5 +1,5 @@
 import type { MetaSession } from '@grafana/faro-core';
-import type { PersistentSessionsManager } from './PersistentSessionsManager';
+import type { MmkvPersistentSessionsManager } from './MmkvPersistentSessionsManager';
 import type { VolatileSessionsManager } from './VolatileSessionManager';
 export interface FaroUserSession {
     sessionId: string;
@@ -8,4 +8,4 @@ export interface FaroUserSession {
     isSampled: boolean;
     sessionMeta?: MetaSession;
 }
-export type SessionManager = typeof VolatileSessionsManager | typeof PersistentSessionsManager;
+export type SessionManager = typeof VolatileSessionsManager | typeof MmkvPersistentSessionsManager;

package/dist/types/instrumentations/startup/index.d.ts

@@ -37,7 +37,7 @@ import type { StartupInstrumentationOptions } from './types';
 export declare class StartupInstrumentation extends BaseInstrumentation {
     private options;
     readonly name = "@grafana/faro-react-native:instrumentation-startup";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     /** 0 = came from background (warm start eligible), null = never backgrounded */
     private warmStartTimestamp;
     private appStateSubscription;

package/dist/types/instrumentations/userActions/index.d.ts

@@ -24,7 +24,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class UserActionInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-user-action";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private _userActionSub?;
     initialize(): void;
     /**

package/dist/types/instrumentations/view/index.d.ts

@@ -9,7 +9,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class ViewInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-view";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private notifiedView;
     private metaUnsubscribe;
     private sendViewChangedEvent;

package/dist/types/instrumentations/xhr/index.d.ts

@@ -7,7 +7,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class XHRInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-xhr";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private originalOpen?;
     private originalSend?;
     private ignoredUrls;

package/dist/types/internalLogger/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Internal logger levels - copied from @grafana/faro-core to avoid bundling web code
+ * Keep in sync with @grafana/faro-core's InternalLoggerLevel
+ */
+export declare enum InternalLoggerLevel {
+    OFF = 0,
+    ERROR = 1,
+    WARN = 2,
+    INFO = 3,
+    VERBOSE = 4
+}
+/**
+ * Log levels for console/logging - copied from @grafana/faro-core to avoid bundling web code
+ * Keep in sync with @grafana/faro-core's LogLevel
+ */
+export declare enum LogLevel {
+    TRACE = "trace",
+    DEBUG = "debug",
+    INFO = "info",
+    LOG = "log",
+    WARN = "warn",
+    ERROR = "error"
+}
+export declare const defaultLogLevel = LogLevel.LOG;
+export declare const allLogLevels: ReadonlyArray<Readonly<LogLevel>>;

package/dist/types/metas/sdk.d.ts

@@ -1,6 +1,8 @@
 import type { Meta, MetaItem } from '@grafana/faro-core';
 /**
- * SDK meta for React Native
- * Provides information about the Faro SDK and its integrations
+ * SDK meta for React Native.
+ * - `sdk.version`: `@grafana/faro-core` release (same as Faro Web SDK).
+ * - `sdk.name`: integration id (`faro-web` / `faro-react-native`).
+ * - `sdk.integrations`: published `@grafana/faro-react-native` npm name and semver for this build.
  */
 export declare const getSdkMeta: () => MetaItem<Pick<Meta, "sdk">>;

package/dist/types/testUtils/mockFaroReactNativeTracing.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Jest stub for optional peer `@grafana/faro-react-native-tracing`.
+ * Mapped via moduleNameMapper so tests run without installing the tracing workspace package.
+ */
+import { BaseInstrumentation } from '@grafana/faro-core';
+export declare class TracingInstrumentation extends BaseInstrumentation {
+    readonly name = "@grafana/faro-react-native-tracing";
+    readonly version = "2.3.1";
+    initialize(): void;
+}

package/dist/types/transports/console/transport.d.ts

@@ -4,7 +4,7 @@ import type { ConsoleTransportOptions } from './types';
 export declare class ConsoleTransport extends BaseTransport {
     private options;
     readonly name = "@grafana/faro-react-native:transport-console";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     constructor(options?: ConsoleTransportOptions);
     send(item: TransportItem): void;
 }

package/dist/types/transports/fetch/transport.d.ts

@@ -4,7 +4,7 @@ import type { FetchTransportOptions } from './types';
 export declare class FetchTransport extends BaseTransport {
     private options;
     readonly name = "@grafana/faro-react-native:transport-fetch";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     promiseBuffer: PromiseBuffer<Response | void>;
     private readonly rateLimitBackoffMs;
     private readonly getNow;

package/dist/types/transports/offline/transport.d.ts

@@ -31,7 +31,7 @@ import type { OfflineTransportOptions } from './types';
  */
 export declare class OfflineTransport extends BaseTransport {
     readonly name = "@grafana/faro-react-native:transport-offline";
-    readonly version = "2.2.3";
+    readonly version = "2.3.1";
     private readonly cache;
     private readonly connectivityService;
     private readonly maxCacheDurationMs;

package/dist/types/util/performanceObserverPolyfill.d.ts

@@ -13,7 +13,10 @@
  * @see https://github.com/facebook/react-native/issues (PerformanceObserver iOS)
  */
 /**
- * Apply polyfill on React Native iOS to prevent bad_variant_access crash.
- * Must run before any code that might use PerformanceObserver.
+ * Apply React Native performance API compatibility patches.
+ *
+ * Resource Timing lookup is patched on all platforms because OTel web
+ * instrumentation can probe it. The PerformanceObserver replacement is
+ * iOS-only to avoid the native bad_variant_access crash.
  */
 export declare function applyPerformanceObserverPolyfill(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/faro-react-native",
-  "version": "1.0.0-alpha.1",
+  "version": "1.1.0",
   "description": "Faro instrumentations, metas, transports for React Native.",
   "keywords": [
     "observability",
@@ -31,11 +31,13 @@
     "ios",
     "android",
     "FaroReactNative.podspec",
+    "react-native.config.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "yarn watch",
+    "sync:package-meta": "node ./scripts/sync-faro-rn-package-meta.mjs",
     "build": "run-s 'build:*'",
     "build:compile": "run-p 'build:compile:*'",
     "build:compile:cjs": "tsc --build tsconfig.cjs.json",
@@ -50,7 +52,8 @@
     "quality:lint": "run-p 'quality:lint:eslint' 'quality:lint:prettier'",
     "quality:lint:eslint": "eslint --cache --cache-location ../../.cache/eslint/reactNative \"./**/*.{js,jsx,ts,tsx}\"",
     "quality:lint:prettier": "prettier --cache --cache-location=../../.cache/prettier/reactNative --ignore-path ../../.prettierignore -c \"./**/*.{js,jsx,ts,tsx,css,scss,md,yaml,yml,json}\"",
-    "quality:circular-deps": "madge --circular ."
+    "quality:circular-deps": "madge --circular .",
+    "version": "node ./scripts/sync-faro-rn-package-meta.mjs && git add src/generated/faroRNPackageMeta.ts"
   },
   "dependencies": {
     "@grafana/faro-core": "^2.2.3",
@@ -61,7 +64,8 @@
     "@grafana/faro-react-native-tracing": ">=1.0.0",
     "@react-navigation/native": ">=6.0.0",
     "react": ">=18.0.0",
-    "react-native": ">=0.70.0"
+    "react-native": ">=0.70.0",
+    "react-native-mmkv": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "@grafana/faro-react-native-tracing": {
@@ -69,15 +73,19 @@
     },
     "@react-navigation/native": {
       "optional": true
+    },
+    "react-native-mmkv": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "24.10.1",
     "@types/react": "^19.1.1",
-    "@types/react-native": "^0.73.0"
+    "@types/react-native": "^0.73.0",
+    "react-native-mmkv": "^4.3.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "486ee5d65eb1e274a7e207e0c9c04cccffe98c2e"
+  "gitHead": "8ca367978d53ef163886a2e99690c6f8a61416dc"
 }

package/react-native.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      ios: {},
+      android: {},
+    },
+  },
+};

package/src/config/getRNInstrumentations.test.ts

@@ -1,16 +1,3 @@
-/** Keeps tests working without a workspace devDependency (avoids npm/Lerna cycle: tracing → react-native → tracing). */
-jest.mock('@grafana/faro-react-native-tracing', () => {
-  const { BaseInstrumentation, VERSION } = require('@grafana/faro-core');
-
-  class TracingInstrumentation extends BaseInstrumentation {
-    readonly name = '@grafana/faro-react-native-tracing';
-    readonly version = VERSION;
-    initialize(): void {}
-  }
-
-  return { TracingInstrumentation };
-});
-
 import { Platform } from 'react-native';
 
 import { TracingInstrumentation } from '@grafana/faro-react-native-tracing';

package/src/config/getRNInstrumentations.ts

@@ -114,13 +114,15 @@ export function getRNInstrumentations(config: Partial<ReactNativeConfig> = {}):
     }
   }
 
-  // Performance vitals (CPU/memory)
-  const perfInstrumentation = new PerformanceInstrumentation({
-    memoryUsageVitals,
-    cpuUsageVitals,
-    fetchVitalsInterval,
-  });
-  instrumentations.push(perfInstrumentation);
+  // Performance vitals (CPU/memory) - only add if at least one metric is enabled
+  if (cpuUsageVitals || memoryUsageVitals) {
+    const perfInstrumentation = new PerformanceInstrumentation({
+      memoryUsageVitals,
+      cpuUsageVitals,
+      fetchVitalsInterval,
+    });
+    instrumentations.push(perfInstrumentation);
+  }
 
   // Startup tracking - always enabled
   instrumentations.push(new StartupInstrumentation());

package/src/config/makeRNConfig.test.ts

@@ -1,5 +1,6 @@
 import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
 
+import { minimalSessionDeviceAttributes } from '../instrumentations/session/sessionAttributes';
 import { defaultSessionTrackingConfig } from '../instrumentations/session/sessionManager/sessionConstants';
 import { ConsoleTransport } from '../transports/console';
 import { FetchTransport } from '../transports/fetch';
@@ -114,4 +115,16 @@ describe('makeRNConfig', () => {
     expect(minimal.instrumentations?.length).toBe(direct.length);
     expect(minimal.instrumentations?.map((i) => i.name)).toEqual(direct.map((i) => i.name));
   });
+
+  it('passes preloaded session device attributes to core config when provided as second argument', () => {
+    const preloaded = minimalSessionDeviceAttributes();
+    preloaded.device_id = 'test-preloaded-id';
+    const cfg = makeRNConfig({ ...base }, preloaded);
+    expect(
+      (cfg as { preloadedSessionDeviceAttributes?: { device_id: string } }).preloadedSessionDeviceAttributes
+    ).toBeDefined();
+    expect(
+      (cfg as { preloadedSessionDeviceAttributes?: { device_id: string } }).preloadedSessionDeviceAttributes?.device_id
+    ).toBe('test-preloaded-id');
+  });
 });

package/src/config/makeRNConfig.ts

@@ -1,8 +1,10 @@
-import { defaultGlobalObjectKey, defaultUnpatchedConsole, InternalLoggerLevel, LogLevel } from '@grafana/faro-core';
+import { defaultGlobalObjectKey, defaultUnpatchedConsole } from '@grafana/faro-core';
 import type { Config } from '@grafana/faro-core';
 
 import { getStackFramesFromError } from '../instrumentations/errors/stackTraceParser';
+import type { SessionAttributes } from '../instrumentations/session/sessionAttributes';
 import { defaultSessionTrackingConfig } from '../instrumentations/session/sessionManager/sessionConstants';
+import { InternalLoggerLevel, LogLevel } from '../internalLogger';
 import { getPageMeta } from '../metas/page';
 import { getScreenMeta } from '../metas/screen';
 import { getSdkMeta } from '../metas/sdk';
@@ -11,7 +13,7 @@ import { FetchTransport } from '../transports/fetch';
 import { OfflineTransport } from '../transports/offline';
 
 import { getRNInstrumentations } from './getRNInstrumentations';
-import type { ReactNativeConfig, ReactNativeSessionTrackingConfig } from './types';
+import type { ReactNativeConfig, ReactNativeFullConfig } from './types';
 
 const DEFAULT_OFFLINE_CACHE_MS = 3 * 24 * 60 * 60 * 1000; // 3 days
 
@@ -72,8 +74,13 @@ const parseStacktrace: Config['parseStacktrace'] = (err) => ({
  *
  * Based on flags, builds instrumentations and transports automatically.
  * Client just enables what they need; makeRNConfig does the rest.
+ *
+ * @param preloadedSessionDeviceAttributes Device/session fields for session meta (passed from async `initializeFaro`).
  */
-export function makeRNConfig(config: ReactNativeConfig): Config {
+export function makeRNConfig(
+  config: ReactNativeConfig,
+  preloadedSessionDeviceAttributes?: SessionAttributes
+): ReactNativeFullConfig {
   const defaultMetas = [getSdkMeta(), getPageMeta(), getScreenMeta()];
   const customMetas = config.metas ?? [];
   const transports = buildTransports(config);
@@ -81,6 +88,9 @@ export function makeRNConfig(config: ReactNativeConfig): Config {
 
   return {
     app: config.app,
+    ...(preloadedSessionDeviceAttributes != null && {
+      preloadedSessionDeviceAttributes,
+    }),
     dedupe: config.dedupe ?? true,
     globalObjectKey: config.globalObjectKey ?? defaultGlobalObjectKey,
     internalLoggerLevel: config.internalLoggerLevel ?? InternalLoggerLevel.ERROR,
@@ -97,7 +107,7 @@ export function makeRNConfig(config: ReactNativeConfig): Config {
     sessionTracking: {
       ...defaultSessionTrackingConfig,
       ...config.sessionTracking,
-    } as ReactNativeSessionTrackingConfig,
+    },
     metas: [...defaultMetas, ...customMetas],
     instrumentations,
     transports,

package/src/config/types.ts

@@ -2,6 +2,7 @@ import type { Config } from '@grafana/faro-core';
 
 import type { ANRInstrumentationOptions } from '../instrumentations/anr';
 import type { FrameMonitoringOptions } from '../instrumentations/frameMonitoring';
+import type { SessionAttributes } from '../instrumentations/session/sessionAttributes';
 
 import type { Sampling } from './sampling';
 
@@ -9,6 +10,9 @@ import type { Sampling } from './sampling';
  * React Native session tracking config.
  * Extends Config['sessionTracking'] with sampling (Flutter-style) and RN-specific props.
  * Excludes samplingRate and sampler in favor of sampling.
+ *
+ * When `persistent` is true, sessions are stored with [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv)
+ * (synchronous). Add `react-native-mmkv` to your app and rebuild native projects.
  */
 export type ReactNativeSessionTrackingConfig = Omit<
   NonNullable<Config['sessionTracking']>,
@@ -77,3 +81,11 @@ export type ReactNativeConfig = Partial<
   Omit<Config, 'sessionTracking' | 'consoleInstrumentation' | 'userActionsInstrumentation'>
 > &
   ReactNativeConfigOverrides;
+
+/**
+ * Internal full config returned by `makeRNConfig`.
+ * Extends faro-core `Config` with RN-specific fields that instrumentations need at init time.
+ */
+export type ReactNativeFullConfig = Config & {
+  preloadedSessionDeviceAttributes?: SessionAttributes;
+};

package/src/generated/faroRNPackageMeta.test.ts

@@ -0,0 +1,10 @@
+import packageJson from '../../package.json';
+
+import { FARO_REACT_NATIVE_NPM_NAME, FARO_REACT_NATIVE_NPM_VERSION } from './faroRNPackageMeta';
+
+describe('faroRNPackageMeta', () => {
+  it('should match package.json (run yarn sync:package-meta after manual version edits, or use lerna version)', () => {
+    expect(FARO_REACT_NATIVE_NPM_NAME).toBe(packageJson.name);
+    expect(FARO_REACT_NATIVE_NPM_VERSION).toBe(packageJson.version);
+  });
+});

package/src/generated/faroRNPackageMeta.ts

@@ -0,0 +1,5 @@
+/**
+ * NPM package identity for this build. Generated by scripts/sync-faro-rn-package-meta.mjs - do not edit.
+ */
+export const FARO_REACT_NATIVE_NPM_NAME = '@grafana/faro-react-native' as const;
+export const FARO_REACT_NATIVE_NPM_VERSION = '1.1.0' as const;