@oneuptime/react-native-replay 13.0.4

package/OneUptimeReactNativeReplay.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |spec|
+  spec.name = "OneUptimeReactNativeReplay"
+  spec.version = package["version"]
+  spec.summary = package["description"]
+  spec.homepage = "https://oneuptime.com"
+  spec.license = package["license"]
+  spec.author = package["author"]
+  spec.source = {
+    :git => "https://github.com/OneUptime/oneuptime.git",
+    :tag => "#{spec.version}"
+  }
+  spec.platforms = { :ios => "13.0" }
+  spec.source_files = "ios/**/*.{h,m,mm,swift}"
+  spec.swift_version = "5.7"
+  spec.dependency "React-Core"
+end

package/README.md

@@ -0,0 +1,264 @@
+# `@oneuptime/react-native-replay`
+
+Privacy-first session replay for React Native. The SDK samples the native view
+hierarchy into synthetic rrweb events and sends them through OneUptime's normal
+session-replay ingest pipeline. It records layout, tightly allowlisted visual
+styles, navigation, touches, custom events, and JavaScript errors without
+capturing screenshots or readable native text.
+
+## Requirements
+
+- React Native 0.73 or newer.
+- `@react-native-async-storage/async-storage` installed in the application.
+- A OneUptime RUM application with session replay enabled.
+- The Android application ID or iOS bundle ID added to that application's
+  replay origin allowlist as `app://com.example.yourapp`.
+
+This package contains native modules. **Expo Go is not supported.** Expo apps
+must use a development build or EAS build after prebuild. Bare iOS apps must
+run `pod install` (or `npx pod-install`) after installation. Android and iOS
+modules autolink on supported React Native versions.
+
+```sh
+npm install @oneuptime/react-native-replay \
+  @react-native-async-storage/async-storage
+npx pod-install
+```
+
+## Start recording
+
+Wrap the application root so the SDK can register one non-collapsable native
+root and observe bubbling touch events. The provider can start the default
+client for you:
+
+```tsx
+import {
+  OneUptimeReplayProvider,
+  ReplayMask,
+} from "@oneuptime/react-native-replay";
+
+export default function App() {
+  return (
+    <OneUptimeReplayProvider
+      options={{
+        host: "https://oneuptime.example.com",
+        token: "YOUR_TELEMETRY_INGESTION_KEY",
+        appIdentifier: "YOUR_RUM_APPLICATION_IDENTIFIER",
+        mobileAppIdentifier: "com.example.checkout",
+        userRef: "support-user-42", // optional record-next-session target
+      }}
+    >
+      <RootNavigator />
+    </OneUptimeReplayProvider>
+  );
+}
+```
+
+`mobileAppIdentifier` is the installed binary's Android `applicationId` or
+iOS bundle identifier. It is canonicalized to lowercase and must contain at
+least two reverse-DNS labels. `appIdentifier` is the OneUptime RUM application
+identifier; the two identifiers are intentionally different.
+
+For manual lifecycle control, omit `options` from the provider and use the
+singleton:
+
+```ts
+import OneUptimeReplay from "@oneuptime/react-native-replay";
+
+await OneUptimeReplay.start({
+  host: "https://oneuptime.example.com",
+  token: "YOUR_TELEMETRY_INGESTION_KEY",
+  appIdentifier: "YOUR_RUM_APPLICATION_IDENTIFIER",
+  mobileAppIdentifier: "com.example.checkout",
+  appName: "Checkout",       // optional metadata override
+  appVersion: "2.4.1",       // optional metadata override
+  userRef: "support-user-42", // optional targeting reference
+});
+
+await OneUptimeReplay.stop();
+```
+
+`host` must be an HTTP(S) origin, not a URL with credentials, a path, query,
+or fragment. The SDK fetches policy before capturing and fails closed if the
+policy request or native bridge is unavailable.
+
+## Privacy model
+
+Mobile replay is deliberately stricter than web replay:
+
+- `<Text>` content and `<TextInput>` values are never read by native code and
+  never appear in an event, regardless of the web masking policy.
+- `<ReplayMask>` is a hard traversal boundary. The wrapper's frame becomes one
+  opaque placeholder and no descendant is visited.
+- Images, WebViews, Skia, Metal/OpenGL, Canvas, SurfaceView, and TextureView
+  content is opaque. Only the containing frame is recorded.
+- Native output is allowlisted to parent-relative geometry, canonical hex
+  background/border colors, bounded border width/radius, opacity, and z-order.
+  Accessibility content, arbitrary props, pixels, and developer test IDs are
+  not serialized.
+- Error messages and stacks can quote user input, so v1 records the JavaScript
+  error type only when it is a built-in safe name and a fixed `[masked]`
+  marker, never a custom name, original message, or stack.
+
+Use `ReplayMask` for any subtree whose mere shape or presence should not be
+recorded:
+
+```tsx
+<ReplayMask>
+  <PaymentCard />
+</ReplayMask>
+```
+
+## Consent
+
+When policy requires explicit consent, capture stays only in the bounded
+in-memory pre-roll until the host grants consent. Nothing is persisted or sent
+before that call.
+
+The first policy request is always anonymous. `grantConsent()` always refreshes
+the current policy before anything is persisted or sent. If `userRef` is
+supplied, the SDK only includes it in a targeting refresh after the anonymous
+policy says consent is not required, or during that post-consent refresh. A
+failed or disabled fresh policy stops recording rather than falling back to the
+older anonymous policy.
+
+```ts
+await OneUptimeReplay.grantConsent();
+await OneUptimeReplay.revokeConsent();
+```
+
+Revocation stops capture and clears the in-memory buffer, session identifier,
+anonymous visitor identifier, and AsyncStorage outbox. A later grant starts a
+new visit.
+
+## Identity, tags, events, and routes
+
+```ts
+OneUptimeReplay.identify("support-user-42", {
+  plan: "enterprise",
+  role: "admin",
+});
+
+OneUptimeReplay.setTags({ build: "2026.09.13", experiment: "checkout-b" });
+OneUptimeReplay.addTag("region", "eu-west");
+OneUptimeReplay.track("checkout_opened", { cartSize: 3 });
+
+// Call from the navigation container's state-change callback.
+await OneUptimeReplay.setRoute("/checkout?payment_token=discarded");
+```
+
+Calling `identify()` before `start()` preserves that reference for the
+consent-safe targeting refresh. A non-empty `userRef` passed to `start()` takes
+precedence over an earlier pre-start `identify()` call. Changing or clearing
+the normalized reference while recording seals the previous user's replay and
+starts a new session before applying the new identity. The SDK immediately
+revalidates targeting for the new reference; a target or manual trigger from
+the old user never carries into the new session.
+
+Identity and traits are sent only when the RUM application's policy enables
+user-identity capture. Under mobile's mandatory `MaskAllText`, trait values,
+custom-event property values, and manual-capture reasons use the same coarse
+text masks as the browser recorder. Event names and the explicitly supplied
+user reference stay readable. Tag values deliberately stay readable and
+searchable, matching the browser contract; do not use tags for secrets. All
+maps remain count/length bounded. Routes always drop query strings and
+fragments and are stored as `app://com.example.checkout/checkout`. The
+remaining path stays readable, so pass stable screen templates rather than
+account names, order numbers, or other sensitive path values.
+
+## Manual and error capture
+
+```ts
+await OneUptimeReplay.captureSession("support-request");
+
+try {
+  await submitOrder();
+} catch (error) {
+  await OneUptimeReplay.captureError(error);
+  throw error;
+}
+```
+
+React Native's existing global JavaScript error handler is chained only when
+it can be safely restored. The SDK never takes ownership of an application
+handler it cannot restore. In error-triggered mode a bounded 60-second/2 MiB
+pre-roll is uploaded after a manual or JavaScript error trigger.
+
+## Diagnostics
+
+```ts
+const diagnostics = OneUptimeReplay.getDiagnostics();
+// status, sessionId, sampled, triggered, consentState, pendingEvents, events
+```
+
+Diagnostics contain recorder decisions and fixed reason codes, not view text.
+Pass `debug: true` at startup to mirror those codes to the development console.
+
+Use the current consented session ID to correlate the application's own traces
+and logs with replay. The listener fires immediately when a session exists,
+again on every rotation, and with `null` when capture stops or consent is
+withdrawn:
+
+```ts
+const unsubscribe = OneUptimeReplay.onSessionChange((sessionId) => {
+  updateOpenTelemetryResource({ "session.id": sessionId });
+});
+
+const sessionId = OneUptimeReplay.getSessionId();
+unsubscribe();
+```
+
+For independent clients or tests, instantiate `new MobileReplayRecorder()` and
+pass it to `<OneUptimeReplayProvider recorder={client}>`.
+
+## Durability and lifecycle
+
+The SDK takes a view-tree sample every 500 ms, creates a full checkout at
+least every 60 seconds, and closes a chunk at 15 seconds or 256 KiB. Chunks are
+gzip-compressed with `fflate.gzipSync`. Each chunk is placed in an ordered,
+bounded AsyncStorage outbox before POST and removed only after a terminal
+server response. AppState backgrounding records visibility, closes the current
+chunk, drains the outbox only when policy and consent permit uploading, and
+pauses sampling; foregrounding resumes with a fresh full snapshot.
+
+Policy is revalidated without HTTP-cache reuse before every foreground resume,
+after identity changes, and at five-minute intervals while the app remains
+active. An explicit disable takes effect before more capture; a transient
+network failure outside the consent transition keeps the last valid policy and
+retries on the next bounded refresh cadence. Consent grants always fail closed
+when a fresh policy cannot be obtained.
+
+The SDK never sets a browser `Origin` header. It sends
+`x-oneuptime-replay-recorder-kind: rn-view-tree` and the mobile app identifier;
+the server validates the identifier and synthesizes its exact `app://` origin.
+
+## Fidelity limitations
+
+- Reanimated/UI-thread animations are sampled, not frame-accurate.
+- Image pixels, WebView content, Skia, Metal/OpenGL, and other drawing surfaces
+  replay as disclosed opaque rectangles.
+- JavaScript errors are captured reliably. Hard native crashes may terminate
+  the process before JavaScript can close or upload a chunk and are not a
+  reliable session-replay trigger.
+- Mobile operating systems may suspend networking immediately after an app
+  enters the background. Unacknowledged chunks remain in AsyncStorage for the
+  next launch.
+- This is a wireframe replay, not a screenshot or video recording.
+- Touches beginning in a `ReplayMask`, image, WebView, Skia/canvas, or other
+  opaque surface are discarded for the entire pointer sequence. If a gesture
+  crosses into one later, that touch and the remainder of its pointer sequence
+  are discarded. If current native target ancestry or the coordinate basis
+  cannot be verified, touch telemetry fails closed and is discarded.
+
+## Package development
+
+```sh
+npm run compile
+npm test
+npm run build
+npm pack --dry-run
+```
+
+`prepack` and `prepublishOnly` both build ESM, CommonJS, source maps, and TypeScript
+declarations. The published package contains those artifacts plus Android and
+iOS native sources, the podspec, autolinking configuration, and this README.

package/android/build.gradle

@@ -0,0 +1,36 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+apply plugin: "com.android.library"
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+    namespace "com.oneuptime.replay"
+    compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+    defaultConfig {
+        minSdkVersion safeExtGet("minSdkVersion", 23)
+        targetSdkVersion safeExtGet("targetSdkVersion", 35)
+        consumerProguardFiles "consumer-rules.pro"
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-android"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,26 @@
+# These React Native APIs are accessed reflectively so the same SDK binary can
+# support both the RN 0.73 legacy drawable and newer background implementations.
+-keepnames class com.facebook.react.views.view.ReactViewBackgroundDrawable
+-keepclassmembers class com.facebook.react.views.view.ReactViewBackgroundDrawable {
+    public int getColor();
+    public float getFullBorderWidth();
+    public int getBorderColor(int);
+    public float getFullBorderRadius();
+}
+
+-keepnames class com.facebook.react.uimanager.BackgroundStyleApplicator
+-keepclassmembers class com.facebook.react.uimanager.BackgroundStyleApplicator {
+    public static *** getBackgroundColor(...);
+    public static *** getBorderWidth(...);
+    public static *** getBorderColor(...);
+    public static *** getBorderRadius(...);
+}
+
+-keep class com.facebook.react.uimanager.Spacing {
+    public static int ALL;
+}
+-keep class com.facebook.react.uimanager.style.LogicalEdge { *; }
+-keep class com.facebook.react.uimanager.style.BorderRadiusProp { *; }
+-keepclassmembers class com.facebook.react.uimanager.LengthPercentage {
+    public float resolve(float);
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/oneuptime/replay/OneUptimeReplayPackage.java

@@ -0,0 +1,29 @@
+package com.oneuptime.replay;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.Collections;
+import java.util.List;
+
+public final class OneUptimeReplayPackage implements ReactPackage {
+    @NonNull
+    @Override
+    public List<NativeModule> createNativeModules(
+        @NonNull ReactApplicationContext reactContext
+    ) {
+        return Collections.singletonList(new OneUptimeReplayViewTreeModule(reactContext));
+    }
+
+    @NonNull
+    @Override
+    public List<ViewManager> createViewManagers(
+        @NonNull ReactApplicationContext reactContext
+    ) {
+        return Collections.emptyList();
+    }
+}