@grafana/faro-react-native 1.3.0 → 1.4.0

package/ios/FaroReactNativeModule.mm

@@ -2,10 +2,81 @@
 #import <React/RCTBridgeModule.h>
 #import "FaroReactNative-Swift.h"
 
+static NSLock *FaroSessionPersistenceLock(void)
+{
+  static NSLock *lock;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    lock = [[NSLock alloc] init];
+  });
+  return lock;
+}
+
+// Weak ownership also clears the claim if teardown skips `invalidate`.
+static __weak FaroReactNativeModule *FaroSessionPersistenceOwner;
+
+@interface FaroReactNativeModule ()
+- (BOOL)claimSessionPersistenceOwnership;
+- (BOOL)releaseSessionPersistenceOwnership;
+@end
+
 @implementation FaroReactNativeModule
 
 RCT_EXPORT_MODULE(FaroReactNativeModule)
 
+/// Stable process identity used to isolate persisted session chains.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getSessionProcessIdentifier)
+{
+  return [FaroReactNative getSessionProcessIdentifier];
+}
+
+/// Whether this runtime belongs to the host application's main process.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(isMainSessionProcess)
+{
+  return @([FaroReactNative isMainSessionProcess]);
+}
+
+/// Allows only one React Native runtime in a process to persist sessions.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(claimSessionPersistence)
+{
+  return @([self claimSessionPersistenceOwnership]);
+}
+
+/// Releases persistence only when this native module instance owns it.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(releaseSessionPersistence)
+{
+  return @([self releaseSessionPersistenceOwnership]);
+}
+
+- (BOOL)claimSessionPersistenceOwnership
+{
+  NSLock *lock = FaroSessionPersistenceLock();
+  [lock lock];
+  BOOL claimed = FaroSessionPersistenceOwner == nil || FaroSessionPersistenceOwner == self;
+  if (claimed) {
+    FaroSessionPersistenceOwner = self;
+  }
+  [lock unlock];
+  return claimed;
+}
+
+- (BOOL)releaseSessionPersistenceOwnership
+{
+  NSLock *lock = FaroSessionPersistenceLock();
+  [lock lock];
+  BOOL released = FaroSessionPersistenceOwner == self;
+  if (released) {
+    FaroSessionPersistenceOwner = nil;
+  }
+  [lock unlock];
+  return released;
+}
+
+- (void)invalidate
+{
+  [self releaseSessionPersistenceOwnership];
+}
+
 /// Synchronous method for immediate access from JavaScript
 /// Returns app startup duration in milliseconds from process start to current time
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getAppStartDuration)
@@ -34,9 +105,9 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getCpuUsage)
 /// @param config Dictionary with targetFps, frozenFrameThresholdMs, normalizedRefreshRate
 RCT_EXPORT_METHOD(startFrameMonitoring:(NSDictionary *)config)
 {
-  double targetFps = [[config objectForKey:@"targetFps"] doubleValue] ?: 60.0;
-  double frozenFrameThresholdMs = [[config objectForKey:@"frozenFrameThresholdMs"] doubleValue] ?: 100.0;
-  double normalizedRefreshRate = [[config objectForKey:@"normalizedRefreshRate"] doubleValue] ?: 60.0;
+  double targetFps = [[config objectForKey:@"targetFps"] doubleValue] ?: RefreshRateVitals.defaultTargetFps;
+  double frozenFrameThresholdMs = [[config objectForKey:@"frozenFrameThresholdMs"] doubleValue] ?: RefreshRateVitals.defaultFrozenFrameThresholdMs;
+  double normalizedRefreshRate = [[config objectForKey:@"normalizedRefreshRate"] doubleValue] ?: RefreshRateVitals.defaultNormalizedRefreshRate;
   
   dispatch_async(dispatch_get_main_queue(), ^{
     [[RefreshRateVitals shared] configureWithTargetFps:targetFps
@@ -79,12 +150,13 @@ RCT_EXPORT_METHOD(getFrameMetrics:(RCTPromiseResolveBlock)resolve
 {
   dispatch_async(dispatch_get_main_queue(), ^{
     RefreshRateVitals *vitals = [RefreshRateVitals shared];
-    
+    NSDictionary *frozenMetrics = [vitals getAndResetFrozenMetrics];
+
     NSDictionary *metrics = @{
       @"refreshRate": @([vitals getRefreshRate]),
       @"slowFrames": @([vitals getAndResetSlowFrames]),
-      @"frozenFrames": @([vitals getAndResetFrozenFrames]),
-      @"frozenDurationMs": @([vitals getAndResetFrozenDuration])
+      @"frozenFrames": frozenMetrics[@"count"],
+      @"frozenDurationMs": frozenMetrics[@"durationMs"]
     };
     
     resolve(metrics);
@@ -121,4 +193,47 @@ RCT_EXPORT_METHOD(getCrashReport:(RCTPromiseResolveBlock)resolve
   }
 }
 
+/// Store the active session synchronously so it is available if the process crashes.
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(recordCrashSessionContext:(NSDictionary *)sessionContext)
+{
+  return @([FaroReactNative recordCrashSessionContext:sessionContext]);
+}
+
+/// Get pending crash reports without deleting them.
+RCT_EXPORT_METHOD(getPendingCrashReports:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  NSArray<NSString *> *crashReports = [FaroReactNative getPendingCrashReports];
+  if (crashReports != nil && crashReports.count > 0) {
+    resolve(crashReports);
+  } else {
+    resolve([NSNull null]);
+  }
+}
+
+/// Delete only crash reports that JavaScript has finished handling.
+RCT_EXPORT_METHOD(acknowledgeCrashReports:(NSArray *)reportIds
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  NSMutableArray<NSString *> *sanitizedReportIds = [NSMutableArray array];
+  for (id reportId in reportIds) {
+    if (![reportId isKindOfClass:[NSString class]]) {
+      continue;
+    }
+
+    NSString *trimmedReportId = [(NSString *)reportId stringByTrimmingCharactersInSet:
+                                 [NSCharacterSet whitespaceAndNewlineCharacterSet]];
+    if (trimmedReportId.length > 0) {
+      [sanitizedReportIds addObject:trimmedReportId];
+    }
+  }
+
+  if ([FaroReactNative acknowledgeCrashReports:sanitizedReportIds]) {
+    resolve([NSNull null]);
+  } else {
+    reject(@"E_CRASH_ACK_FAILED", @"Failed to acknowledge recovered crash report", nil);
+  }
+}
+
 @end

package/ios/RefreshRateVitals.swift

@@ -9,18 +9,22 @@ import UIKit
 /// Uses CADisplayLink to measure actual frame durations and calculate FPS.
 /// Handles ProMotion displays (120Hz) by normalizing to 60 FPS baseline.
 @objc public class RefreshRateVitals: NSObject {
+    @objc public static let defaultTargetFps: Double = 60.0
+    @objc public static let defaultFrozenFrameThresholdMs: Double = 700.0
+    @objc public static let defaultNormalizedRefreshRate: Double = 60.0
+
     private var displayLink: CADisplayLink?
     private var lastFrameTimestamp: CFTimeInterval?
     private var nextFrameDuration: CFTimeInterval?
     
     /// Normalized refresh rate for backend compatibility (default 60 FPS)
-    private var normalizedRefreshRate: Double = 60.0
+    private var normalizedRefreshRate: Double = RefreshRateVitals.defaultNormalizedRefreshRate
     
     /// Target FPS for slow frame detection
-    private var targetFps: Double = 60.0
+    private var targetFps: Double = RefreshRateVitals.defaultTargetFps
     
     /// Threshold in seconds for frozen frame detection
-    private var frozenFrameThreshold: Double = 0.100
+    private var frozenFrameThreshold: Double = RefreshRateVitals.defaultFrozenFrameThresholdMs / 1000.0
     
     /// Last calculated refresh rate
     @objc public private(set) var lastRefreshRate: Double = 0.0
@@ -28,11 +32,11 @@ import UIKit
     /// Count of slow frame events since last reset (not individual frames)
     @objc public private(set) var slowFrameEventCount: Int = 0
     
-    /// Count of frozen frames since last reset
-    @objc public private(set) var frozenFrameCount: Int = 0
-    
-    /// Total duration of frozen frames in milliseconds
-    @objc public private(set) var frozenFrameDurationMs: Double = 0
+    /// Lock for frozen frame count and duration (writer and poll snapshot).
+    private let frozenMetricsLock = NSLock()
+
+    private var frozenFrameCount: Int = 0
+    private var frozenFrameDurationMs: Double = 0
     
     /// Whether monitoring is active
     @objc public private(set) var isMonitoring: Bool = false
@@ -60,7 +64,7 @@ import UIKit
     /// Configure monitoring parameters
     /// - Parameters:
     ///   - targetFps: Target FPS for slow frame detection (default 60)
-    ///   - frozenFrameThresholdMs: Threshold in ms for frozen frames (default 100)
+    ///   - frozenFrameThresholdMs: Threshold in ms for frozen frames (default 700)
     ///   - normalizedRefreshRate: Normalized rate for ProMotion displays (default 60)
     @objc public func configure(
         targetFps: Double,
@@ -82,8 +86,10 @@ import UIKit
         
         // Reset counters
         slowFrameEventCount = 0
+        frozenMetricsLock.lock()
         frozenFrameCount = 0
         frozenFrameDurationMs = 0
+        frozenMetricsLock.unlock()
         lastFrameTimestamp = nil
         nextFrameDuration = nil
         inSlowFrameEvent = false
@@ -111,18 +117,25 @@ import UIKit
         return count
     }
     
-    /// Get and reset frozen frame count
-    @objc public func getAndResetFrozenFrames() -> Int {
+    /// Get and reset frozen frame count and duration atomically.
+    @objc public func getAndResetFrozenMetrics() -> [String: NSNumber] {
+        frozenMetricsLock.lock()
         let count = frozenFrameCount
-        frozenFrameCount = 0
-        return count
-    }
-    
-    /// Get and reset frozen frame duration in milliseconds
-    @objc public func getAndResetFrozenDuration() -> Double {
         let duration = frozenFrameDurationMs
+        frozenFrameCount = 0
         frozenFrameDurationMs = 0
-        return duration
+        frozenMetricsLock.unlock()
+        return [
+            "count": NSNumber(value: count),
+            "durationMs": NSNumber(value: duration),
+        ]
+    }
+
+    private func recordFrozenFrame(durationMs: Double) {
+        frozenMetricsLock.lock()
+        frozenFrameCount += 1
+        frozenFrameDurationMs += durationMs
+        frozenMetricsLock.unlock()
     }
     
     // MARK: - Private Methods
@@ -132,13 +145,7 @@ import UIKit
         if let lastTimestamp = lastFrameTimestamp {
             let frameDuration = link.timestamp - lastTimestamp
             if frameDuration > frozenFrameThreshold {
-                frozenFrameCount += 1
-                
-                // Track duration in milliseconds
-                let durationMs = frameDuration * 1000
-                frozenFrameDurationMs += durationMs
-                
-                NSLog("[Faro] Frozen frame detected! Duration: %.0fms (threshold: %.0fms)", durationMs, frozenFrameThreshold * 1000)
+                recordFrozenFrame(durationMs: frameDuration * 1000)
             }
         }
         
@@ -150,12 +157,7 @@ import UIKit
         // A slow frame "event" is a period of consecutive frames below target FPS
         // This groups consecutive slow frames to report meaningful jank, not microsecond variations
         let isSlow = fps < targetFps
-        
-        // 🔍 TEMP DEBUG LOG - Remove after analysis
-        if isSlow {
-            NSLog("[Faro DEBUG IOS] 🐌 Slow frame detected: %.1f FPS (target: %.1f)", fps, targetFps)
-        }
-        
+
         if isSlow {
             if !inSlowFrameEvent {
                 // Start new slow frame event
@@ -166,17 +168,11 @@ import UIKit
             // Frame is good - check if we should end the current slow frame event
             if inSlowFrameEvent {
                 let eventDuration = link.timestamp - slowFrameEventStartTime
-                let eventDurationMs = eventDuration * 1000
-                
+
                 // Only count as a slow frame event if it lasted long enough to be user-perceptible
                 // This filters out single-frame dips that don't affect user experience
                 if eventDuration >= slowFrameEventMinDuration {
                     slowFrameEventCount += 1
-                    // 🔍 TEMP DEBUG LOG - Remove after analysis
-                    NSLog("[Faro DEBUG IOS] ✅ COUNTED as event (%.0fms)! Total events now: %d", eventDurationMs, slowFrameEventCount)
-                } else {
-                    // 🔍 TEMP DEBUG LOG - Remove after analysis
-                    NSLog("[Faro DEBUG IOS] ❌ NOT counted (%.0fms is too short). Total events still: %d", eventDurationMs, slowFrameEventCount)
                 }
                 
                 inSlowFrameEvent = false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/faro-react-native",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Faro instrumentations, metas, transports for React Native.",
   "keywords": [
     "observability",
@@ -56,7 +56,7 @@
     "version": "node ./scripts/sync-faro-rn-package-meta.mjs && git add src/generated/faroRNPackageMeta.ts"
   },
   "dependencies": {
-    "@grafana/faro-core": "^2.7.0",
+    "@grafana/faro-core": "^2.8.2",
     "@react-native-async-storage/async-storage": "^1.21.0",
     "react-native-device-info": "^11.1.0"
   },
@@ -76,13 +76,15 @@
   },
   "devDependencies": {
     "@types/node": "24.12.4",
-    "@types/react": "19.2.15",
+    "@types/react": "19.2.18",
     "@types/react-native": "0.73.0",
-    "react-native-mmkv": "4.3.1",
-    "react-native-nitro-modules": "0.35.6"
+    "@types/react-test-renderer": "19.1.0",
+    "react-native-mmkv": "4.3.2",
+    "react-native-nitro-modules": "0.36.1",
+    "react-test-renderer": "19.2.3"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7cd0482f59a7eefad5a812e468d259e17ad39ed6"
+  "gitHead": "38d87a3474585e1177c38d2e9acd04860a4236e6"
 }

package/src/config/getRNInstrumentations.ts

@@ -26,8 +26,7 @@ function toRegExpArray(patterns: Patterns): RegExp[] {
 /**
  * Returns the default set of instrumentations for React Native.
  *
- * Reads all options from the Faro config (single source of truth).
- * Property names are aligned with Flutter SDK FaroConfig:
+ * Reads all options from the Faro config (single source of truth):
  * - cpuUsageVitals, memoryUsageVitals, anrTracking, refreshRateVitals
  * - enableCrashReporting, enableErrorReporting
  * - fetchVitalsInterval, ignoreUrls
@@ -47,7 +46,6 @@ function toRegExpArray(patterns: Patterns): RegExp[] {
  * ```
  */
 export function getRNInstrumentations(config: Partial<ReactNativeConfig> = {}): Instrumentation[] {
-  // Aligned with Flutter SDK FaroConfig defaults
   const {
     // Error & crash tracking
     enableErrorReporting = true,
@@ -77,7 +75,7 @@ export function getRNInstrumentations(config: Partial<ReactNativeConfig> = {}):
 
   const instrumentations: Instrumentation[] = [];
 
-  // Error reporting (Flutter: enableFlutterErrorReporting)
+  // Error reporting
   if (enableErrorReporting) {
     instrumentations.push(
       new ErrorsInstrumentation({
@@ -86,18 +84,18 @@ export function getRNInstrumentations(config: Partial<ReactNativeConfig> = {}):
     );
   }
 
-  // Console capture - not in Flutter SDK, RN-specific
+  // Console capture
   if (enableConsoleCapture) {
     instrumentations.push(new ConsoleInstrumentation());
   }
 
-  // Sessions - always enabled in Flutter, same here
+  // Sessions
   instrumentations.push(new SessionInstrumentation());
 
-  // Views - always enabled in Flutter, same here
+  // Views
   instrumentations.push(new ViewInstrumentation());
 
-  // App state - always enabled in Flutter, same here
+  // App state
   instrumentations.push(new AppStateInstrumentation());
 
   // User actions - enabled by default, opt-out via enableUserActions

package/src/config/makeRNConfig.test.ts

@@ -108,6 +108,12 @@ describe('makeRNConfig', () => {
     });
   });
 
+  it('enables minimal session persistence by default', () => {
+    const cfg = makeRNConfig({ ...base });
+
+    expect(cfg.sessionTracking?.persistent).toBe(true);
+  });
+
   it('uses getRNInstrumentations for the instrumentation set from flags', () => {
     const minimal = makeRNConfig({
       ...base,

package/src/config/sampling.ts

@@ -7,9 +7,6 @@ import type { Meta } from '@grafana/faro-core';
  * allowing sampling decisions based on session attributes, user info, app
  * environment, and other metadata.
  *
- * This aligns with the Faro Flutter SDK's `SamplingContext` which provides
- * `meta` to the sampler.
- *
  * @example
  * ```ts
  * sampling: SamplingFunction((context) => {

package/src/config/types.ts

@@ -8,11 +8,13 @@ import type { Sampling } from './sampling';
 
 /**
  * React Native session tracking config.
- * Extends Config['sessionTracking'] with sampling (Flutter-style) and RN-specific props.
+ * Extends Config['sessionTracking'] with sampling 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.
+ * Persistence defaults to true and stores a minimal, versioned record with
+ * [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) (synchronous).
+ * Add `react-native-mmkv` to your app and rebuild native projects, or set
+ * `persistent` to false to use in-memory sessions.
  */
 export type ReactNativeSessionTrackingConfig = Omit<
   NonNullable<Config['sessionTracking']>,

package/src/dataCollection/DataCollectionPolicy.ts

@@ -13,8 +13,7 @@ const DEFAULT_STORAGE_KEY = 'faro_enable_data_collection';
  * Controls whether telemetry data is collected and sent.
  * The setting is persisted to AsyncStorage so it survives app restarts.
  *
- * Implementation follows Flutter SDK's DataCollectionPolicy pattern:
- * - Uses AsyncStorage for persistence (matching Flutter's SharedPreferences)
+ * Uses AsyncStorage for persisting data collection policy state.
  * - Provides enable/disable methods
  * - Initializes from persisted value or default
  *

package/src/generated/faroRNPackageMeta.ts

@@ -2,4 +2,4 @@
  * 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.3.0' as const;
+export const FARO_REACT_NATIVE_NPM_VERSION = '1.4.0' as const;

package/src/index.ts

@@ -8,7 +8,7 @@ export { faro } from '@grafana/faro-core';
 // Export types
 export type { EnableTransportsConfig, ReactNativeConfig, ReactNativeSessionTrackingConfig } from './config/types';
 
-// Export sampling (Flutter-style interface)
+// Export sampling
 export { SamplingFunction, SamplingRate, type Sampling, type SamplingContext } from './config/sampling';
 
 // Export instrumentation helpers
@@ -18,7 +18,12 @@ export { getRNInstrumentations } from './config/getRNInstrumentations';
 export { ErrorMechanism, ErrorsInstrumentation } from './instrumentations/errors';
 export type { ErrorMechanismType, ErrorsInstrumentationOptions } from './instrumentations/errors';
 export { ConsoleInstrumentation } from './instrumentations/console';
-export { SessionInstrumentation } from './instrumentations/session';
+export { startNewSession, SessionInstrumentation } from './instrumentations/session';
+export {
+  FaroSessionActivityBoundary,
+  type FaroSessionActivityBoundaryProps,
+} from './instrumentations/session/FaroSessionActivityBoundary';
+export { notifySessionActivity } from './instrumentations/session/directSessionActivity';
 export {
   getSessionAttributes,
   loadMobileMetaForInit,
@@ -70,6 +75,7 @@ export { getSdkMeta } from './metas/sdk';
 
 // Export transports
 export { FetchTransport } from './transports/fetch';
+export type { FetchTransportSendOutcome, FetchTransportSendResult } from './transports/fetch';
 export { ConsoleTransport } from './transports/console';
 export type { ConsoleTransportOptions } from './transports/console';
 export { OfflineTransport } from './transports/offline';

package/src/instrumentations/anr/instrumentation.ts

@@ -73,7 +73,14 @@ export class ANRInstrumentation extends BaseInstrumentation {
     this.startNativeTracking(nativeModule);
 
     const emitter = new NativeEventEmitter(nativeModule);
-    this.anrEventSubscription = emitter.addListener('onANRDetected', (anrJson: string) => {
+    this.anrEventSubscription = emitter.addListener('onANRDetected', (...args: readonly Object[]) => {
+      const [anrJson] = args;
+
+      if (typeof anrJson !== 'string') {
+        this.logWarn('Ignoring onANRDetected event without a string payload');
+        return;
+      }
+
       void this.handleLiveAnrEvent(nativeModule, anrJson);
     });
 

package/src/instrumentations/appState/index.ts

@@ -2,9 +2,16 @@ import { AppState, type AppStateStatus } from 'react-native';
 
 import { BaseInstrumentation, dateNow, VERSION } from '@grafana/faro-core';
 
-// Event name aligned with Faro Flutter SDK (app_lifecycle_changed)
 export const EVENT_APP_STATE_CHANGED = 'app_lifecycle_changed';
 
+const APP_STATE_STATUSES = ['inactive', 'background', 'active', 'extension', 'unknown'] as const;
+
+// RN types AppState.currentState as `null | undefined | string`: it stays null
+// until the initial value is set, so narrow it instead of trusting the shape.
+function isAppStateStatus(value: unknown): value is AppStateStatus {
+  return typeof value === 'string' && (APP_STATE_STATUSES as readonly string[]).includes(value);
+}
+
 /**
  * AppState instrumentation for React Native
  * Tracks app foreground/background/inactive state changes
@@ -22,7 +29,8 @@ export class AppStateInstrumentation extends BaseInstrumentation {
 
   initialize(): void {
     // Get initial app state
-    this.currentState = AppState.currentState;
+    const initialState = AppState.currentState;
+    this.currentState = isAppStateStatus(initialState) ? initialState : undefined;
     this.stateStartTime = dateNow();
 
     this.logInfo('AppState instrumentation initialized', {

package/src/instrumentations/crashReporting/BaseCrashReportingInstrumentation.ts

@@ -1,10 +1,17 @@
 import { NativeModules } from 'react-native';
 
 import { BaseInstrumentation } from '@grafana/faro-core';
+import type { ExceptionStackFrame } from '@grafana/faro-core';
 
 import { looksLikeNativeTombstoneTrace } from './android/nativeTombstoneTrace';
 import type { CrashReport, CrashReportingOptions } from './types';
 
+interface CrashReportDetails {
+  context: Record<string, string>;
+  errorMessage: string;
+  stackFrames: ExceptionStackFrame[];
+}
+
 /**
  * Abstract base class for platform-specific crash reporting implementations.
  *
@@ -39,6 +46,7 @@ export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentat
     }
 
     this.logDebug('Initializing crash reporting instrumentation');
+    await this.prepareCrashReporting(nativeModule);
 
     // Wait for session attributes before sending crash reports
     await this.waitForSessionAttributes();
@@ -82,7 +90,11 @@ export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentat
    */
   protected abstract getTraceUnavailableWarning(): string;
 
-  private async waitForSessionAttributes(maxWaitMs = 10000): Promise<void> {
+  protected prepareCrashReporting(_nativeModule: typeof NativeModules.FaroReactNativeModule): void | Promise<void> {
+    // Optional platform-specific setup.
+  }
+
+  protected async waitForSessionAttributes(maxWaitMs = 10000): Promise<void> {
     const startTime = Date.now();
     const pollInterval = 200;
     let checkCount = 0;
@@ -134,7 +146,7 @@ export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentat
     );
   }
 
-  private getNativeModule(): typeof NativeModules.FaroReactNativeModule | null {
+  protected getNativeModule(): typeof NativeModules.FaroReactNativeModule | null {
     const { FaroReactNativeModule } = NativeModules;
 
     if (!FaroReactNativeModule) {
@@ -144,7 +156,7 @@ export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentat
     return FaroReactNativeModule;
   }
 
-  private async processCrashReports(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
+  protected async processCrashReports(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
     try {
       if (typeof nativeModule.getCrashReport !== 'function') {
         this.logDebug('getCrashReport method not available');
@@ -201,15 +213,11 @@ export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentat
     }
   }
 
-  private sendCrashReport(crash: CrashReport): void {
+  protected buildCrashReportDetails(crash: CrashReport): CrashReportDetails {
     // Platform-specific parsing
     const parsedTrace = crash.trace ? this.parseCrashTrace(crash.trace) : null;
     const errorMessage = this.resolveCrashErrorMessage(crash, parsedTrace).trim() || 'Application crash';
 
-    // Use a message-only Error so pushError does not capture the JS reporter stack
-    const error = new Error(errorMessage);
-    error.stack = undefined;
-
     // Build context from crash data
     const context: Record<string, string> = {
       mechanism: 'crash',
@@ -258,6 +266,18 @@ export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentat
       );
     }
 
+    return {
+      context,
+      errorMessage,
+      stackFrames,
+    };
+  }
+
+  protected sendCrashReport(crash: CrashReport): void {
+    const { context, errorMessage, stackFrames } = this.buildCrashReportDetails(crash);
+    const error = new Error(errorMessage);
+    error.stack = undefined;
+
     this.api.pushError(error, {
       stackFrames,
       context,