feat(android): update session replay masking precedence rules (#518)

## Summary

Changes Android semantics to match iOS when applying session replay
masking precedence rules.

This changes existing masking behavior, but should be clearer than the
previous behavior. Please see the README changes for details.

## How did you test this change?

Unit tests added.

## Are there any deployment considerations?

N/A

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes core session replay privacy behavior by introducing explicit
mask/unmask precedence and propagation, which could affect what gets
redacted in recordings. Risk is mitigated by added unit tests but still
impacts sensitive-data handling paths.
> 
> **Overview**
> Aligns Android session replay masking with a new **explicit precedence
model**: *explicit mask* (including `ldMask()` and `maskXMLViewIds`)
propagates to descendants and overrides everything, *explicit unmask*
(`ldUnmask()`) propagates but cannot override an explicit mask, and
*global privacy rules* (e.g. `maskTextInputs`, `maskText`,
`maskWebViews`) only apply when no explicit signal exists.
> 
> Implements this by splitting `PrivacyProfile` matchers into
`explicitMaskMatchers` vs `globalMaskMatchers`, extending `MaskTarget`
with `hasLDUnmask`, updating `MaskCollector` traversal to carry
inherited explicit state, and wiring `ImageCaptureService` to pass both
matcher sets. Adds focused tests for the new precedence rules and
updates docs/comments to match; the React Native adapter also switches
Observability logging to `LDObserveLogging.adapter()`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d7e05f1. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: beekld

sdk/@launchdarkly/observability-android/README.md

@@ -244,6 +244,19 @@ Call `LDReplay.stop()` to pause recording.
 
 Use `ldMask()` to mark views that should be masked in session replay. There are helpers for both XML-based Views and Jetpack Compose.
 
+##### How the SDK Determines What to Mask
+
+When deciding whether a specific view should be masked in a Session Replay, the SDK evaluates rules in a strict order of precedence. It checks these conditions from top to bottom and stops at the first one that applies:
+
+1. **Explicit Masking (Highest Priority)**: Is the view, or *any* of its parent views, explicitly masked (e.g., using `.ldMask()` or matching `maskXMLViewIds`)?
+   * **Yes**: The view is **masked**. This overrides all other rules.
+2. **Explicit Unmasking**: Is the view, or *any* of its parent views, explicitly unmasked (e.g., using `.ldUnmask()`)?
+   * **Yes**: The view is **unmasked**.
+3. **Global Configuration**: Does your global privacy configuration (like `maskTextInputs`, `maskImages`, etc.) apply to this view?
+   * **Yes**: The view follows the global configuration.
+
+*Note: If multiple rules conflict at the same level, masking wins over unmasking.*
+
 ##### Configure masking via `PrivacyProfile`
 
 If you want to configure masking globally (instead of calling `ldMask()` on each element), pass a `PrivacyProfile` to `ReplayOptions`:
@@ -322,7 +335,7 @@ override fun onCreateView(
 }
 ```
 
-Optional: use `ldUnmask()` to explicitly clear masking on a view you previously masked.
+Use `ldUnmask()` to explicitly opt a view out of masking. This overrides global masking rules (e.g. `maskText`) for the view and its descendants — but an explicit `ldMask()` on the view itself or any ancestor still wins.
 
 ##### Jetpack Compose
 
@@ -348,7 +361,7 @@ fun CreditCardField() {
 }
 ```
 
-Optional: use `Modifier.ldUnmask()` to explicitly clear masking on a composable you previously masked.
+Use `Modifier.ldUnmask()` to explicitly opt a composable out of masking. This overrides global masking rules (e.g. `maskText`) for the composable and its descendants — but an explicit `ldMask()` on the composable itself or any ancestor still wins.
 
 Notes:
 - Masking marks elements so their contents are obscured in recorded sessions.

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/api/ComposeMaskingAPI.kt

@@ -16,14 +16,18 @@ val LdMaskSemanticsKey = SemanticsPropertyKey<Boolean>("ld_mask")
 var SemanticsPropertyReceiver.ldMask by LdMaskSemanticsKey
 
 /**
- * Marks this Compose element as sensitive; session replay should mask it.
+ * Marks this Compose element — and every descendant of it — as sensitive for masking in session
+ * replay.
  */
 fun Modifier.ldMask(): Modifier = this.semantics {
     ldMask = true
 }
 
 /**
- * Marks this Compose element as not sensitive; session replay should not mask it.
+ * Marks this Compose element — and every descendant of it — as explicitly *not* sensitive for
+ * masking in session replay. This overrides global masking rules such as `maskText` and
+ * `maskTextInputs` for the affected elements. If this element or one of its ancestors is also
+ * explicitly masked via [ldMask], the explicit mask wins.
  */
 fun Modifier.ldUnmask(): Modifier = this.semantics {
     ldMask = false

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/api/MaskingViewAPI.kt

@@ -3,16 +3,18 @@ import android.view.View
 import com.launchdarkly.observability.R
 
 /**
- * Marks this native View as sensitive for masking in session replay.
- * Sets a tag so the replay system can detect and apply masking.
+ * Marks this native View — and every descendant of it — as sensitive for masking in session
+ * replay.
  */
 fun View.ldMask() {
     setTag(R.id.ld_mask_tag, true)
 }
 
 /**
- * Unmarks this native View as sensitive for masking in session replay.
- * Sets a tag so the replay system will not mask this view.
+ * Marks this native View — and every descendant of it — as explicitly *not* sensitive for
+ * masking in session replay. This overrides global masking rules such as `maskText` and
+ * `maskTextInputs` for the affected views. If this view or one of its ancestors is also
+ * explicitly masked via [ldMask], the explicit mask wins.
  */
 fun View.ldUnmask() {
     setTag(R.id.ld_mask_tag, false)

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/replay/PrivacyProfile.kt

@@ -49,22 +49,6 @@ data class PrivacyProfile(
         }
     }.toSet()
 
-    /**
-     * Converts this [PrivacyProfile] into its equivalent [MaskMatcher] list.
-     *
-     * Note: matchers are evaluated with `any { ... }`, so ordering only affects performance
-     * (earlier matchers can short-circuit later ones).
-     */
-    internal fun asMatchersList(): List<MaskMatcher> = buildList {
-        // Prefer cheaper checks first; heavier checks should be later.
-        if (maskTextInputs) add(textInputMatcher)
-        if (maskText) add(textMatcher)
-        if (viewClassSet.isNotEmpty()) add(viewsMatcher)
-        if (maskXMLViewIdSet.isNotEmpty()) add(xmlViewIdsMatcher)
-        if (maskBySemanticsKeywords) add(sensitiveMatcher)
-        if (webViewClassNameSet.isNotEmpty()) add(webViewClassHierarchyMatcher)
-    }
-
     /**
      * Matches targets whose underlying Android View has an exact class match with [maskViews].
      *
@@ -140,6 +124,40 @@ data class PrivacyProfile(
         }
     }
 
+    /**
+     * Matchers whose match counts as an "explicit" masking signal — equivalent to a call to
+     * `View.ldMask()` on the matched view. An explicit-mask match propagates to descendants per
+     * the precedence rules in `MaskCollector`.
+     *
+     * Identifier-based matchers belong here (the developer named a specific view to mask).
+     * Type-based / heuristic matchers belong in [globalMaskMatchers].
+     *
+     * Matchers are evaluated with `any { ... }`, so ordering only affects performance (earlier
+     * matchers can short-circuit later ones).
+     */
+    internal val explicitMaskMatchers: List<MaskMatcher> = buildList {
+        if (maskXMLViewIdSet.isNotEmpty()) add(xmlViewIdsMatcher)
+    }
+
+    /**
+     * Matchers whose match applies only to the matched view itself: a global match does not
+     * propagate to descendants and does not override an explicit unmask.
+     *
+     * Type-based / heuristic matchers belong here (the developer asked to mask all views *of a
+     * kind*, not specific ones). Identifier-based matchers belong in [explicitMaskMatchers].
+     *
+     * Matchers are evaluated with `any { ... }`, so ordering only affects performance (earlier
+     * matchers can short-circuit later ones).
+     */
+    internal val globalMaskMatchers: List<MaskMatcher> = buildList {
+        // Prefer cheaper checks first; heavier checks should be later.
+        if (maskTextInputs) add(textInputMatcher)
+        if (maskText) add(textMatcher)
+        if (viewClassSet.isNotEmpty()) add(viewsMatcher)
+        if (maskBySemanticsKeywords) add(sensitiveMatcher)
+        if (webViewClassNameSet.isNotEmpty()) add(webViewClassHierarchyMatcher)
+    }
+
     // this list of sensitive keywords is used to detect sensitive content descriptions
     private val sensitiveKeywords = listOf(
         "sensitive",

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/replay/capture/ImageCaptureService.kt

@@ -46,7 +46,8 @@ class ImageCaptureService(
     private val windowInspector = WindowInspector(logger)
     private val maskCollector = MaskCollector(logger)
     private val maskApplier = MaskApplier()
-    private val maskMatchers = options.privacyProfile.asMatchersList()
+    private val explicitMaskMatchers = options.privacyProfile.explicitMaskMatchers
+    private val globalMaskMatchers = options.privacyProfile.globalMaskMatchers
 
     suspend fun captureRawFrame(): RawFrame? =
         withContext(DispatcherProviderHolder.current.main) {
@@ -175,13 +176,15 @@ class ImageCaptureService(
 
     private fun collectMasks(capturingWindowEntries: List<WindowEntry>): MutableList<List<Mask>?> {
         return capturingWindowEntries.map {
-            maskCollector.collectMasks(it.rootView, maskMatchers)
+            maskCollector.collectMasks(it.rootView, explicitMaskMatchers, globalMaskMatchers)
         }.toMutableList()
     }
 
     private fun collectMasksFromResults(captureResults: List<CaptureResult?>): MutableList<List<Mask>?> {
         return captureResults.map { result ->
-            result?.windowEntry?.rootView?.let { rv -> maskCollector.collectMasks(rv, maskMatchers) }
+            result?.windowEntry?.rootView?.let { rv ->
+                maskCollector.collectMasks(rv, explicitMaskMatchers, globalMaskMatchers)
+            }
         }.toMutableList()
     }
 

sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/replay/masking/ComposeMaskTarget.kt

@@ -89,6 +89,10 @@ data class ComposeMaskTarget(
         return config.getOrNull(LdMaskSemanticsKey) == true
     }
 
+    override fun hasLDUnmask(): Boolean {
+        return config.getOrNull(LdMaskSemanticsKey) == false
+    }
+
     override fun isSensitive(sensitiveKeywords: List<String>): Boolean {
         if (config.contains(SemanticsProperties.Password)) return true