@grafana/faro-react-native 1.3.1 → 1.4.0

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

@@ -3,7 +3,7 @@ import type { CachedPayload, OfflineCache } from './types';
  * File-based offline cache implementation using AsyncStorage.
  *
  * Stores cached telemetry payloads as JSONL (one JSON object per line)
- * following the Flutter SDK's offline transport pattern.
+ * Persistent offline telemetry cache backed by AsyncStorage.
  *
  * Uses a mutex pattern for thread-safe file access.
  */
@@ -22,7 +22,7 @@ export declare class AsyncStorageOfflineCache implements OfflineCache {
     getCount(): Promise<number>;
     /**
      * Execute an operation with a mutex lock to ensure thread-safe access.
-     * Follows Flutter SDK's Completer-based lock pattern.
+     * Async lock to serialize cache read/write operations.
      */
     private withLock;
     private readAllInternal;

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

@@ -8,8 +8,7 @@ import type { OfflineTransportOptions } from './types';
  * When the device is offline, telemetry is cached to AsyncStorage.
  * When connectivity is restored, cached telemetry is replayed through the wrapped transports.
  *
- * Implementation follows Flutter SDK's OfflineTransport pattern:
- * - Uses AsyncStorage for persistent caching (matching Flutter's SharedPreferences)
+ * Uses AsyncStorage for persistent offline telemetry caching.
  * - Respects maxCacheDuration to skip expired entries
  * - Uses mutex pattern for thread-safe cache access
  * - Excludes itself when replaying to prevent infinite loops
@@ -72,12 +71,12 @@ export declare class OfflineTransport extends BaseTransport {
     dispose(): void;
     /**
      * Replay cached payloads through other transports.
-     * Follows Flutter SDK's _readFromFile pattern.
+     * Reads cached telemetry from AsyncStorage.
      */
     private replayCachedPayloads;
     /**
      * Send items to all other registered transports.
-     * Follows Flutter SDK's _sendCachedData pattern.
+     * Sends cached telemetry when connectivity is restored.
      */
     private sendToOtherTransports;
 }

package/dist/types/userPersistence/UserPersistence.d.ts

@@ -6,8 +6,7 @@ import type { UserPersistence, UserPersistenceOptions } from './types';
  * Stores user information persistently so it can be restored on app restart.
  * This ensures early telemetry events include user identification.
  *
- * Implementation follows Flutter SDK's UserPersistence pattern:
- * - Uses AsyncStorage for persistence (matching Flutter's SharedPreferences)
+ * Uses AsyncStorage for persistent user data across app sessions.
  * - Stores user as JSON
  * - Handles null/cleared users
  *

package/ios/FaroCrashReporter.swift

@@ -21,6 +21,17 @@ public class FaroCrashReporter: NSObject {
 
     private static var crashReporter: PLCrashReporter?
     private static var isEnabled = false
+    private static let stateLock = NSLock()
+    // activatedAt keeps the persisted context aligned with Android. iOS does not
+    // use it to match a pending PLCrashReporter report.
+    private static let sessionContextKeys = [
+        "sessionId",
+        "activatedAt",
+        "isSampled",
+        "appVersion",
+        "appRelease",
+        "appBundleId"
+    ]
 
     /// Signal descriptions for human-readable crash messages.
     private static let signalDescriptions: [String: String] = [
@@ -50,6 +61,12 @@ public class FaroCrashReporter: NSObject {
     ///
     /// - Returns: true if successfully enabled, false otherwise
     @objc public static func enable() -> Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return enableLocked()
+    }
+
+    private static func enableLocked() -> Bool {
         guard !isEnabled else {
             return true
         }
@@ -90,53 +107,145 @@ public class FaroCrashReporter: NSObject {
         }
     }
 
-    /// Gets crash reports from previous sessions as JSON strings.
+    /// Records the active Faro session in PLCrashReporter's crash-safe custom data.
     ///
-    /// Returns an array of JSON strings, each representing a crash report.
-    /// The JSON format matches the Android implementation for consistency.
-    /// After calling this method, pending crash reports are purged.
+    /// PLCrashReporter copies this data into the report at crash time, allowing a
+    /// recovered crash to retain its original session after the app restarts.
+    /// Keep this payload minimal because it is embedded in every crash report.
+    ///
+    /// - Parameter sessionContext: Sanitized session and app fields from JavaScript
+    /// - Returns: true when the context was stored, false when it was invalid
+    @objc public static func recordSessionContext(_ sessionContext: [String: Any]) -> Bool {
+        let sanitizedContext = sanitizeSessionContext(sessionContext)
+        guard sanitizedContext["sessionId"] != nil,
+              JSONSerialization.isValidJSONObject(sanitizedContext) else {
+            return false
+        }
+
+        do {
+            let data = try JSONSerialization.data(withJSONObject: sanitizedContext)
+            stateLock.lock()
+            defer { stateLock.unlock() }
+            guard enableLocked(), let reporter = crashReporter else {
+                return false
+            }
+            reporter.customData = data
+            return true
+        } catch {
+            print("[FaroCrashReporter] Failed to serialize crash session context: \(error)")
+            return false
+        }
+    }
+
+    /// Gets crash reports from previous sessions without deleting them.
+    ///
+    /// JavaScript acknowledges a report only after successful delivery or an
+    /// intentional local discard.
     ///
     /// - Returns: Array of crash report JSON strings, or nil if no crashes
-    @objc public static func getCrashReports() -> [String]? {
-        // Ensure crash reporter is enabled
-        guard enable() else {
+    @objc public static func getPendingCrashReports() -> [String]? {
+        guard let reporter = enabledReporter(), reporter.hasPendingCrashReport() else {
             return nil
         }
 
-        guard let reporter = crashReporter else {
+        do {
+            let data = try reporter.loadPendingCrashReportDataAndReturnError()
+            let reportId = reportIdentifier(for: data)
+
+            do {
+                let plcrReport = try PLCrashReport(data: data)
+                let crashReport = try FaroCrashReport(from: plcrReport)
+                if let json = exportCrashReportAsJSON(crashReport, reportId: reportId) {
+                    return [json]
+                }
+            } catch {
+                print("[FaroCrashReporter] Failed to parse pending crash report: \(error)")
+            }
+
+            // Return a stable marker so JavaScript can acknowledge an unreadable
+            // report rather than assigning it to the new session or retrying forever.
+            return [malformedReportJSON(reportId: reportId)]
+        } catch {
+            print("[FaroCrashReporter] Failed to load pending crash report: \(error)")
+            _ = purgeUnreadablePendingReport(reporter)
             return nil
         }
+    }
 
+    /// Purges the pending report only when its stable ID was acknowledged.
+    ///
+    /// - Parameter reportIds: Stable IDs handled by JavaScript
+    /// - Returns: true when no matching report remains or the matching report was purged
+    @objc public static func acknowledgeCrashReports(_ reportIds: [String]) -> Bool {
+        guard let reporter = enabledReporter() else {
+            return false
+        }
         guard reporter.hasPendingCrashReport() else {
-            return nil
+            return true
         }
 
-        var crashReports: [String] = []
+        let acknowledgedIds = Set(
+            reportIds
+                .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+        )
+        guard !acknowledgedIds.isEmpty else {
+            return true
+        }
 
         do {
             let data = try reporter.loadPendingCrashReportDataAndReturnError()
-            let plcrReport = try PLCrashReport(data: data)
-            let crashReport = try FaroCrashReport(from: plcrReport)
-
-            // Convert to JSON matching Android format
-            if let jsonString = exportCrashReportAsJSON(crashReport) {
-                crashReports.append(jsonString)
+            guard acknowledgedIds.contains(reportIdentifier(for: data)) else {
+                return true
             }
+            return reporter.purgePendingCrashReport()
         } catch {
-            print("[FaroCrashReporter] Failed to load crash report: \(error)")
+            print("[FaroCrashReporter] Failed to acknowledge pending crash report: \(error)")
+            return purgeUnreadablePendingReport(reporter)
         }
+    }
 
-        // Purge the crash report after loading
-        reporter.purgePendingCrashReport()
+    /// Gets crash reports from previous sessions as JSON strings.
+    ///
+    /// Returns an array of JSON strings, each representing a crash report.
+    /// The JSON format matches the Android implementation for consistency.
+    /// This legacy API eagerly purges returned reports for older JavaScript bundles
+    /// that cannot acknowledge delivery.
+    ///
+    /// - Returns: Array of crash report JSON strings, or nil if no crashes
+    @objc public static func getCrashReports() -> [String]? {
+        guard let crashReports = getPendingCrashReports() else {
+            return nil
+        }
 
-        return crashReports.isEmpty ? nil : crashReports
+        let reportIds = crashReports.compactMap(reportIdentifier(from:))
+        _ = acknowledgeCrashReports(reportIds)
+        return crashReports
     }
 
     // MARK: - Private Helpers
 
+    private static func enabledReporter() -> PLCrashReporter? {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        guard enableLocked() else {
+            return nil
+        }
+        return crashReporter
+    }
+
+    private static func purgeUnreadablePendingReport(_ reporter: PLCrashReporter) -> Bool {
+        let purged = reporter.purgePendingCrashReport()
+        if !purged {
+            print("[FaroCrashReporter] Failed to purge unreadable pending crash report")
+        }
+        return purged
+    }
+
     /// Converts a FaroCrashReport to JSON string matching the Android format.
-    private static func exportCrashReportAsJSON(_ crashReport: FaroCrashReport) -> String? {
+    private static func exportCrashReportAsJSON(_ crashReport: FaroCrashReport, reportId: String) -> String? {
         var json: [String: Any] = [:]
+        json["reportId"] = reportId
 
         // Reason - matches Android's "reason" field
         // For iOS, we use the signal name as the reason
@@ -176,6 +285,14 @@ public class FaroCrashReporter: NSObject {
             json["incidentId"] = incidentId
         }
 
+        if let sessionContext = decodeSessionContext(crashReport.contextData) {
+            for key in sessionContextKeys {
+                if let value = sessionContext[key] {
+                    json[key] = value
+                }
+            }
+        }
+
         // Convert to JSON string
         do {
             let jsonData = try JSONSerialization.data(withJSONObject: json, options: [])
@@ -186,6 +303,82 @@ public class FaroCrashReporter: NSObject {
         }
     }
 
+    private static func sanitizeSessionContext(_ context: [String: Any]) -> [String: Any] {
+        var sanitized: [String: Any] = [:]
+
+        if let sessionId = nonEmptyString(context["sessionId"]) {
+            sanitized["sessionId"] = sessionId
+        }
+        // Android uses activatedAt to map a crash to persisted session history.
+        // iOS keeps it in the shared context shape, although PLCrashReporter
+        // already snapshots the one active context directly into the report.
+        if let activatedAt = context["activatedAt"] as? NSNumber,
+           activatedAt.doubleValue.isFinite,
+           activatedAt.doubleValue > 0 {
+            sanitized["activatedAt"] = activatedAt
+        }
+        if let isSampled = context["isSampled"] as? NSNumber {
+            sanitized["isSampled"] = isSampled.boolValue
+        }
+        for key in ["appVersion", "appRelease", "appBundleId"] {
+            if let value = nonEmptyString(context[key]) {
+                sanitized[key] = value
+            }
+        }
+
+        return sanitized
+    }
+
+    private static func decodeSessionContext(_ data: Data?) -> [String: Any]? {
+        guard let data else {
+            return nil
+        }
+        do {
+            guard let context = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+                  nonEmptyString(context["sessionId"]) != nil else {
+                return nil
+            }
+            return sanitizeSessionContext(context)
+        } catch {
+            print("[FaroCrashReporter] Failed to decode crash session context: \(error)")
+            return nil
+        }
+    }
+
+    private static func nonEmptyString(_ value: Any?) -> String? {
+        guard let string = value as? String else {
+            return nil
+        }
+        let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func malformedReportJSON(reportId: String) -> String {
+        let data = try? JSONSerialization.data(withJSONObject: ["reportId": reportId])
+        return data.flatMap { String(data: $0, encoding: .utf8) } ?? "{\"reportId\":\"\(reportId)\"}"
+    }
+
+    private static func reportIdentifier(from crashReportJSON: String) -> String? {
+        guard let data = crashReportJSON.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return nil
+        }
+        return nonEmptyString(json["reportId"])
+    }
+
+    private static func reportIdentifier(for data: Data) -> String {
+        // PLCrashReporter stores a single immutable report. A deterministic hash
+        // gives both retrieval and acknowledgement the same stable opaque ID,
+        // including when the report itself cannot be parsed.
+        var hash: UInt64 = 14_695_981_039_346_656_037
+        for byte in data {
+            hash ^= UInt64(byte)
+            hash = hash &* 1_099_511_628_211
+        }
+        let hex = String(hash, radix: 16)
+        return "ios-\(String(repeating: "0", count: max(0, 16 - hex.count)))\(hex)"
+    }
+
     /// Creates a human-readable description of the crash.
     ///
     /// This returns just the descriptive portion. The TypeScript layer formats the

package/ios/FaroReactNative.swift

@@ -20,6 +20,15 @@ import Foundation
 /// but include improvements where applicable (e.g., better memory metric).
 @objc(FaroReactNative)
 public class FaroReactNative: NSObject {
+    /// Stable bundle identity used to isolate persisted session chains.
+    @objc public static func getSessionProcessIdentifier() -> String {
+        return Bundle.main.bundleIdentifier ?? ProcessInfo.processInfo.processName
+    }
+
+    /// App extensions have an NSExtension dictionary in their main bundle.
+    @objc public static func isMainSessionProcess() -> Bool {
+        return Bundle.main.object(forInfoDictionaryKey: "NSExtension") == nil
+    }
 
     // MARK: - App Startup Time
 
@@ -172,4 +181,19 @@ public class FaroReactNative: NSObject {
     @objc public static func getCrashReports() -> [String]? {
         return FaroCrashReporter.getCrashReports()
     }
+
+    /// Records the active Faro session in PLCrashReporter's custom crash data.
+    @objc public static func recordCrashSessionContext(_ sessionContext: [String: Any]) -> Bool {
+        return FaroCrashReporter.recordSessionContext(sessionContext)
+    }
+
+    /// Gets pending crash reports without deleting them.
+    @objc public static func getPendingCrashReports() -> [String]? {
+        return FaroCrashReporter.getPendingCrashReports()
+    }
+
+    /// Purges only the pending report whose stable ID was acknowledged.
+    @objc public static func acknowledgeCrashReports(_ reportIds: [String]) -> Bool {
+        return FaroCrashReporter.acknowledgeCrashReports(reportIds)
+    }
 }

package/ios/FaroReactNativeModule.h

@@ -1,4 +1,5 @@
 #import <React/RCTBridgeModule.h>
+#import <React/RCTInvalidating.h>
 
-@interface FaroReactNativeModule : NSObject <RCTBridgeModule>
+@interface FaroReactNativeModule : NSObject <RCTBridgeModule, RCTInvalidating>
 @end

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