@grafana/faro-react-native 1.2.1 → 1.3.0

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

@@ -3,44 +3,39 @@ import type { ANRInstrumentationOptions } from './types';
 /**
  * ANR (Application Not Responding) Detection Instrumentation.
  *
- * Detects when the main/UI thread is blocked for extended periods on Android.
- * Uses a background thread that posts tasks to the main thread and monitors
- * if they complete within the timeout.
+ * On Android 11+, historical ANRs are read from ApplicationExitInfo (Sentry AnrV2
+ * style) on the next launch. ANRTracker remains a pre-API-30 fallback and a
+ * persistence backup when the OS trace stream is empty.
  *
- * **Note**: ANR detection is only available on Android. iOS does not have
- * the same ANR concept as Android's system watchdog.
- *
- * Sends telemetry via Faro API:
- * - Measurement: `anr` with `anr_count` value (for dashboards)
- * - Error: Each ANR with `type: 'ANR'`, stack trace, duration, timestamp (Sentry-aligned)
- *
- * @example
- * ```typescript
- * import { initializeFaro, ANRInstrumentation } from '@grafana/faro-react-native';
- *
- * initializeFaro({
- *   url: 'https://collector.example.com',
- *   instrumentations: [
- *     new ANRInstrumentation({
- *       timeout: 5000,        // 5 second threshold
- *       pollingInterval: 60000, // Poll every 60 seconds
- *     }),
- *   ],
- * });
- * ```
+ * ANRs stay out of CrashReportingInstrumentation so they are not replayed as
+ * generic previous-session `crash` rows with empty messages.
  */
 export declare class ANRInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-anr";
-    readonly version = "2.3.1";
+    readonly version = "2.7.0";
     private readonly options;
     private pollingIntervalId;
+    private anrEventSubscription;
+    private readonly reportedAnrTimestamps;
+    private readonly preferAppExitInfoAnr;
     constructor(options?: ANRInstrumentationOptions);
     initialize(): void;
     private getNativeModule;
     private startNativeTracking;
+    private drainAllAnrSources;
+    private drainHistoricalAnrs;
+    private drainPendingANRs;
+    private handleLiveAnrEvent;
+    private fetchPendingANRs;
+    private acknowledgeANRs;
+    private acknowledgeNearbyPendingAnrs;
+    private reportAndAcknowledgePendingANRs;
+    private shouldReportTrackerAnr;
+    private reportANRIfNew;
+    private rememberReportedTimestamp;
+    private isNearbyReportedTimestamp;
+    private isNearbyTimestamp;
+    private reportANR;
     private checkANRStatus;
-    /**
-     * Clean up resources when instrumentation is disabled.
-     */
     unpatch(): void;
 }

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

@@ -10,7 +10,7 @@ export interface ANRInstrumentationOptions {
     timeout?: number;
     /**
      * Interval in milliseconds for polling ANR status from native.
-     * Default: 60000 (60 seconds, matching Flutter SDK's default)
+     * Default: 10000 (10 seconds). Native also emits onANRDetected immediately.
      */
     pollingInterval?: number;
 }
@@ -34,4 +34,8 @@ export interface ANREvent {
      * Duration of the ANR in milliseconds
      */
     duration: number;
+    /** Human-readable ANR description from ApplicationExitInfo when available. */
+    description?: string;
+    /** `AppExitInfo` (preferred) or `ANRTracker` (fallback). */
+    source?: string;
 }

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.3.1";
+    readonly version = "2.7.0";
     private currentState;
     private stateStartTime;
     private appStateSubscription;

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

@@ -11,7 +11,7 @@ import { BaseInstrumentation, LogLevel } from '@grafana/faro-core';
  */
 export declare class ConsoleInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-console";
-    readonly version = "2.3.1";
+    readonly version = "2.7.0";
     static defaultDisabledLevels: LogLevel[];
     static consoleErrorPrefix: string;
     private originalConsole;

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

@@ -0,0 +1,56 @@
+import { BaseInstrumentation } from '@grafana/faro-core';
+import type { CrashReport, CrashReportingOptions } from './types';
+/**
+ * Abstract base class for platform-specific crash reporting implementations.
+ *
+ * Defines the common contract that both Android and iOS implementations must follow.
+ * Handles the shared logic for retrieving crash reports from native modules and
+ * processing them, while delegating platform-specific parsing and validation to subclasses.
+ */
+export declare abstract class BaseCrashReportingInstrumentation extends BaseInstrumentation {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    protected readonly options: {
+        enabled: boolean;
+        releaseBundleFilename?: string;
+    };
+    constructor(options?: CrashReportingOptions);
+    initialize(): Promise<void>;
+    /**
+     * Platform-specific: Parse a crash trace string into structured stack frames.
+     */
+    protected abstract parseCrashTrace(trace: string): any | null;
+    /**
+     * Platform-specific: Resolve human-readable error message from crash data.
+     */
+    protected abstract resolveCrashErrorMessage(crash: CrashReport, parsedTrace: any | null): string;
+    /**
+     * Platform-specific: Determine if a crash report should be skipped.
+     */
+    protected abstract shouldSkipCrashReport(crash: CrashReport): boolean;
+    /**
+     * Platform-specific: Extract stack frames from parsed trace.
+     */
+    protected abstract getStackFrames(parsedTrace: any | null): any[];
+    /**
+     * Platform-specific: Build platform-specific context from parsed trace.
+     */
+    protected abstract buildPlatformContext(parsedTrace: any | null, context: Record<string, string>): void;
+    /**
+     * Platform-specific: Get warning message when trace parsing fails.
+     */
+    protected abstract getParseFailureWarning(): string;
+    /**
+     * Platform-specific: Get warning message when trace is unavailable.
+     */
+    protected abstract getTraceUnavailableWarning(): string;
+    private waitForSessionAttributes;
+    private getNativeModule;
+    private processCrashReports;
+    private sendCrashReport;
+    logDebug(message: string, ...args: any[]): void;
+    logInfo(message: string, ...args: any[]): void;
+    logWarn(message: string, ...args: any[]): void;
+    logError(message: string, ...args: any[]): void;
+    unpatch(): void;
+}

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

@@ -0,0 +1,12 @@
+import { BaseInstrumentation } from '@grafana/faro-core';
+import type { CrashReportingOptions } from './types';
+/**
+ * Crash reporting stub for platforms other than Android and iOS (e.g. web, macOS, Windows).
+ */
+export declare class NoOpCrashReportingInstrumentation extends BaseInstrumentation {
+    readonly name = "@grafana/faro-react-native:instrumentation-crash-noop";
+    readonly version = "2.7.0";
+    constructor(_options?: CrashReportingOptions);
+    initialize(): void;
+    unpatch(): void;
+}

package/dist/types/instrumentations/crashReporting/android/AndroidCrashReportingInstrumentation.d.ts

@@ -0,0 +1,26 @@
+import { BaseCrashReportingInstrumentation } from '../BaseCrashReportingInstrumentation';
+import type { CrashReport } from '../types';
+import { type ParsedAndroidCrashTrace } from './parseAndroidCrashTrace';
+/**
+ * Android Crash Reporting Instrumentation.
+ *
+ * Uses ApplicationExitInfo API (Android 11+ / API 30+) to retrieve crash reports
+ * from previous sessions. Captures:
+ * - CRASH: Java/Kotlin exception crashes
+ * - CRASH_NATIVE: Native (NDK) crashes
+ * - LOW_MEMORY: App killed due to low memory
+ * - EXCESSIVE_RESOURCE_USAGE: App killed due to excessive resource usage
+ *
+ * ANRs are reported separately by ANRInstrumentation, not via ApplicationExitInfo replay.
+ */
+export declare class AndroidCrashReportingInstrumentation extends BaseCrashReportingInstrumentation {
+    readonly name = "@grafana/faro-react-native:instrumentation-crash-android";
+    readonly version = "2.7.0";
+    protected parseCrashTrace(trace: string): ParsedAndroidCrashTrace | null;
+    protected resolveCrashErrorMessage(crash: CrashReport, parsedTrace: ParsedAndroidCrashTrace | null): string;
+    protected shouldSkipCrashReport(crash: CrashReport): boolean;
+    protected getStackFrames(parsedTrace: ParsedAndroidCrashTrace | null): any[];
+    protected buildPlatformContext(parsedTrace: ParsedAndroidCrashTrace | null, context: Record<string, string>): void;
+    protected getParseFailureWarning(): string;
+    protected getTraceUnavailableWarning(): string;
+}

package/dist/types/instrumentations/crashReporting/android/crashErrorMessage.d.ts

@@ -0,0 +1,23 @@
+import type { CrashReport } from '../types';
+import type { ParsedAndroidCrashTrace } from './parseAndroidCrashTrace';
+/**
+ * Human-readable exception value for ApplicationExitInfo crash reports.
+ * Priority: parsed trace message → exception class → description → generic fallback.
+ */
+export declare function resolveCrashErrorMessage(crash: CrashReport, parsedTrace: ParsedAndroidCrashTrace | null): string;
+/**
+ * Android ANR watchdog descriptions from ApplicationExitInfo (any app).
+ */
+export declare function isAnrTimeoutDescription(description: string | undefined): boolean;
+/**
+ * Skip duplicate ApplicationExitInfo rows that have no stack and no useful title,
+ * and ANR incidents mis-tagged as previous-session crashes.
+ */
+export declare function shouldSkipCrashReport(crash: CrashReport): boolean;
+/**
+ * Skip duplicate ApplicationExitInfo rows that have no stack and no useful title.
+ * These surface in the plugin as a second generic `crash` row for a single button press.
+ */
+export declare function shouldSkipLowSignalCrashReport(crash: CrashReport): boolean;
+/** Generic fallback when the trace carries no parseable message or type. */
+export declare function buildFallbackCrashMessage(crash: CrashReport): string;

package/dist/types/instrumentations/crashReporting/android/index.d.ts

@@ -0,0 +1,4 @@
+export { AndroidCrashReportingInstrumentation } from './AndroidCrashReportingInstrumentation';
+export { parseAndroidCrashTrace, normalizeJavaStackTraceForRetrace } from './parseAndroidCrashTrace';
+export type { ParsedAndroidCrashTrace, AndroidCrashStackFrame } from './parseAndroidCrashTrace';
+export { resolveCrashErrorMessage, shouldSkipCrashReport } from './crashErrorMessage';

package/dist/types/instrumentations/crashReporting/android/nativeTombstoneTrace.d.ts

@@ -0,0 +1,2 @@
+/** Detect Android tombstone backtrace lines used for NDK native retrace. */
+export declare function looksLikeNativeTombstoneTrace(trace: string | undefined): boolean;

package/dist/types/instrumentations/crashReporting/android/parseAndroidCrashTrace.d.ts

@@ -0,0 +1,45 @@
+import type { ExceptionStackFrame } from '@grafana/faro-core';
+/**
+ * Android ApplicationExitInfo traces use Java/Kotlin stack-trace formatting.
+ * Faro ingest expects structured frames with `module` (obfuscated class) so the
+ * collector can R8-retrace them — not the JS call stack from sendCrashReport().
+ *
+ * Fatal RN JS errors also embed a short Hermes/Metro stack before native frames
+ * (e.g. `anonymous@1:1390953`). Those lines are parsed as JS frames (no `module`)
+ * so the collector can source-map them to files like DebugScreen.tsx.
+ */
+export interface AndroidCrashStackFrame extends ExceptionStackFrame {
+    module: string;
+}
+export interface ParseAndroidCrashTraceOptions {
+    releaseBundleFilename?: string;
+}
+export interface NativeTombstoneStackFrame extends ExceptionStackFrame {
+    /** Unstripped .so basename (e.g. libappmodules.so) for NDK retrace on the collector. */
+    module: string;
+}
+export interface ParsedAndroidCrashTrace {
+    exceptionType?: string;
+    /** Human-readable message from the trace header (e.g. the JS error text). */
+    exceptionMessage?: string;
+    /** JS/Hermes frames from the embedded RN stack (source-map targets). */
+    jsFrames: ExceptionStackFrame[];
+    /** Native Java/Kotlin frames (Android R8 retrace targets). */
+    frames: AndroidCrashStackFrame[];
+    /** NDK tombstone #NN pc lines (server-side .so retrace targets). */
+    nativeFrames: NativeTombstoneStackFrame[];
+}
+/** Tombstone section headers and metadata must not become exception_type / nativeExceptionType. */
+export declare function isTombstoneSectionLabel(value: string): boolean;
+/** Reject version tokens (e.g. "18.2213") and other non-class header lines. */
+export declare function isPlausibleJavaExceptionIdentifier(value: string): boolean;
+/**
+ * Normalize raw Java thread stacks (e.g. ANRTracker) to Log.getStackTraceString shape
+ * so collector R8 retrace (mapping.RetraceText) can rewrite frame lines.
+ */
+export declare function normalizeJavaStackTraceForRetrace(trace: string): string;
+export declare function normalizeCrashTraceExceptionMessage(rawMessage: string | undefined): string | undefined;
+/**
+ * Parse a raw Android crash trace into structured stack frames for pushError().
+ */
+export declare function parseAndroidCrashTrace(trace: string, options?: ParseAndroidCrashTraceOptions): ParsedAndroidCrashTrace | null;

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

@@ -1,2 +1,25 @@
-export { CrashReportingInstrumentation } from './instrumentation';
-export type { CrashReport, CrashReportingOptions } from './types';
+import { AndroidCrashReportingInstrumentation } from './android';
+import { IosCrashReportingInstrumentation } from './ios';
+import { NoOpCrashReportingInstrumentation } from './NoOpCrashReportingInstrumentation';
+/**
+ * Platform-aware crash reporting instrumentation export.
+ *
+ * At module load time, determines the platform and exports the correct implementation:
+ * - Android: Uses ApplicationExitInfo API to retrieve crashes
+ * - iOS: Uses PLCrashReporter to retrieve crashes
+ * - Other: No-op stub (web, macOS, Windows, etc.)
+ *
+ * Usage:
+ * ```ts
+ * import { CrashReportingInstrumentation } from '@grafana/faro-react-native/instrumentation-crash';
+ *
+ * const faro = initializeFaro({
+ *   // ...
+ *   instrumentations: [
+ *     new CrashReportingInstrumentation(),
+ *   ],
+ * });
+ * ```
+ */
+export declare const CrashReportingInstrumentation: typeof AndroidCrashReportingInstrumentation | typeof IosCrashReportingInstrumentation | typeof NoOpCrashReportingInstrumentation;
+export type { CrashReportingOptions } from './types';

package/dist/types/instrumentations/crashReporting/ios/IosCrashReportingInstrumentation.d.ts

@@ -0,0 +1,28 @@
+import { BaseCrashReportingInstrumentation } from '../BaseCrashReportingInstrumentation';
+import type { CrashReport } from '../types';
+import { type ParsedIosCrashTrace } from './parseIosCrashTrace';
+/**
+ * iOS Crash Reporting Instrumentation.
+ *
+ * Uses PLCrashReporter to capture native crashes from previous sessions:
+ * - SIGSEGV: Segmentation fault / invalid memory access
+ * - SIGABRT: Abnormal termination (e.g., assertion failure, uncaught exception)
+ * - SIGBUS: Bus error / alignment/hardware error
+ * - SIGILL: Illegal instruction
+ * - SIGFPE: Floating point exception
+ * - SIGTRAP: Breakpoint/debugger trap
+ * - Mach exceptions (EXC_BAD_ACCESS, EXC_CRASH, etc.)
+ *
+ * Stack frames are symbolicated on the native side before being surfaced.
+ */
+export declare class IosCrashReportingInstrumentation extends BaseCrashReportingInstrumentation {
+    readonly name = "@grafana/faro-react-native:instrumentation-crash-ios";
+    readonly version = "2.7.0";
+    protected parseCrashTrace(trace: string): ParsedIosCrashTrace | null;
+    protected resolveCrashErrorMessage(crash: CrashReport, parsedTrace: ParsedIosCrashTrace | null): string;
+    protected shouldSkipCrashReport(crash: CrashReport): boolean;
+    protected getStackFrames(parsedTrace: ParsedIosCrashTrace | null): any[];
+    protected buildPlatformContext(parsedTrace: ParsedIosCrashTrace | null, context: Record<string, string>): void;
+    protected getParseFailureWarning(): string;
+    protected getTraceUnavailableWarning(): string;
+}

package/dist/types/instrumentations/crashReporting/ios/crashErrorMessage.d.ts

@@ -0,0 +1,14 @@
+import type { CrashReport } from '../types';
+import type { ParsedIosCrashTrace } from './parseIosCrashTrace';
+/**
+ * Human-readable exception value for iOS PLCrashReporter crash reports.
+ * Priority: exception reason → signal description → signal name → fallback.
+ */
+export declare function resolveCrashErrorMessage(crash: CrashReport, parsedTrace: ParsedIosCrashTrace | null): string;
+/**
+ * Skip crash reports that have no useful information.
+ * iOS crashes should always have either a trace or a signal.
+ */
+export declare function shouldSkipCrashReport(crash: CrashReport): boolean;
+/** Generic fallback when the trace carries no parseable signal or description. */
+export declare function buildFallbackCrashMessage(crash: CrashReport): string;

package/dist/types/instrumentations/crashReporting/ios/index.d.ts

@@ -0,0 +1,4 @@
+export { IosCrashReportingInstrumentation } from './IosCrashReportingInstrumentation';
+export { parseIosCrashTrace } from './parseIosCrashTrace';
+export type { ParsedIosCrashTrace, IosCrashStackFrame } from './parseIosCrashTrace';
+export { resolveCrashErrorMessage, shouldSkipCrashReport } from './crashErrorMessage';

package/dist/types/instrumentations/crashReporting/ios/parseIosCrashTrace.d.ts

@@ -0,0 +1,38 @@
+import type { ExceptionStackFrame } from '@grafana/faro-core';
+/**
+ * iOS PLCrashReporter stack frames include library name and instruction pointers.
+ * Format: "0  libsystem_kernel.dylib  0x00000001a2b3c000"
+ */
+export interface IosCrashStackFrame extends ExceptionStackFrame {
+    /** Library/module name (e.g., "MyApp", "UIKitCore") */
+    module: string;
+    /** Instruction pointer address (hex string) */
+    instructionPointer?: string;
+    /** Library base address (hex string) */
+    libraryBaseAddress?: string;
+}
+export interface ParseIosCrashTraceOptions {
+    releaseBundleFilename?: string;
+}
+export interface ParsedIosCrashTrace {
+    /** Signal name (e.g., "SIGSEGV", "SIGABRT") */
+    signalName?: string;
+    /** Human-readable signal description */
+    signalDescription?: string;
+    /** Exception name for uncaught exceptions (e.g., "NSInternalInconsistencyException") */
+    exceptionName?: string;
+    /** Exception reason/message for uncaught exceptions */
+    exceptionReason?: string;
+    /** iOS native frames (library + instruction pointer for symbolication) */
+    frames: IosCrashStackFrame[];
+}
+/**
+ * Parse a raw iOS crash trace from PLCrashReporter into structured stack frames.
+ *
+ * iOS crashes from PLCrashReporter come with formatted stack traces where each line
+ * contains: frame number, library name, and instruction pointer hex address.
+ *
+ * The collector will use the library name and instruction pointer for symbolication
+ * with dSYM files or Breakpad symbols.
+ */
+export declare function parseIosCrashTrace(trace: string, _options?: ParseIosCrashTraceOptions): ParsedIosCrashTrace | null;

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

@@ -1,61 +1,28 @@
 /**
- * Configuration options for Crash Reporting instrumentation.
- *
- * **Platform Support**:
- * - **Android**: Uses ApplicationExitInfo API (Android 11+ / API 30+)
- *   Captures: CRASH, CRASH_NATIVE, ANR, LOW_MEMORY, EXCESSIVE_RESOURCE_USAGE
- * - **iOS**: Uses PLCrashReporter (automatically included via podspec)
- *   Captures: Signal crashes (SIGSEGV, SIGABRT, etc.) and Mach exceptions
- */
-export interface CrashReportingOptions {
-    /**
-     * Whether to enable crash reporting.
-     * Default: true
-     */
-    enabled?: boolean;
-}
-/**
- * Crash report data from native module.
- *
- * Field names match Faro Flutter SDK for consistency across mobile platforms.
- * Both Android (ApplicationExitInfo) and iOS (PLCrashReporter) produce JSON
- * matching this interface.
+ * Crash report data structure returned from native module.
  */
 export interface CrashReport {
-    /**
-     * Reason for the crash (e.g., "CRASH", "CRASH_NATIVE", "ANR", "LOW_MEMORY")
-     */
-    reason: string;
-    /**
-     * Timestamp when the crash occurred (milliseconds since epoch)
-     */
-    timestamp: number;
-    /**
-     * Exit status code
-     */
-    status?: number;
-    /**
-     * Description of the crash
-     */
+    trace?: string;
+    signal?: string;
+    timestamp?: number;
     description?: string;
-    /**
-     * Process importance level
-     */
-    importance?: number;
-    /**
-     * Process ID
-     */
-    pid?: number;
-    /**
-     * Process name
-     */
     processName?: string;
+    pid?: number;
+    importance?: number;
+    reason?: string;
+    status?: number;
+}
+/**
+ * Configuration options for crash reporting instrumentation.
+ */
+export interface CrashReportingOptions {
     /**
-     * Stack trace (if available)
+     * Enable or disable crash reporting. Defaults to true.
      */
-    trace?: string;
+    enabled?: boolean;
     /**
-     * Signal name (for iOS crashes)
+     * Optional release bundle filename hint for R8 retracing.
+     * e.g., "index.android.bundle"
      */
-    signal?: string;
+    releaseBundleFilename?: string;
 }

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.3.1";
+    readonly version = "2.7.0";
     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.3.1";
+    readonly version = "2.7.0";
     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.3.1";
+    readonly version = "2.7.0";
     private options;
     private intervalId;
     constructor(options?: PerformanceInstrumentationOptions);

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

@@ -5,7 +5,7 @@ import { BaseInstrumentation } from '@grafana/faro-core';
  */
 export declare class SessionInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native:instrumentation-session";
-    readonly version = "2.3.1";
+    readonly version = "2.7.0";
     private notifiedSession;
     private sessionManagerInstance;
     private getDefaultSessionDeviceAttributes;

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

@@ -0,0 +1 @@
+export declare function getInstallationId(): Promise<string | undefined>;

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

@@ -1,3 +1,4 @@
+import type { Meta } from '@grafana/faro-core';
 /**
  * Session attributes for React Native
  * These attributes are automatically included with every telemetry event
@@ -18,17 +19,17 @@ export interface SessionAttributes {
     device_os_version?: string;
     /** Detailed OS info (e.g., "iOS 17.0" or "Android 15 (SDK 35)") */
     device_os_detail?: string;
-    /** Device manufacturer (e.g., "apple", "samsung") */
+    /** Device manufacturer (e.g., "apple", "samsung", "Google") */
     device_manufacturer?: string;
-    /** Raw model identifier (e.g., "iPhone16,1", "SM-A155F") */
+    /** Device model in flat session attributes (e.g., "iPhone 15 Pro", "SM-A155F") */
     device_model?: string;
     /** Human-readable model name (e.g., "iPhone 15 Pro") */
     device_model_name?: string;
-    /** Device brand (e.g., "iPhone", "samsung") */
+    /** Device brand in flat session attributes (e.g., "Apple", "samsung") */
     device_brand?: string;
     /** Whether device is physical or emulator ("true" or "false") */
     device_is_physical?: string;
-    /** Unique device ID (UUID) */
+    /** Temporary flat attribute mirroring `app.installationId` during migration. */
     device_id?: string;
     /** Device type ("mobile" or "tablet") */
     device_type?: string;
@@ -45,6 +46,10 @@ export interface SessionAttributes {
     /** Mobile carrier name (e.g., "Verizon") - empty if unavailable */
     device_carrier?: string;
 }
+export interface PreloadedMobileMeta {
+    sessionAttributes: SessionAttributes;
+    meta: Pick<Meta, 'app' | 'device' | 'os'>;
+}
 /**
  * Session attributes without device props when async collection or DeviceInfo is unavailable.
  * No synchronous DeviceInfo reads — use {@link getSessionAttributes} or the package async `initializeFaro`.
@@ -67,6 +72,10 @@ export declare function minimalSessionDeviceAttributes(): SessionAttributes;
  * - device_carrier
  */
 export declare function getSessionAttributes(): Promise<SessionAttributes>;
+/**
+ * Get structured mobile meta plus flat session attributes for async `initializeFaro`.
+ */
+export declare function loadMobileMetaForInit(): Promise<PreloadedMobileMeta>;
 /**
  * Await full async session device attributes (battery, carrier, etc.), then fall back to
  * {@link minimalSessionDeviceAttributes} if anything throws. Used by async `initializeFaro`.

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.3.1";
+    readonly version = "2.7.0";
     /** 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.3.1";
+    readonly version = "2.7.0";
     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.3.1";
+    readonly version = "2.7.0";
     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.3.1";
+    readonly version = "2.7.0";
     private originalOpen?;
     private originalSend?;
     private ignoredUrls;

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

@@ -0,0 +1,16 @@
+/** Metro / webpack preamble bundle id for JS source maps (`__faroBundleId_<appName>`). */
+export declare function getMetroInjectedBundleId(appName: string | undefined): string | undefined;
+/**
+ * Encodes the Android/iOS build identity used as `meta.app.bundleId` for
+ * server-side symbol retrace. Must match the symbols upload bundle id
+ * (`{applicationId}@{versionCode}@{versionName}`).
+ */
+export declare function formatSymbolsBundleId(applicationId: string, versionCode: string, versionName: string): string;
+/**
+ * Reads the installed build's identity from `react-native-device-info` and
+ * returns the encoded bundle id when all parts are available.
+ *
+ * Values must match what the symbol uploader (Gradle plugin / faro-cli) sends
+ * for the same build so the collector can locate the mapping for retrace.
+ */
+export declare function loadAppSymbolsBundleIdForInit(): Promise<string | undefined>;

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

@@ -5,6 +5,6 @@
 import { BaseInstrumentation } from '@grafana/faro-core';
 export declare class TracingInstrumentation extends BaseInstrumentation {
     readonly name = "@grafana/faro-react-native-tracing";
-    readonly version = "2.3.1";
+    readonly version = "2.7.0";
     initialize(): void;
 }