@grafana/faro-react-native 1.3.1 → 1.4.1

package/README.md

@@ -62,9 +62,7 @@ initializeFaro({
   // Session - optional
   sessionTracking: {
     enabled: true,
-    persistent: false,
-    inactivityTimeout: 15 * 60 * 1000,
-    sessionExpirationTime: 4 * 60 * 60 * 1000,
+    persistent: true,
     maxSessionPersistenceTime: 15 * 60 * 1000,
     // Optional: sampling: new SamplingRate(0.1) or new SamplingFunction((ctx) => ...)
     // Omit sampling to record all sessions (default).
@@ -178,6 +176,12 @@ This package’s **`android/build.gradle`** registers **`faroUploadComposedSourc
 - **Crash Reporting Instrumentation** - Captures native crashes — `enableCrashReporting` (default: false)
 - **Tracing Instrumentation** - OpenTelemetry distributed tracing (requires `@grafana/faro-react-native-tracing`) — `enableTracing` (default: false)
 
+On iOS and Android 11 or newer, recovered native crashes are reported on the next launch with the session ID
+and timestamp from the process that crashed. Failed deliveries remain pending for a later launch; Android
+retries reports for up to seven days, while PLCrashReporter keeps one pending iOS report. The newly started
+session continues to identify live telemetry. If the original session context is unavailable, the recovered
+crash is skipped rather than assigned to the newly started session.
+
 ### React Integration
 
 - **Error Boundary** - Catch and report React component errors with `FaroErrorBoundary`
@@ -777,7 +781,64 @@ initializeFaro({
 
 ### Session Configuration
 
-The SDK supports both persistent and volatile session tracking with configurable expiration and inactivity timeouts:
+Session persistence is enabled by default. The SDK does not bundle storage, so
+apps using the default configuration must install the optional
+`react-native-mmkv` peer dependency:
+
+```bash
+yarn add react-native-mmkv
+```
+
+Rebuild the native projects after installing or upgrading the SDK. A JavaScript-only
+or OTA update cannot add the native process-coordination methods; when they are
+unavailable, Faro uses an in-memory session rather than risking concurrent writes.
+Apps using `persistent: false` use in-memory sessions and do not need MMKV.
+
+Use `maxSessionPersistenceTime` to control the inactivity and cold-start linking window. A session's
+maximum lifetime is fixed at four hours.
+
+The inactivity window is refreshed only by meaningful activity:
+
+| Activity source                                                           | Activity category |
+| ------------------------------------------------------------------------- | ----------------- |
+| Navigation and view changes                                               | Meaningful        |
+| Return from `background` to `active`                                      | Meaningful        |
+| Telemetry linked to a tracked user action                                 | Meaningful        |
+| React Native touch starts inside `FaroSessionActivityBoundary`            | Meaningful        |
+| Explicit `notifySessionActivity()` calls                                  | Meaningful        |
+| Other app lifecycle events                                                | Passive           |
+| Unmarked events, logs, errors, measurements, and traces                   | Passive           |
+| Unmarked HTTP and XHR requests                                            | Passive           |
+| Unmarked session, startup, ANR, frame, console, and performance telemetry | Passive           |
+
+Passive telemetry still checks whether the session has expired, but it does not
+keep the session alive. To refresh inactivity for ordinary touches without
+emitting user-action telemetry, wrap the application once with
+`FaroSessionActivityBoundary`:
+
+```tsx
+import { FaroSessionActivityBoundary } from '@grafana/faro-react-native';
+
+export function App() {
+  return (
+    <FaroSessionActivityBoundary>
+      <AppNavigator />
+    </FaroSessionActivityBoundary>
+  );
+}
+```
+
+The boundary observes touch-start responder negotiation from descendants
+without becoming the responder. This covers standard React Native presses,
+scrolling, dragging, and touches that focus inputs on Android and iOS.
+Continued keyboard input after focus is not another touch. Interactions
+rendered outside the boundary's React Native responder tree, or native and
+accessibility interactions that do not produce a React Native touch event, are
+also not observed. Call `notifySessionActivity()` from those paths. The
+boundary renders a `flex: 1` view for root usage; pass `style` to override its
+layout when wrapping a subtree. Use `withFaroUserAction` or `trackUserAction`
+only when the interaction should also emit user-action telemetry and correlate
+related work.
 
 ```tsx
 import { initializeFaro, SamplingFunction, SamplingRate } from '@grafana/faro-react-native';
@@ -790,10 +851,8 @@ initializeFaro({
   },
   sessionTracking: {
     enabled: true, // default: true
-    persistent: true, // default: false (volatile)
-    // Configurable timeouts (all in ms):
-    inactivityTimeout: 15 * 60 * 1000, // default: 15 min
-    sessionExpirationTime: 4 * 60 * 60 * 1000, // default: 4 h
+    persistent: true, // default: true
+    // Inactivity and cold-start linking window (ms):
     maxSessionPersistenceTime: 15 * 60 * 1000, // default: 15 min
 
     // Optional: session sampling (omit = all sessions recorded)
@@ -822,37 +881,78 @@ initializeFaro({
 
 **Session Types:**
 
-- **Persistent Sessions** (`persistent: true`): Stored in AsyncStorage and survive app restarts. Sessions expire after `sessionExpirationTime` (default 4 h) or `inactivityTimeout` (default 15 min).
+- **Persistent Sessions** (`persistent: true`, default): A versioned record is stored in MMKV. Every process start creates a new session and links the previous ID when the record is valid. The live session is never resumed across a process start.
+
+- **Volatile Sessions** (`persistent: false`): Stored in memory only. Each app launch creates a new session.
+
+The persisted record contains only the current and previous session IDs, start and last-activity timestamps, the sampling decision, and a schema version. Session attributes, device state, and overrides remain in memory. Records older than `maxSessionPersistenceTime` are discarded. Unversioned records from earlier SDK versions, corrupt records, and unsupported schema versions are removed and start an unlinked session.
+
+Persistent storage is isolated by native process:
+
+- On Android, the main process keeps the existing MMKV storage ID. A process declared with `android:process` uses a separate record based on its full process name.
+- On iOS, the host app keeps the existing MMKV storage ID. Each extension uses a separate record based on its `Bundle.main.bundleIdentifier`. Each target that initializes Faro must include the Faro native module and MMKV. Extension persistence requires `react-native-mmkv` v3 or newer so Faro can enable MMKV's multi-process mode; older versions fall back to memory in extensions.
+- Each process maintains its own previous-session link. The `process_name` session attribute identifies which process or extension produced the telemetry.
+
+Only one React Native runtime at a time may write a native process's record. An overlapping runtime that has already fallen back remains in memory for its lifetime. After the owning runtime is invalidated, a newly created replacement runtime can claim persistence. The SDK also falls back to memory when native process identity is unavailable, MMKV cannot be initialized safely, or exclusive ownership cannot be established, and logs a warning rather than risking concurrent writes.
 
-- **Volatile Sessions** (`persistent: false`, default): Stored in memory only. Each app launch creates a new session.
+A single session shared across Android processes or between an iOS host app and extension is not supported. Configuring an App Group does not merge Faro session chains between a host app and its extensions because their record IDs remain distinct. If multiple host apps share the same App Group, they share Faro's fixed host record ID; only one of those apps may use `persistent: true`, and the others must use `persistent: false`. Shared sessions would require a multi-process-safe store and native writer coordination. Use `persistent: false` for runtimes where an independent persisted chain is not wanted.
 
 **Sampling:** Set `sessionTracking.sampling` to a `SamplingRate` (fixed 0–1) or `SamplingFunction` (dynamic, receives `context.meta`). Omit `sampling` to record all sessions. The decision is made once per session.
 
-**Defaults:** `persistent=false`, `inactivityTimeout=15min`, `sessionExpirationTime=4h`, `maxSessionPersistenceTime=15min`
+**Defaults:** `persistent=true`, `maxSessionPersistenceTime=15min`. The maximum session lifetime is four hours.
 
 **Session events:**
 
-The SDK emits `session_start` when a new session is created (including when session metadata changes to a new session id). Resuming a valid persisted session does not emit additional lifecycle events.
+The SDK emits `session_start` when a new session is created, including each cold start and when session metadata changes to a new session ID.
+
+**Starting a new linked session:**
+
+Use `startNewSession()` after changing or clearing the current user at an
+application-defined boundary. It immediately creates a new session, links the
+previous session ID, restarts the lifetime, inactivity, and sampling windows,
+and creates the normal `session_start` event. As with other telemetry, the event
+is not exported when the new session is sampled out. Persistent sessions attempt
+the synchronous MMKV write before the call returns; write failures are logged
+and the new session remains active in memory.
+
+```tsx
+import { startNewSession } from '@grafana/faro-react-native';
+
+function logout() {
+  faro.api.resetUser();
+  startNewSession();
+}
+
+function switchAccount(nextUserId: string) {
+  faro.api.setUser({ id: nextUserId });
+  startNewSession();
+}
+```
+
+Any active user action is ended before the new session starts so its buffered telemetry
+stays with the previous session. Calls made before Faro initializes, after
+teardown, or while session tracking is disabled have no effect.
 
 ### Default Session Attributes
 
-Every telemetry event automatically includes default session attributes with device and SDK information. These attributes match the [Grafana Faro Flutter SDK](https://github.com/grafana/faro-flutter-sdk) format for cross-platform compatibility.
+Every telemetry event automatically includes default session attributes with device and SDK information.
 
 **Automatically Collected Attributes:**
 
-| Attribute              | Description          | iOS Example     | Android Example       |
-| ---------------------- | -------------------- | --------------- | --------------------- |
-| `faro_sdk_version`     | SDK version          | `2.0.2`         | `2.0.2`               |
-| `react_native_version` | React Native version | `0.75.1`        | `0.75.1`              |
-| `device_os`            | Operating system     | `iOS`           | `Android`             |
-| `device_os_version`    | OS version           | `17.0`          | `15`                  |
-| `device_os_detail`     | Detailed OS info     | `iOS 17.0`      | `Android 15 (SDK 35)` |
-| `device_manufacturer`  | Manufacturer         | `apple`         | `samsung`             |
-| `device_model`         | Raw model identifier | `iPhone16,1`    | `SM-A155F`            |
-| `device_model_name`    | Human-readable model | `iPhone 15 Pro` | `SM-A155F`\*          |
-| `device_brand`         | Device brand         | `iPhone`        | `samsung`             |
-| `device_is_physical`   | Physical or emulator | `true`          | `true`                |
-| `device_id`            | Unique device ID     | `uuid`          | `uuid`                |
+| Attribute              | Description          | iOS Example      | Android Example       |
+| ---------------------- | -------------------- | ---------------- | --------------------- |
+| `faro_sdk_version`     | SDK version          | `2.0.2`          | `2.0.2`               |
+| `react_native_version` | React Native version | `0.75.1`         | `0.75.1`              |
+| `process_name`         | Process identity     | `com.acme.share` | `com.acme.app:sync`   |
+| `device_os`            | Operating system     | `iOS`            | `Android`             |
+| `device_os_version`    | OS version           | `17.0`           | `15`                  |
+| `device_os_detail`     | Detailed OS info     | `iOS 17.0`       | `Android 15 (SDK 35)` |
+| `device_manufacturer`  | Manufacturer         | `apple`          | `samsung`             |
+| `device_model`         | Raw model identifier | `iPhone16,1`     | `SM-A155F`            |
+| `device_model_name`    | Human-readable model | `iPhone 15 Pro`  | `SM-A155F`\*          |
+| `device_brand`         | Device brand         | `iPhone`         | `samsung`             |
+| `device_is_physical`   | Physical or emulator | `true`           | `true`                |
+| `device_id`            | Unique device ID     | `uuid`           | `uuid`                |
 
 \*Android does not provide a mapping from model codes to marketing names, so `device_model_name` equals `device_model`.
 
@@ -1067,6 +1167,43 @@ The SDK automatically tracks app startup time from process start to Faro initial
 | avg
 ```
 
+#### Frame Monitoring (Refresh Rate, Slow & Frozen Frames)
+
+Enable with `refreshRateVitals: true`. Uses native frame callbacks
+(`CADisplayLink` on iOS, `Choreographer` on Android).
+
+**Defaults** (override via `frameMonitoringOptions`):
+
+- **Frozen frame threshold**: 700ms (aligned with Android Vitals)
+- **Slow frame target**: 60 FPS (event-based grouping; events ≥50ms count)
+- **Poll interval**: 30s (`refreshRatePollingInterval`)
+
+Slow and frozen frames are **polled** on both platforms (no duplicate
+Android event stream). Refresh rate may also emit on Android between polls
+when `refreshRateVitals` is enabled.
+
+**Metrics:**
+
+| Type               | Values                             | Notes                                                 |
+| ------------------ | ---------------------------------- | ----------------------------------------------------- |
+| `app_refresh_rate` | `refresh_rate`                     | Current FPS                                           |
+| `app_frames_rate`  | `slow_frames`                      | Count of slow frame **events**, not individual frames |
+| `app_frozen_frame` | `frozen_frames`, `frozen_duration` | Frames above threshold; duration in ms                |
+
+**Configuration example:**
+
+```tsx
+initializeFaro({
+  url: 'https://your-faro-collector-url',
+  app: { name: 'my-app', version: '1.0.0' },
+  refreshRateVitals: true,
+  frameMonitoringOptions: {
+    frozenFrameThresholdMs: 700,
+    refreshRatePollingInterval: 30000,
+  },
+});
+```
+
 #### Performance Best Practices
 
 **For Production:**
@@ -1163,13 +1300,13 @@ The SDK collects the following device information synchronously:
 
 ## Device Information
 
-The SDK automatically collects device information and sends it as **session attributes** with every telemetry event. This matches the Faro Flutter SDK convention and provides comprehensive device context for mobile observability.
+The SDK automatically collects device information and sends it as **session attributes** with every telemetry event.
 
 ### Session Attributes
 
-All device information is sent as session attributes (not browser meta) to match Flutter SDK:
+All device information is sent as session attributes (not browser meta):
 
-**Core Attributes (matching Flutter SDK):**
+**Core Attributes:**
 
 - `faro_sdk_version` - SDK version (e.g., "1.0.0")
 - `react_native_version` - React Native version (e.g., "0.75.1")
@@ -1244,7 +1381,7 @@ These attributes are automatically collected during Faro initialization and incl
 - Session attributes are included with every telemetry event
 - All fields are optional and gracefully handle permission errors
 - The React Native SDK sends an empty `page` meta field to override faro-core's default web-specific page meta
-- Screen tracking is handled via `view` meta instead of `page` meta (matching Flutter SDK)
+- Screen tracking is handled via `view` meta instead of `page` meta
 - Battery, carrier, and low power mode info may not be available on all devices/OS versions
 
 ## TypeScript
@@ -1270,12 +1407,20 @@ See the [demo](../../demo) directory for a complete example application.
 - `faro.api.pushMeasurement(measurement: Measurement)` - Track performance
 - `faro.api.setUser(user: User)` - Identify users
 - `faro.api.resetUser()` - Clear user identification
+- `startNewSession()` - Top-level API that starts a new session linked to the current session
 
 ### User Actions API
 
 - `withFaroUserAction<P>(Component, defaultActionName)` - HOC for tracking component interactions
 - `trackUserAction(actionName, context?)` - Manual user action tracking
 
+### Session Activity API
+
+- `FaroSessionActivityBoundary` - Refresh session inactivity for touch starts
+  inside a React Native responder subtree without emitting user-action telemetry
+- `notifySessionActivity()` - Refresh session inactivity for supported
+  interactions outside the boundary
+
 ### Error Boundary API
 
 - `FaroErrorBoundary` - React component for catching and reporting component errors
@@ -1369,6 +1514,7 @@ console.debug('New event', {
 ### React Components
 
 - `FaroErrorBoundary` - Error boundary component for catching React errors
+- `FaroSessionActivityBoundary` - Touch activity boundary for session inactivity
 - `withFaroErrorBoundary` - HOC for wrapping components with error boundary
 
 ## Future Enhancements

package/android/build.gradle

@@ -1,4 +1,12 @@
 buildscript {
+    // Follow the consumer app's Kotlin version. Pinning our own would ship a
+    // stdlib the app's compiler cannot read: Kotlin 1.9.x rejects 2.2 metadata,
+    // and our peer range still admits react-native >=0.70.0. The fallback only
+    // applies to apps whose root buildscript sets no kotlinVersion.
+    ext.faroKotlinVersion = rootProject.ext.has('kotlinVersion')
+        ? rootProject.ext.get('kotlinVersion')
+        : '1.9.25'
+
     repositories {
         google()
         mavenCentral()
@@ -6,8 +14,8 @@ buildscript {
 
     dependencies {
         classpath 'com.android.tools.build:gradle:7.4.2'
-        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0'
-        classpath 'com.google.protobuf:protobuf-gradle-plugin:0.9.4'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$faroKotlinVersion"
+        classpath 'com.google.protobuf:protobuf-gradle-plugin:0.10.0'
     }
 }
 
@@ -17,20 +25,17 @@ apply plugin: 'com.google.protobuf'
 
 android {
     namespace 'com.grafana.faro.reactnative'
-    compileSdkVersion 33
+    compileSdkVersion 34
 
     defaultConfig {
         minSdkVersion 21
-        targetSdkVersion 33
+        targetSdkVersion 34
         consumerProguardFiles 'consumer-proguard-rules.pro'
     }
 
     sourceSets {
         main {
             java.srcDirs = ['src/main/java']
-            proto {
-                srcDir 'src/main/proto'
-            }
         }
     }
 
@@ -45,7 +50,7 @@ android {
 
 protobuf {
     protoc {
-        artifact = 'com.google.protobuf:protoc:3.25.5'
+        artifact = 'com.google.protobuf:protoc:3.25.9'
     }
     generateProtoTasks {
         all().each { task ->
@@ -66,12 +71,12 @@ repositories {
 dependencies {
     //noinspection GradleDynamicVersion
     implementation 'com.facebook.react:react-native:+'
-    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.8.0'
-    implementation 'com.google.protobuf:protobuf-javalite:3.25.5'
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$faroKotlinVersion"
+    implementation 'com.google.protobuf:protobuf-javalite:3.25.9'
 
     testImplementation 'junit:junit:4.13.2'
-    testImplementation 'org.robolectric:robolectric:4.11.1'
-    testImplementation 'androidx.test:core:1.5.0'
+    testImplementation 'org.robolectric:robolectric:4.17'
+    testImplementation 'androidx.test:core:1.7.0'
 }
 
 /* ---------------------------------------------------------------------------

package/android/src/main/java/com/grafana/faro/reactnative/FaroCrashIds.kt

@@ -0,0 +1,44 @@
+package com.grafana.faro.reactnative
+
+import java.security.MessageDigest
+
+internal object FaroCrashIds {
+    private const val SCHEMA_VERSION = 1
+
+    fun sessionContextId(
+        sessionId: String,
+        activatedAtMs: Long,
+        pid: Int,
+        processName: String,
+    ): String {
+        return digest("context", sessionId, activatedAtMs, pid, processName)
+    }
+
+    fun reportId(
+        packageName: String,
+        timestampMs: Long,
+        pid: Int,
+        processName: String,
+    ): String {
+        return digest("report", packageName, timestampMs, pid, processName)
+    }
+
+    private fun digest(kind: String, vararg parts: Any): String {
+        val input = buildString {
+            append(SCHEMA_VERSION)
+            append('|')
+            append(kind)
+            for (part in parts) {
+                val value = part.toString()
+                append('|')
+                append(value.length)
+                append(':')
+                append(value)
+            }
+        }
+        val hash = MessageDigest.getInstance("SHA-256")
+            .digest(input.toByteArray(Charsets.UTF_8))
+            .joinToString("") { byte -> "%02x".format(byte.toInt() and 0xff) }
+        return "v$SCHEMA_VERSION:$hash"
+    }
+}