clintplay-react-native 0.2.0 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 Session capture SDK for React Native / Expo apps — companion to [`clintplay-sdk`](../sdk) (web). Captures lifecycle, screen dimensions, navigation, JS errors, network requests (Fetch & XHR/Axios), console output, touches (screen-relative & target-relative), and native visual wireframe replay on iOS and Android.
 
-> **Status:** `0.2.0` — Production-ready JS runtime and Native TurboModule. Supports native view hierarchy traversal on iOS (`ios/ClintplayRN.mm`) and Android (`android/.../ClintplayRNModule.kt`), visual wireframe session replay, network interception for `fetch` and `XMLHttpRequest`/Axios, automatic navigation tracking, and intelligent auto-masking for sensitive fields.
+> **Status:** `0.2.2` — Production-ready JS runtime and Native TurboModule. Supports native view hierarchy traversal on iOS (`ios/ClintplayRN.mm`) and Android (`android/.../ClintplayRNModule.kt`), visual wireframe session replay, network interception for `fetch` and `XMLHttpRequest`/Axios, automatic navigation tracking, and intelligent auto-masking for sensitive fields.
 
 ## Install
 
@@ -12,7 +12,7 @@ pnpm add clintplay-react-native
 npm install clintplay-react-native
 ```
 
-Peer deps: `react >=18`, `react-native >=0.74`. Optional peer: `@react-native-async-storage/async-storage` (enables the offline retry queue when present). Tested against Expo SDK 54 / RN 0.81 with New Architecture enabled.
+Peer deps: `react >=18`, `react-native >=0.74`. Optional peer: `@react-native-async-storage/async-storage` (enables the offline retry queue when present). Android verified on Expo SDK 57 / RN 0.86.3 with New Architecture (debug and release builds, and wireframe capture on an emulator); iOS not re-verified on that version.
 
 In your `app.json`, register the config plugin:
 
@@ -81,7 +81,7 @@ export default function RootLayout() {
 | `enabled` | `boolean` | `true` | Master killswitch. Set to `false` to disable all telemetry. |
 | `sampleRate` | `number` | `1.0` | Probabilistic sampling rate between `0.0` and `1.0`. |
 | `captureWireframe` | `boolean` | `false` | Enable native view-hierarchy visual wireframe capture for session replay. |
-| `wireframeIntervalMs` | `number` | `1000` | Wireframe snapshot interval in milliseconds. |
+| `wireframeIntervalMs` | `number` | `1000` | Wireframe snapshot interval in milliseconds. A snapshot identical to the previous one is not re-sent (an unchanged screen is re-sent every 30 s), and a snapshot is also taken ~400 ms after every touch end and navigation, so screens visited for less than the interval still reach the replay. |
 | `captureNetwork` | `boolean` | `true` | Intercept `globalThis.fetch` and `XMLHttpRequest` (including Axios) requests. |
 | `captureConsole` | `boolean` | `false` | Intercept `console.warn` and `console.error` logs. |
 | `captureConsoleLog` | `boolean` | `false` | Intercept `console.log` logs when `captureConsole: true`. |
@@ -104,7 +104,7 @@ export default function RootLayout() {
 | `network` | `fetch` & `XMLHttpRequest` / Axios | **On** | HTTP method, URL (sanitized), status code, duration, and errors. Protected against double-counting. |
 | `navigation` | Navigation Trackers & `trackScreen` | **On (Tracker)** | Screen path changes (`to`, `from`). Automatic via `<ClintplayNavigationTracker />` or React Navigation listener. |
 | `touch` | `<ClintplayCaptureProvider>` | **Provider** | Tap / touch gestures with both screen-relative coordinates (`screenX`, `screenY`) and target-relative coordinates (`x`, `y`). |
-| `wireframe` | Native TurboModule | **Opt-in** | Visual UI hierarchy snapshots (view rects, styles, text, masking) across iOS and Android. |
+| `wireframe` | Native TurboModule | **Opt-in** | Visual UI hierarchy snapshots (view rects, background colors, text with font size, color and alignment — plus weight on iOS, and bold on Android —, masking) across iOS and Android. Sent on change, after interactions, and every 30 s while unchanged. |
 | `log` | Console Interceptor | **Opt-in** | Console output (`warn`, `error`, and optional `log`). |
 | `identify` | `Clintplay.identify()` | **Manual** | Associating sessions with authenticated users and custom traits. |
 

package/android/build.gradle

@@ -1,19 +1,16 @@
-buildscript {
-  // Match the consumer app's Kotlin version so we don't drag in a
-  // conflicting toolchain. Most modern Expo SDK 54 / RN 0.81 apps
-  // ship Kotlin 1.9.x.
-  ext.kotlin_version = rootProject.ext.kotlin_version ?: '1.9.24'
-
-  repositories {
-    google()
-    mavenCentral()
-  }
-  dependencies {
-    classpath "com.android.tools.build:gradle:8.6.0"
-    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-  }
-}
-
+// No `buildscript` block: this module is only built inside a host app, whose
+// root build.gradle already puts the Android and Kotlin Gradle plugins on the
+// classpath (bare RN and Expo templates alike). Don't read a Kotlin version from
+// `rootProject.ext` either: Expo's template defines none, and in Groovy reading
+// a missing `ext` property throws instead of returning null.
+
+// On the classpath through the host's root build.gradle (resolved by the
+// includeBuild in its settings.gradle). Runs the codegen for the
+// `codegenConfig` in package.json (`ClintplayRNSpec`): autolinking adds that
+// spec's `codegen/jni` folder to the app's CMake build and its C++
+// ModuleProvider is what binds this TurboModule to JS, so without the plugin
+// the app's CMake configure fails on a directory that was never generated.
+apply plugin: 'com.facebook.react'
 apply plugin: 'com.android.library'
 apply plugin: 'org.jetbrains.kotlin.android'
 

package/android/src/main/java/digital/clint/clintplay/ClintplayRNModule.kt

@@ -2,13 +2,19 @@ package digital.clint.clintplay
 
 import android.app.Activity
 import android.content.Context
+import android.graphics.Typeface
 import android.graphics.drawable.ColorDrawable
 import android.graphics.drawable.Drawable
 import android.os.Build
 import android.os.Handler
 import android.os.Looper
 import android.text.InputType
+import android.text.Spanned
 import android.text.method.PasswordTransformationMethod
+import android.text.style.AbsoluteSizeSpan
+import android.text.style.ForegroundColorSpan
+import android.text.style.StyleSpan
+import android.view.Gravity
 import android.view.View
 import android.view.ViewGroup
 import android.view.WindowManager
@@ -37,9 +43,11 @@ import kotlin.math.round
 // coordinate conversion, background colors, extracted text, and
 // privacy auto-masking (clintplay-mask tags, password fields, and sensitive autofill hints).
 //
-// React Native's codegen emits `NativeClintplayRNSpec` from
-// `src/spec/NativeClintplayRN.ts` at build time. The TurboReactPackage
-// in `ClintplayRNPackage.kt` routes calls here.
+// React Native's codegen emits `NativeClintplayRNSpec` and its C++ JSI glue
+// from `src/spec/NativeClintplayRN.ts` at build time. This class does not
+// extend that spec: the glue calls the methods below by name and JNI signature
+// (`()Ljava/lang/String;`), so they must match the spec by hand. The
+// TurboReactPackage in `ClintplayRNPackage.kt` routes calls here.
 @ReactModule(name = ClintplayRNModule.NAME)
 class ClintplayRNModule(reactContext: ReactApplicationContext) :
   ReactContextBaseJavaModule(reactContext), TurboModule {
@@ -112,6 +120,45 @@ class ClintplayRNModule(reactContext: ReactApplicationContext) :
     return false
   }
 
+  // React Native sets size and colour as spans on the text, so the spans at the first
+  // character win over the TextView's own defaults. Weight is only sent when bold is
+  // actually detected: RN carries it in its own CustomStyleSpan, which this does not read,
+  // and a guessed 400 would look measured. Best effort: the text alone already makes the
+  // replay readable.
+  private fun putTextStyle(node: JSONObject, view: TextView, density: Float) {
+    try {
+      val text = view.text
+      val safeDensity = if (density > 0f) density else 1f
+      var sizePx = view.textSize
+      var color = view.currentTextColor
+      var bold = view.typeface?.isBold == true
+      if (text is Spanned && text.isNotEmpty()) {
+        text.getSpans(0, 1, AbsoluteSizeSpan::class.java).lastOrNull()?.let { span ->
+          sizePx = if (span.dip) span.size * safeDensity else span.size.toFloat()
+        }
+        text.getSpans(0, 1, ForegroundColorSpan::class.java).lastOrNull()?.let { span ->
+          color = span.foregroundColor
+        }
+        if (text.getSpans(0, 1, StyleSpan::class.java).any { (it.style and Typeface.BOLD) != 0 }) {
+          bold = true
+        }
+      }
+      node.put("fontSize", round(sizePx / safeDensity * 10.0) / 10.0)
+      if (bold) node.put("fontWeight", 700)
+      node.put("color", formatColor(color))
+      val horizontal = Gravity.getAbsoluteGravity(view.gravity, view.layoutDirection) and
+        Gravity.HORIZONTAL_GRAVITY_MASK
+      node.put(
+        "textAlign",
+        when (horizontal) {
+          Gravity.CENTER_HORIZONTAL -> "center"
+          Gravity.RIGHT -> "right"
+          else -> "left"
+        },
+      )
+    } catch (_: Throwable) {}
+  }
+
   private fun serializeView(
     view: View?,
     nodeCounter: AtomicInteger,
@@ -206,6 +253,9 @@ class ClintplayRNModule(reactContext: ReactApplicationContext) :
     var extractedText: String? = null
     if (view is TextView) {
       extractedText = view.text?.toString()
+      if (!isMasked && !extractedText.isNullOrEmpty()) {
+        putTextStyle(nodeObj, view, density)
+      }
     }
 
     if (extractedText != null) {
@@ -278,7 +328,9 @@ class ClintplayRNModule(reactContext: ReactApplicationContext) :
 
   @ReactMethod(isBlockingSynchronousMethod = true)
   fun captureViewHierarchy(): String {
-    val activity = currentActivity ?: return FALLBACK_JSON
+    // Not the inherited `currentActivity`: since RN 0.80 that is a deprecated
+    // protected Kotlin function, which property syntax does not resolve.
+    val activity = reactApplicationContext.currentActivity ?: return FALLBACK_JSON
 
     if (activity.isFinishing || activity.isDestroyed) {
       return FALLBACK_JSON
@@ -328,7 +380,7 @@ class ClintplayRNModule(reactContext: ReactApplicationContext) :
 
   companion object {
     const val NAME = "ClintplayRN"
-    private const val VERSION = "0.2.0"
+    private const val VERSION = "0.2.2"
     private const val FALLBACK_JSON = "{\"version\":1,\"nodes\":[]}"
 
     private val NO_METHOD_SENTINEL = Any()

package/dist/index.d.mts

@@ -7,6 +7,8 @@ interface SessionState {
     startedAt: number;
     lastActivity: number;
     userId: string | null;
+    tags: Set<string>;
+    metadata: Record<string, unknown>;
 }
 declare class SessionManager {
     private state;
@@ -15,13 +17,16 @@ declare class SessionManager {
     private create;
     current(): SessionState;
     touch(): void;
+    addTag(tag: string): boolean;
+    hasTag(tag: string): boolean;
+    setMetadata(data: Record<string, unknown>): void;
     setUser(userId: string | null): boolean;
     isStale(): boolean;
     rotateIfStale(): boolean;
     reset(): void;
 }
 
-type EventType = 'meta' | 'screen' | 'lifecycle' | 'navigation' | 'touch' | 'error' | 'log' | 'identify' | 'network' | 'wireframe';
+type EventType = 'meta' | 'screen' | 'lifecycle' | 'navigation' | 'touch' | 'error' | 'log' | 'identify' | 'network' | 'wireframe' | 'metadata' | 'tag';
 interface DeviceInfo {
     platform: 'ios' | 'android' | 'web';
     osVersion?: string;
@@ -92,6 +97,18 @@ interface NetworkEvent {
     durationMs?: number;
     error?: string;
 }
+interface MetadataEvent {
+    type: 'metadata';
+    ts: number;
+    data: Record<string, unknown>;
+}
+interface TagEvent {
+    type: 'tag';
+    ts: number;
+    data: {
+        tag: string;
+    };
+}
 interface WireframeNode {
     id: number;
     type: string;
@@ -117,7 +134,7 @@ interface WireframeEvent {
     version: number;
     nodes: WireframeNode[];
 }
-type ReplayEvent = MetaEvent | ScreenEvent | LifecycleEvent | NavigationEvent | TouchEvent | ErrorEvent | LogEvent | IdentifyEvent | NetworkEvent | WireframeEvent;
+type ReplayEvent = MetaEvent | ScreenEvent | LifecycleEvent | NavigationEvent | TouchEvent | ErrorEvent | LogEvent | IdentifyEvent | NetworkEvent | WireframeEvent | MetadataEvent | TagEvent;
 interface BackendEvent {
     type: string;
     timestamp: number;
@@ -186,6 +203,10 @@ interface Recorder {
     start(): void;
     stop(): void;
     takeWireframeSnapshot(): void;
+    /** Captura depois que a interação assenta (toque, navegação). Chamadas próximas viram uma. */
+    scheduleWireframeSnapshot(): void;
+    /** A próxima captura é enviada mesmo igual à anterior (sessão nova precisa da tela). */
+    resetWireframeBaseline(): void;
 }
 
 interface NetworkInterceptorDeps {
@@ -386,6 +407,13 @@ interface InternalConfig {
     debug: boolean;
     captureWireframe: boolean;
 }
+declare const METADATA_MAX_KEYS = 50;
+declare const METADATA_MAX_DEPTH = 3;
+declare const METADATA_MAX_STRING_LENGTH = 1024;
+declare const METADATA_MAX_BYTES = 8192;
+declare const TAG_MAX_LENGTH = 128;
+declare function sanitizeTag(rawTag: unknown): string | null;
+declare function sanitizeMetadata(data: unknown): Record<string, unknown> | null;
 declare function formatEventForBatch(event: ReplayEvent | BackendEvent, defaultSessionId: string): BackendEvent;
 declare function init(rawConfig: ClintplayReactNativeConfig): typeof Clintplay;
 declare function identify(userId: string | number | null, traits?: Record<string, unknown>): void;
@@ -394,6 +422,8 @@ declare function reset(options?: {
 }): void;
 declare function trackScreen(path: string, from?: string): void;
 declare function reportError(err: unknown): void;
+declare function setMetadata(data: Record<string, unknown>): void;
+declare function tag(tagName: string): void;
 declare function flush(): Promise<void>;
 declare function stop(): Promise<void>;
 declare function current(): {
@@ -419,10 +449,12 @@ declare const Clintplay: {
     reset: typeof reset;
     trackScreen: typeof trackScreen;
     reportError: typeof reportError;
+    setMetadata: typeof setMetadata;
+    tag: typeof tag;
     flush: typeof flush;
     stop: typeof stop;
     current: typeof current;
     _getState: typeof _getState;
 };
 
-export { type BackendEvent, CLINTPLAY_MASK_ID, Clintplay, ClintplayCaptureProvider, type ClintplayCaptureProviderProps, ClintplayMaskImage, type ClintplayMaskImageProps, ClintplayMaskTextInput, type ClintplayMaskTextInputProps, ClintplayMaskView, type ClintplayMaskViewProps, ClintplayNavigationTracker, type ClintplayNavigationTrackerProps, type ClintplayReactNativeConfig, type DeviceInfo, type NavigationRouteLike, type NavigationStateLike, type NavigationStateListenerCallback, type NavigationStateListenerOptions, type ReplayBatch, type ReplayEvent, SDK_VERSION, type UseClintplayNavigationOptions, type UseClintplayNavigationResult, type WireframeEvent, type WireframeNode, _resetLastTrackedRoute, createClintplayNavigationStateListener, formatEventForBatch, getActiveRouteName, init, sanitizeRoute, useClintplayNavigationTracking };
+export { type BackendEvent, CLINTPLAY_MASK_ID, Clintplay, ClintplayCaptureProvider, type ClintplayCaptureProviderProps, ClintplayMaskImage, type ClintplayMaskImageProps, ClintplayMaskTextInput, type ClintplayMaskTextInputProps, ClintplayMaskView, type ClintplayMaskViewProps, ClintplayNavigationTracker, type ClintplayNavigationTrackerProps, type ClintplayReactNativeConfig, type DeviceInfo, METADATA_MAX_BYTES, METADATA_MAX_DEPTH, METADATA_MAX_KEYS, METADATA_MAX_STRING_LENGTH, type MetadataEvent, type NavigationRouteLike, type NavigationStateLike, type NavigationStateListenerCallback, type NavigationStateListenerOptions, type ReplayBatch, type ReplayEvent, SDK_VERSION, TAG_MAX_LENGTH, type TagEvent, type UseClintplayNavigationOptions, type UseClintplayNavigationResult, type WireframeEvent, type WireframeNode, _resetLastTrackedRoute, createClintplayNavigationStateListener, formatEventForBatch, getActiveRouteName, init, sanitizeMetadata, sanitizeRoute, sanitizeTag, setMetadata, tag, useClintplayNavigationTracking };

package/dist/index.d.ts

@@ -7,6 +7,8 @@ interface SessionState {
     startedAt: number;
     lastActivity: number;
     userId: string | null;
+    tags: Set<string>;
+    metadata: Record<string, unknown>;
 }
 declare class SessionManager {
     private state;
@@ -15,13 +17,16 @@ declare class SessionManager {
     private create;
     current(): SessionState;
     touch(): void;
+    addTag(tag: string): boolean;
+    hasTag(tag: string): boolean;
+    setMetadata(data: Record<string, unknown>): void;
     setUser(userId: string | null): boolean;
     isStale(): boolean;
     rotateIfStale(): boolean;
     reset(): void;
 }
 
-type EventType = 'meta' | 'screen' | 'lifecycle' | 'navigation' | 'touch' | 'error' | 'log' | 'identify' | 'network' | 'wireframe';
+type EventType = 'meta' | 'screen' | 'lifecycle' | 'navigation' | 'touch' | 'error' | 'log' | 'identify' | 'network' | 'wireframe' | 'metadata' | 'tag';
 interface DeviceInfo {
     platform: 'ios' | 'android' | 'web';
     osVersion?: string;
@@ -92,6 +97,18 @@ interface NetworkEvent {
     durationMs?: number;
     error?: string;
 }
+interface MetadataEvent {
+    type: 'metadata';
+    ts: number;
+    data: Record<string, unknown>;
+}
+interface TagEvent {
+    type: 'tag';
+    ts: number;
+    data: {
+        tag: string;
+    };
+}
 interface WireframeNode {
     id: number;
     type: string;
@@ -117,7 +134,7 @@ interface WireframeEvent {
     version: number;
     nodes: WireframeNode[];
 }
-type ReplayEvent = MetaEvent | ScreenEvent | LifecycleEvent | NavigationEvent | TouchEvent | ErrorEvent | LogEvent | IdentifyEvent | NetworkEvent | WireframeEvent;
+type ReplayEvent = MetaEvent | ScreenEvent | LifecycleEvent | NavigationEvent | TouchEvent | ErrorEvent | LogEvent | IdentifyEvent | NetworkEvent | WireframeEvent | MetadataEvent | TagEvent;
 interface BackendEvent {
     type: string;
     timestamp: number;
@@ -186,6 +203,10 @@ interface Recorder {
     start(): void;
     stop(): void;
     takeWireframeSnapshot(): void;
+    /** Captura depois que a interação assenta (toque, navegação). Chamadas próximas viram uma. */
+    scheduleWireframeSnapshot(): void;
+    /** A próxima captura é enviada mesmo igual à anterior (sessão nova precisa da tela). */
+    resetWireframeBaseline(): void;
 }
 
 interface NetworkInterceptorDeps {
@@ -386,6 +407,13 @@ interface InternalConfig {
     debug: boolean;
     captureWireframe: boolean;
 }
+declare const METADATA_MAX_KEYS = 50;
+declare const METADATA_MAX_DEPTH = 3;
+declare const METADATA_MAX_STRING_LENGTH = 1024;
+declare const METADATA_MAX_BYTES = 8192;
+declare const TAG_MAX_LENGTH = 128;
+declare function sanitizeTag(rawTag: unknown): string | null;
+declare function sanitizeMetadata(data: unknown): Record<string, unknown> | null;
 declare function formatEventForBatch(event: ReplayEvent | BackendEvent, defaultSessionId: string): BackendEvent;
 declare function init(rawConfig: ClintplayReactNativeConfig): typeof Clintplay;
 declare function identify(userId: string | number | null, traits?: Record<string, unknown>): void;
@@ -394,6 +422,8 @@ declare function reset(options?: {
 }): void;
 declare function trackScreen(path: string, from?: string): void;
 declare function reportError(err: unknown): void;
+declare function setMetadata(data: Record<string, unknown>): void;
+declare function tag(tagName: string): void;
 declare function flush(): Promise<void>;
 declare function stop(): Promise<void>;
 declare function current(): {
@@ -419,10 +449,12 @@ declare const Clintplay: {
     reset: typeof reset;
     trackScreen: typeof trackScreen;
     reportError: typeof reportError;
+    setMetadata: typeof setMetadata;
+    tag: typeof tag;
     flush: typeof flush;
     stop: typeof stop;
     current: typeof current;
     _getState: typeof _getState;
 };
 
-export { type BackendEvent, CLINTPLAY_MASK_ID, Clintplay, ClintplayCaptureProvider, type ClintplayCaptureProviderProps, ClintplayMaskImage, type ClintplayMaskImageProps, ClintplayMaskTextInput, type ClintplayMaskTextInputProps, ClintplayMaskView, type ClintplayMaskViewProps, ClintplayNavigationTracker, type ClintplayNavigationTrackerProps, type ClintplayReactNativeConfig, type DeviceInfo, type NavigationRouteLike, type NavigationStateLike, type NavigationStateListenerCallback, type NavigationStateListenerOptions, type ReplayBatch, type ReplayEvent, SDK_VERSION, type UseClintplayNavigationOptions, type UseClintplayNavigationResult, type WireframeEvent, type WireframeNode, _resetLastTrackedRoute, createClintplayNavigationStateListener, formatEventForBatch, getActiveRouteName, init, sanitizeRoute, useClintplayNavigationTracking };
+export { type BackendEvent, CLINTPLAY_MASK_ID, Clintplay, ClintplayCaptureProvider, type ClintplayCaptureProviderProps, ClintplayMaskImage, type ClintplayMaskImageProps, ClintplayMaskTextInput, type ClintplayMaskTextInputProps, ClintplayMaskView, type ClintplayMaskViewProps, ClintplayNavigationTracker, type ClintplayNavigationTrackerProps, type ClintplayReactNativeConfig, type DeviceInfo, METADATA_MAX_BYTES, METADATA_MAX_DEPTH, METADATA_MAX_KEYS, METADATA_MAX_STRING_LENGTH, type MetadataEvent, type NavigationRouteLike, type NavigationStateLike, type NavigationStateListenerCallback, type NavigationStateListenerOptions, type ReplayBatch, type ReplayEvent, SDK_VERSION, TAG_MAX_LENGTH, type TagEvent, type UseClintplayNavigationOptions, type UseClintplayNavigationResult, type WireframeEvent, type WireframeNode, _resetLastTrackedRoute, createClintplayNavigationStateListener, formatEventForBatch, getActiveRouteName, init, sanitizeMetadata, sanitizeRoute, sanitizeTag, setMetadata, tag, useClintplayNavigationTracking };