@dynatrace/react-native-plugin 2.339.1 → 2.343.1

package/README.md

@@ -23,20 +23,20 @@ If you want to start using this plugin and are not a Dynatrace customer yet, hea
 * React v16.8 or newer
 * React Native v0.60 or newer
 * For Android users: 
-  * SDK version 21+
-  * Gradle version 7.0+ ([How to update?](#updating-to-gradle-7))
+  * SDK version 23+
+  * Gradle version 8.1.1+ ([How to update?](#updating-to-gradle-7))
   * Android Gradle plugin version 7.0+
-  * Java 11
+  * Java 17
   * Kotlin 2.0.21 - see [Kotlin Compatibility Note](#kotlin-compatibility-note)
   * Jetpack Compose 1.4 - 1.10 - see [Compose Compatibility Note](#compose-compatibility-note)
-* For iOS users: Minimum iOS 12
+* For iOS users: Minimum iOS 15
 * NodeJS 16.0.0+ since our dependencies require NodeJS 16.0.0
 
 ## Agent Versions
 These agent versions are configured in this plugin:
 
-* Android Agent: 8.339.1.1004
-* iOS Agent: 8.339.1.1011
+* Android Agent: 8.343.1.1038
+* iOS Agent: 8.343.1.1007
 
 ## Quick Setup
 
@@ -1030,9 +1030,9 @@ This allows you to preserve interaction analytics while avoiding exposure of sen
 
 Each captured interaction produces an event describing what the user touched and where. The event includes:
 
-- **Element name** — the resolved label of the touched element, derived from its visible text, accessibility label, component name, or test ID.
-- **Component type** — the type of the UI component that was touched (e.g. `Pressable`).
-- **Element path** — a stable path through the component tree that uniquely identifies the element (e.g. `App/View[1]/Pressable[1]`).
+- **Detected name** — the resolved label of the touched element, derived from its visible text, accessibility label, component name, or test ID.
+- **Component** — the type of the UI component that was touched (e.g. `Pressable`).
+- **Component Path** — a stable path through the component tree that uniquely identifies the element (e.g. `App/View[1]/Pressable[1]`).
 - **Interaction type** — how the user interacted (e.g. `touch`).
 - **Position** — the screen coordinates where the touch occurred.
 
@@ -1047,17 +1047,79 @@ If masking is active for an interaction, the event still contains the same struc
   "characteristics.has_user_interaction": true,
   "ui_element.detected_name": "LoginButton",
   "ui_element.components": ["Pressable"],
-  "ui_element.id": "App/View[1]/Pressable[1]",
+  "ui_element.id": "App/View/Pressable",
   "ui_element.name_origin": "component",
-  "interaction.name": "touch",
+  "interaction.type": "touch",
   "positions": [{ "x": 120, "y": 460 }],
   "ui_element.responder.detected_name": "Pressable",
   "ui_element.responder.components": ["Pressable"],
-  "ui_element.responder.id": "App/View[1]/Pressable[1]",
+  "ui_element.responder.id": "App/View[/Pressable",
   "ui_element.responder.name_origin": "component"
 }
 ```
 
+#### Custom Names for Components
+
+You can assign custom names to your components. A custom name affects both the **Component** and the **Component Path** described above. There are two ways to do this, depending on how the component is used.
+
+##### 1. As a JSX prop (`dtActionName`)
+
+Use this when you render the component as JSX. Pass `dtActionName` as a prop, and it overrides the auto-detected name for that specific usage:
+
+```tsx
+<TouchableOpacity dtActionName="Checkout Button" onPress={onCheckout}>
+    <Text dtActionName="Checkout Text">Buy now</Text>
+</TouchableOpacity>
+```
+
+Touching it produces:
+
+```json
+"ui_element.components": ["Checkout Text"],
+"ui_element.id": ".../Checkout Button/Checkout Text"
+```
+
+##### 2. As a static property (`Component.dtActionName`)
+
+Use this when the component is **not** rendered as JSX, so the prop approach above is not available — for example, a screen component you define once and hand to a navigator by reference. Set `dtActionName` directly on the component. This affects **every** place the component is used at once:
+
+```tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { createDrawerNavigator } from '@react-navigation/drawer';
+
+const Drawer = createDrawerNavigator();
+
+function ProfileScreen() {
+    return (/* ... */);
+}
+
+// Applies to all usages of ProfileScreen below
+ProfileScreen.dtActionName = 'User Profile';
+
+function App() {
+    return (
+        <NavigationContainer>
+            <Drawer.Navigator>
+                {/* Both screens reference the same component,
+                    so both pick up the 'User Profile' name */}
+                <Drawer.Screen name="Me" component={ProfileScreen} />
+                <Drawer.Screen name="Account" component={ProfileScreen} />
+            </Drawer.Navigator>
+        </NavigationContainer>
+    );
+}
+```
+
+Touches inside one of the 2 screens now produce:
+
+```json
+"ui_element.id": ".../User Profile/..."
+```
+
+> **Note:** The static property applies to *all* uses of the component. If you need a different name per usage, render the component as JSX and use the `dtActionName` prop (option 1) instead.
+>
+> **Note:** The static property has no effect when a component is rendered as JSX. In that case the name is taken from either the `dtActionName` prop passed to it (option 1) or the name of the JSX component.
+
 ### React Native Symbolication
 
 Dynatrace can automatically symbolicate JavaScript stack traces captured by the plugin using sourcemaps. This allows you to view human-readable file names, line numbers, and column information in your crash reports.
@@ -1098,6 +1160,7 @@ npx instrumentDynatrace [optional: config=... gradle=... plist=...]
 * `gradle=C:\MyReactAndroidProject\build.gradle`: The location of the root build.gradle file. We will assume that the other gradle file resides in `/app/build.gradle`. This will add the whole agent dependencies automatically for you and will update the configuration.
 * `plist=C:\MyReactIOSProject\projectName\info.plist`: Tell the script where your info.plist file is. The plist file is used for updating the configuration for the agent. 
 * `config=C:\SpecialFolderForDynatrace\dynatrace.config.js`: If you have not got your config file in the root folder of the React Native project but somewhere else.
+* `--reset`: Clear any previously-persisted custom config path and revert the Metro/Babel transformer to the default `dynatrace.config.js` lookup. Useful after switching between build flavors.
 
 If `plist=...` is not provided, the plugin tries to resolve `Info.plist` automatically in this order:
 
@@ -1126,6 +1189,22 @@ Our scripts assumes that the usual React Native project structure is given. The
 * `plist=C:\MyReactIOSProject\projectName\info.plist`: Tell the script where your info.plist file is. The plist file is used for updating the configuration for the agent. 
 * `config=C:\SpecialFolderForDynatrace\dynatrace.config.js`: If you have not got your config file in the root folder of the React Native project but somewhere else.
 
+### DYNATRACE_CONFIG environment variable
+
+As an alternative to `config=`, you can set the `DYNATRACE_CONFIG` environment variable to specify the config file path. This is particularly useful in CI pipelines and Xcode schemes where multiple build flavors each need their own config file, because it does not require changing the instrumentation script — only the environment of the build step.
+
+```
+DYNATRACE_CONFIG=dynatrace.config.prod.js npx instrumentDynatrace
+```
+
+**Precedence (highest to lowest):**
+
+1. `config=` CLI argument — always wins
+2. `DYNATRACE_CONFIG` environment variable
+3. Default `dynatrace.config.js` in the project root
+
+> **Note:** `DYNATRACE_CONFIG` applies to the **Metro/Babel transformer** as well as `npx instrumentDynatrace`. This means you can set it in your Xcode scheme's environment variables to ensure the correct config is used during iOS archive/bundling, independently of what was passed to the instrumentation step.
+
 Examples:
 
  * React Native v0.60.1 or newer:
@@ -1242,8 +1321,9 @@ For more information regarding the differences in the react native versions, ple
 ## Structure of the `dynatrace.js` file
 The configuration is structured in the following way:
 
-```ts
-module.exports = {
+```js
+/** @type {import('@dynatrace/react-native-plugin').DynatraceUserConfiguration} */
+const config = {
     react : {
       // Configuration for React Native instrumentation
     },
@@ -1254,8 +1334,31 @@ module.exports = {
       // Configuration for iOS auto instrumentation
     }
 };
+module.exports = config;
+```
+
+Thanks to the `@type` annotation above, your editor can provide autocomplete and type checking for the configuration. To ensure this works, enable `checkJs` in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "checkJs": true
+  }
+}
+```
+
+If your `tsconfig.json` uses an `include` array, make sure `dynatrace.config.js` is listed — TypeScript ignores files not matched by `include`, even when `checkJs` is enabled:
+
+```json
+{
+  "include": ["**/*.ts", "**/*.tsx", "dynatrace.config.js"]
+}
 ```
 
+
+
+
+
 ### Manual Startup Counterparts
 
 Here is a list of all the counterparts for the options that can be used with a manual startup. Below in the counterparts table you will find an example configuration block for both Android and iOS.
@@ -1339,15 +1442,13 @@ Enables or disables the UI interaction (user interaction) feature. Set to `false
 #### Error Handler
 
 ```js
-module.exports = {
-  // ...
-  react: {
-    errorHandler: {
-      enabled: true,
-      reportFatalErrorAsCrash: true,
-    },
-  }
-};
+react: {
+  errorHandler: {
+    enabled: true,
+    reportFatalErrorAsCrash: true,
+  },
+}
+
 ```
 
 The `enabled` property activates our Error/Crash handler which will insert our handler into your React Native application. This is true per default. 
@@ -1987,6 +2088,31 @@ If you are struggling with a problem, submit a support ticket to Dynatrace (supp
 <br/><br/>
 ## Changelog
 
+2.343.1
+* Updated Android (8.343.1.1038) & iOS Agent (8.343.1.1007)
+* Added User Actions feature
+* Raised minimum platform requirements for Android and iOS
+  * Android API level: 21 → 23
+  * Java: 11 → 17
+  * AGP: 7.0+ → 8.1.1+
+  * iOS SDK: 12 → 15
+* Fixed iOS archive/bundle crash (`ENOENT: no such file or directory`) in projects that use app-specific config files (e.g. `dynatrace.config.prod.js`) instead of the default `dynatrace.config.js` at the repo root. The config resolution code was unconditionally reading the config file before `require()`, causing a hard crash in the Metro/Babel transformer instead of a graceful "config not found" fallback. Discovered via external report from a monorepo setup with multiple build flavors.
+* Fixed custom config path (`config=` argument to `npx instrumentDynatrace`) being lost between build steps: previously, running `npx instrumentDynatrace` without arguments in a subsequent build step (e.g. a generic iOS build phase) would silently delete the persisted custom path, causing Metro bundler to fall back to the hardcoded `dynatrace.config.js` and crash. The custom path is now preserved until explicitly overridden.
+* Added `DYNATRACE_CONFIG` environment variable as an alternative way to specify the config file path for the Metro/Babel transformer.
+* Added `npx instrumentDynatrace --reset` flag to clear a previously-persisted custom config path and revert the Metro/Babel transformer to the default `dynatrace.config.js` lookup. Useful after switching between build flavors that each use a different config file.
+* Fixed incorrect `start_time` on Android app start events when `3rd_gen_enabled` is false. The `EventPipeline` was suppressing the `forwardAppStartEvent` timing-correction call along with all other 3rd-gen events, causing the native Dynatrace SDK to report its own stale process-creation timestamp instead of the actual JS bundle load time.
+
+2.341.1
+* Updated Android (8.341.1.1004) & iOS Agent (8.341.1.1010)
+* Added support for using `dtActionName` prop to customize User Interaction component names
+* Fixed Babel instrumentation not recording start time and duration for User Interaction actions
+* Fixed `React.Fragment` and `Fragment` components being incorrectly instrumented as User Interactions
+* Fixed `config=` build argument being silently ignored when the path contains `=` characters (e.g. `config=$PWD/dynatrace.config.js`) or is an absolute path expanded from `$PWD`
+* Added TypeScript typechecking and autocomplete support in `dynatrace.config.js`
+* Decoupled Session Replay automation from the core React Native SDK on Android; renamed automation components to `ReplayEventTrigger`
+* Updated `@babel/runtime` to latest major version
+* Fixed security vulnerabilities in `ws` and `brace-expansion` dependencies
+
 2.339.1
 * Updated Android (8.339.1.1004) & iOS Agent (8.339.1.1011)
 * Enabled User Interaction Feature by default

package/android/build.gradle

@@ -8,6 +8,14 @@ def isNewArchitectureEnabled() {
     return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
 }
 
+// Build-time master switch for the screenshot self-monitoring (replay metrics) feature.
+// Defaults to enabled; disable for a build with -PdynatraceReplayMetricsEnabled=false
+// (or set dynatraceReplayMetricsEnabled=false in gradle.properties). When false, the monitor is
+// never registered, regardless of the remote `replay_metrics_enabled` flag.
+def isReplayMetricsBuildEnabled() {
+    return !project.hasProperty("dynatraceReplayMetricsEnabled") || project.dynatraceReplayMetricsEnabled == "true"
+}
+
 buildscript {
     repositories {
 		google()
@@ -43,12 +51,13 @@ android {
     }
 
     defaultConfig {
-        minSdkVersion safeExtGet('minSdkVersion', 21)
+        minSdkVersion safeExtGet('minSdkVersion', 23)
         targetSdkVersion safeExtGet('targetSdkVersion', 31)
         versionCode 1
         versionName "1.0"
 
         buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+        buildConfigField "boolean", "REPLAY_METRICS_ENABLED", isReplayMetricsBuildEnabled().toString()
     }
 
     lintOptions {
@@ -72,7 +81,7 @@ repositories {
 }
 
 dependencies {
-	implementation 'com.dynatrace.agent:agent-android:8.339.1.1004'
+	implementation 'com.dynatrace.agent:agent-android:8.343.1.1038'
     implementation "com.facebook.react:react-native:${safeExtGet('reactNative', '+')}"
 }
   

package/android/src/main/java/com/dynatrace/android/agent/DynatraceAppStartModule.kt

@@ -1,6 +1,5 @@
 package com.dynatrace.android.agent
 
-import android.os.SystemClock
 import com.dynatrace.android.agent.model.AppStartMeasurement
 import com.dynatrace.android.agent.model.AppStartMeasurementType
 import com.facebook.react.bridge.Arguments
@@ -31,52 +30,31 @@ private val buffer: Queue<AppStartMeasurement> = ConcurrentLinkedQueue()
  * Setup to register all time points which we want to use to report correct app startup time.
  */
 fun setupAppStartListener() {
-    val initTimestamp = System.currentTimeMillis() - SystemClock.elapsedRealtime();
     ReactMarker.addListener { name: ReactMarkerConstants?, _: String?, _: Int ->
         when (name) {
             ReactMarkerConstants.RELOAD -> {
                 buffer.clear()
-                buffer.add(
-                    AppStartMeasurement(
-                        AppStartMeasurementType.RELOAD.value,
-                        initTimestamp + SystemClock.elapsedRealtime()
-                    )
-                )
+                buffer.add(AppStartMeasurement(AppStartMeasurementType.RELOAD.value, TimeLineProvider.getSystemTime()))
             }
 
-            ReactMarkerConstants.CONTENT_APPEARED -> buffer.add(
-                AppStartMeasurement(
-                    AppStartMeasurementType.CONTENT_APPEARED.value,
-                    initTimestamp + SystemClock.elapsedRealtime()
-                )
-            )
+            ReactMarkerConstants.CONTENT_APPEARED -> {
+                buffer.add(AppStartMeasurement(AppStartMeasurementType.CONTENT_APPEARED.value, TimeLineProvider.getSystemTime()))
+            }
 
             ReactMarkerConstants.DOWNLOAD_END -> buffer.add(
-                AppStartMeasurement(
-                    AppStartMeasurementType.DOWNLOAD_END.value,
-                    initTimestamp + SystemClock.elapsedRealtime()
-                )
+                AppStartMeasurement(AppStartMeasurementType.DOWNLOAD_END.value, TimeLineProvider.getSystemTime())
             )
 
             ReactMarkerConstants.DOWNLOAD_START -> buffer.add(
-                AppStartMeasurement(
-                    AppStartMeasurementType.DOWNLOAD_START.value,
-                    initTimestamp + SystemClock.elapsedRealtime()
-                )
+                AppStartMeasurement(AppStartMeasurementType.DOWNLOAD_START.value, TimeLineProvider.getSystemTime())
             )
 
             ReactMarkerConstants.RUN_JS_BUNDLE_END -> buffer.add(
-                AppStartMeasurement(
-                    AppStartMeasurementType.RUN_JS_BUNDLE_END.value,
-                    initTimestamp + SystemClock.elapsedRealtime()
-                )
+                AppStartMeasurement(AppStartMeasurementType.RUN_JS_BUNDLE_END.value, TimeLineProvider.getSystemTime())
             )
 
             ReactMarkerConstants.RUN_JS_BUNDLE_START -> buffer.add(
-                AppStartMeasurement(
-                    AppStartMeasurementType.RUN_JS_BUNDLE_START.value,
-                    initTimestamp + SystemClock.elapsedRealtime()
-                )
+                AppStartMeasurement(AppStartMeasurementType.RUN_JS_BUNDLE_START.value, TimeLineProvider.getSystemTime())
             )
 
             else -> {
@@ -126,4 +104,4 @@ internal class DynatraceAppStartModule(reactContext: ReactApplicationContext?) :
     override fun getName(): String {
         return APP_START_MODULE
     }
-}
+}

package/android/src/main/java/com/dynatrace/android/agent/DynatraceConfigurationModule.kt

@@ -25,6 +25,7 @@ internal class DynatraceConfigurationModule(reactContext: ReactApplicationContex
     
     init {
         setupInternalListener()
+        reactApplicationContext?.let { ScreenshotSelfMonitor.initialize(it) }
     }
 
     /**

package/android/src/main/java/com/dynatrace/android/agent/DynatraceRNBridgeImpl.kt

@@ -47,7 +47,6 @@ class DynatraceRNBridgeImpl(
     private var hasInternalListener: Boolean = false
     private var listenersCount: Int = 0
 
-
     fun getConstants(): Map<String, Any> {
         return constants;
     }
@@ -309,6 +308,47 @@ class DynatraceRNBridgeImpl(
         HybridBridge.forwardAppStartEvent(JSONObject(DynatraceUtils.toHashMap(attributes)), appStartKeys.toArrayList() as ArrayList<String>)
     }
 
+    fun setAutomaticUserActionDetection(enabled: Boolean) {
+        HybridBridge.setAutomaticUserActionDetection(enabled)
+    }
+
+    fun createUserAction(
+        actionId: String,
+        name: String,
+        completeAutomatically: Boolean,
+        properties: ReadableMap?
+    ) {
+        val jsonProperties = properties?.let {
+            JSONObject(DynatraceUtils.toHashMap(it))
+        }
+        HybridBridge.createUserAction(
+            actionId,
+            name,
+            completeAutomatically,
+            jsonProperties
+        )
+    }
+
+    fun addEventStringPropertyToUserAction(actionId: String, key: String, value: String) {
+        HybridBridge.addEventPropertyToUserAction(actionId, key, value)
+    }
+
+    fun addEventDoublePropertyToUserAction(actionId: String, key: String, value: Double) {
+        HybridBridge.addEventPropertyToUserAction(actionId, key, value)
+    }
+
+    fun addEventBooleanPropertyToUserAction(actionId: String, key: String, value: Boolean) {
+        HybridBridge.addEventPropertyToUserAction(actionId, key, value)
+    }
+
+    fun completeUserAction(actionId: String) {
+        HybridBridge.completeUserAction(actionId)
+    }
+
+    fun setCompleteUserActionAutomatically(actionId: String, enabled: Boolean) {
+        HybridBridge.setCompleteUserActionAutomatically(actionId, enabled)
+    }
+
     fun startView(name: String) {
         Dynatrace.startView(name)
     }

package/android/src/main/java/com/dynatrace/android/agent/DynatraceUtils.kt

@@ -1,6 +1,7 @@
 package com.dynatrace.android.agent
 
 import android.util.Log
+import com.facebook.react.bridge.Dynamic
 import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.ReadableType

package/android/src/main/java/com/dynatrace/android/agent/ScreenshotSelfMonitor.kt

@@ -0,0 +1,175 @@
+package com.dynatrace.android.agent
+
+import android.util.Log
+import com.dynatrace.android.agent.conf.ConfigurationSubscriber
+import com.facebook.react.bridge.LifecycleEventListener
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.UiThreadUtil
+import java.util.concurrent.atomic.AtomicBoolean
+
+private const val TAG = "dtxScreenshotSelfMonitor"
+
+/**
+ * Remote feature-flag key in the cross-platform configuration map that turns screenshot
+ * self-monitoring on. Monitoring is off unless the server delivers this flag as `true`, which keeps
+ * the per-frame UI-change observation dormant for apps where it isn't enabled.
+ */
+private const val CONFIG_KEY_REPLAY_METRICS = "replay_metrics_enabled"
+
+// DEM-26735: replay metrics experiment sunsets on 2026-10-15T00:00:00Z; remove this class after that date.
+private const val EXPERIMENT_EXPIRY_EPOCH_MS = 1_792_022_400_000L
+
+/**
+ * Drives the screenshot self-monitoring feature.
+ *
+ * Responsibilities:
+ *  - Subscribes to the agent configuration and toggles monitoring based on
+ *    [CONFIG_KEY_REPLAY_METRICS].
+ *  - When enabled, registers a [UIChangeScreenshotListener] on the current activity and keeps it
+ *    bound to the foreground activity across the React host lifecycle.
+ *
+ * Threading: configuration is delivered on a background thread, but [ViewTreeObserver][android.view.ViewTreeObserver]
+ * registration must happen on the main thread. All monitoring state ([monitoringEnabled],
+ * [uiChangeListener], [lifecycleListenerRegistered]) is therefore confined to the UI thread —
+ * config toggles are posted there and the host lifecycle callbacks already run there — so no locking
+ * is required.
+ *
+ * A single instance is registered for the lifetime of the React instance via [initialize].
+ */
+internal class ScreenshotSelfMonitor private constructor(
+    private val reactApplicationContext: ReactApplicationContext
+) : LifecycleEventListener, ConfigurationSubscriber {
+
+    private var monitoringEnabled = false
+    private var uiChangeListener: UIChangeScreenshotListener? = null
+    private var lifecycleListenerRegistered = false
+
+    private fun register() {
+        // The publisher immediately notifies us with the current configuration on registration.
+        HybridBridge.addConfigurationSubscriber(this)
+    }
+
+    override fun notify(configuration: Map<String, Any>) {
+        val flagEnabled = configuration[CONFIG_KEY_REPLAY_METRICS] as? Boolean ?: false
+        val enabled = flagEnabled && !isExperimentExpired()
+        if (flagEnabled && !enabled) {
+            Log.d(TAG, "notify: $CONFIG_KEY_REPLAY_METRICS=true but experiment expired — treating as disabled")
+        } else {
+            Log.d(TAG, "notify: $CONFIG_KEY_REPLAY_METRICS = $flagEnabled")
+        }
+        UiThreadUtil.runOnUiThread { setMonitoringEnabled(enabled) }
+    }
+
+    private fun isExperimentExpired(): Boolean =
+        System.currentTimeMillis() >= EXPERIMENT_EXPIRY_EPOCH_MS
+
+    private fun setMonitoringEnabled(enabled: Boolean) {
+        if (enabled == monitoringEnabled) {
+            Log.d(TAG, "setMonitoringEnabled: no change (still $enabled)")
+            return
+        }
+        monitoringEnabled = enabled
+
+        if (enabled) {
+            Log.d(TAG, "$CONFIG_KEY_REPLAY_METRICS enabled — starting screenshot self-monitoring")
+            registerUIChangeListener()
+        } else {
+            Log.d(TAG, "$CONFIG_KEY_REPLAY_METRICS disabled — stopping screenshot self-monitoring")
+            deregisterUIChangeListener()
+        }
+    }
+
+    private fun registerUIChangeListener() {
+        if (uiChangeListener != null) return
+
+        if (!lifecycleListenerRegistered) {
+            reactApplicationContext.addLifecycleEventListener(this)
+            lifecycleListenerRegistered = true
+        }
+
+        val activity = reactApplicationContext.currentActivity
+        if (activity == null) {
+            Log.w(TAG, "No current activity — UIChangeScreenshotListener registration deferred to onHostResume")
+            return
+        }
+
+        val listener = UIChangeScreenshotListener()
+        if (!listener.registerOn(activity)) {
+            Log.w(TAG, "Failed to register OnDrawListener")
+            return
+        }
+        uiChangeListener = listener
+        Log.d(TAG, "UIChangeScreenshotListener registered")
+    }
+
+    private fun deregisterUIChangeListener() {
+        if (lifecycleListenerRegistered) {
+            reactApplicationContext.removeLifecycleEventListener(this)
+            lifecycleListenerRegistered = false
+        }
+        uiChangeListener?.unregister()
+        uiChangeListener = null
+        Log.d(TAG, "UIChangeScreenshotListener deregistered")
+    }
+
+    // Host lifecycle callbacks are delivered on the UI thread.
+    override fun onHostResume() {
+        if (!monitoringEnabled) return
+
+        val activity = reactApplicationContext.currentActivity
+        if (activity == null) {
+            if (uiChangeListener != null) {
+                Log.d(TAG, "onHostResume: no activity, tearing down UIChangeScreenshotListener")
+                deregisterUIChangeListener()
+            }
+            return
+        }
+
+        // Deferred registration: monitoring was enabled before an activity was available
+        if (uiChangeListener == null) {
+            Log.d(TAG, "onHostResume: attempting deferred UIChangeScreenshotListener registration")
+            registerUIChangeListener()
+            return
+        }
+
+        val listener = uiChangeListener ?: return
+        Log.d(TAG, "onHostResume: re-registering UIChangeScreenshotListener on current activity")
+        listener.unregister()
+        if (!listener.registerOn(activity)) {
+            Log.w(TAG, "onHostResume: failed to re-register UIChangeScreenshotListener, tearing down")
+            deregisterUIChangeListener()
+        }
+    }
+
+    override fun onHostPause() {
+        Log.d(TAG, "onHostPause: unregistering UIChangeScreenshotListener")
+        uiChangeListener?.unregister()
+    }
+
+    override fun onHostDestroy() {
+        Log.d(TAG, "onHostDestroy: deregistering UIChangeScreenshotListener")
+        deregisterUIChangeListener()
+    }
+
+    companion object {
+        private val initialized = AtomicBoolean(false)
+
+        /**
+         * Creates and registers the single [ScreenshotSelfMonitor] for the current React instance.
+         * Safe to call multiple times (e.g. from different module init paths / architectures); only
+         * the first call takes effect.
+         */
+        @JvmStatic
+        fun initialize(reactApplicationContext: ReactApplicationContext) {
+            // Build-time master switch (see android/build.gradle isReplayMetricsBuildEnabled()).
+            // When disabled the monitor is never registered, so the remote flag can't turn it on.
+            if (!BuildConfig.REPLAY_METRICS_ENABLED) {
+                Log.d(TAG, "screenshot self-monitoring disabled at build time — not registering")
+                return
+            }
+            if (initialized.compareAndSet(false, true)) {
+                ScreenshotSelfMonitor(reactApplicationContext).register()
+            }
+        }
+    }
+}