feat(screenshot): Add screenshot masking using view hierarchy (#5077)

* feat(screenshot): Add screenshot masking using view hierarchy

Adds masking support to error screenshots by reusing the Session Replay
masking logic. This allows sensitive content (text, images) to be masked
before attaching screenshots to error events.

- Add SentryMaskingOptions base class for shared masking configuration
- Add SentryScreenshotOptions for screenshot-specific masking settings
- Create MaskRenderer utility for shared mask rendering (used by both
  replay and screenshots)
- Add manifest metadata support for screenshot masking options
- Add snapshot tests with Dropbox Differ library for visual regression
- Update CLAUDE.md with dependency management guidelines

Masking requires the sentry-android-replay module to be present at runtime.
Without it, screenshots are captured without masking.

Refs: #3286

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Changelog

* dontwarn about classes we check via reflection at runtime

* pr id

* fix(screenshot): Only warn about missing replay module when masking is configured

The isMaskingEnabled() method was logging a warning before checking if
masking was actually configured. This caused users who never set up
screenshot masking to see spurious warnings on every event.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(screenshot): Remove sensitive view classes when setMaskAllImages(false) is called

setMaskAllImages(true) was adding WebView, VideoView, and ExoPlayer
classes to maskViewClasses, but setMaskAllImages(false) only removed
ImageView. This caused asymmetric toggle behavior where disabling
image masking didn't restore the original state.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(screenshot): Recycle bitmap copy on masking failure to prevent memory leak

When an exception occurred in applyMasking after creating a mutable
copy of the bitmap, the catch block returned the original screenshot
without recycling the copy. This caused bitmap memory to accumulate
until GC runs, potentially causing OOM issues on frequent errors.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Resolve merge conflicts with main and integrate trackCustomMasking

Move trackCustomMasking() to SentryMaskingOptions as an abstract method
so it can be called polymorphically from replay view hierarchy code.
SentryReplayOptions provides the real implementation, while
SentryScreenshotOptions provides a no-op. Also adds
CAMERAX_PREVIEW_VIEW_CLASS_NAME to SentryMaskingOptions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Clean up slop

* fix(test): Implement abstract trackCustomMasking in test stub

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(screenshot): Use peekDecorView instead of getDecorView

peekDecorView returns null if the decor view hasn't been created yet,
avoiding forced creation. This is consistent with the rest of the
codebase (ScreenshotUtils, ViewHierarchyEventProcessor).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(screenshot): Per-call MaskRenderer, main-thread VH capture, and don't leak unmasked screenshots

- Use per-call MaskRenderer via try-with-resources instead of shared instance
- Remove Closeable from ScreenshotEventProcessor (nothing to clean up)
- Capture view hierarchy on main thread via runOnUiThread + CountDownLatch
- Apply masking on the calling thread (only VH traversal needs main thread)
- Return null on masking failure to avoid sending unmasked screenshots
- Fix setMaskViewContainerClass to not trigger trackCustomMasking

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix tests and remove slop

* clean up

* fix(masking): Remove from opposite set when adding mask/unmask view class

addMaskViewClass now removes from unmaskViewClasses and vice versa,
preventing stale entries from silently blocking masking when
setMaskAllText(false)/setMaskAllImages(false) is called with defaults.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* delegate to super in SentryReplayOptions

* Do not capture screenshot when copy bitmap fails

* fix(screenshot): Recycle bitmaps on all early-return paths to prevent memory leaks

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(screenshot): Log missing replay module warning once in constructor instead of per event

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Move PR id info to AGENTS.md

* refactor: Rename getScreenshotOptions() to getScreenshot() to match getSessionReplay() pattern

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: Move screenshot masking changelog entry to Unreleased with code snippets

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(screenshot): Avoid crash from uncaught exception in view hierarchy traversal and unnecessary bitmap alloc in MaskRenderer.close()

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: Fix MaskRendererTest after lazy bitmap init guard and simplify test setup

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(screenshot): Wrap runOnUiThread in try-catch to handle destroyed activity race condition

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Bail out early if replay module is not available but masking is enabled for screenshots

* fix(test): Expect no screenshot when masking configured without replay module

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: romtsn

AGENTS.md

@@ -144,6 +144,21 @@ The repository is organized into multiple modules:
 4. New features must be **opt-in by default** - extend `SentryOptions` or similar Option classes with getters/setters
 5. Consider backwards compatibility
 
+### Getting PR Information
+
+Use `gh pr view` to get PR details from the current branch. This is needed when adding changelog entries, which require the PR number.
+
+```bash
+# Get PR number for current branch
+gh pr view --json number -q '.number'
+
+# Get PR number for a specific branch
+gh pr view <branch-name> --json number -q '.number'
+
+# Get PR URL
+gh pr view --json url -q '.url'
+```
+
 ## Useful Resources
 
 - Main SDK documentation: https://develop.sentry.dev/sdk/overview/

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+### Features
+
+- Add screenshot masking support using view hierarchy ([#5077](https://github.com/getsentry/sentry-java/pull/5077))
+  - Masks sensitive content (text, images) in error screenshots using the same view hierarchy approach as Session Replay
+  - Requires the `sentry-android-replay` module to be present at runtime for masking to work
+  - Enable via code:
+    ```kotlin
+    SentryAndroid.init(context) { options ->
+        options.isAttachScreenshot = true
+        options.screenshot.setMaskAllText(true)
+        options.screenshot.setMaskAllImages(true)
+        // Or mask specific view classes
+        options.screenshot.addMaskViewClass("com.example.MyCustomView")
+    }
+    ```
+  - Or via `AndroidManifest.xml`:
+    ```xml
+    <meta-data android:name="io.sentry.attach-screenshot" android:value="true" />
+    <meta-data android:name="io.sentry.screenshot.mask-all-text" android:value="true" />
+    <meta-data android:name="io.sentry.screenshot.mask-all-images" android:value="true" />
+    ```
+
 ### Fixes
 
 - Fix crash when unregistering `SystemEventsBroadcastReceiver` with try-catch block. ([#5106](https://github.com/getsentry/sentry-java/pull/5106))

CLAUDE.md

@@ -3,5 +3,4 @@
 ## STOP — Required Reading (Do This First)
 
 Before doing ANYTHING else (including answering questions), you MUST use the Read tool to load [AGENTS.md](AGENTS.md) and follow ALL of its instructions, including reading the required `.cursor/rules/*.mdc` files it references.
-
 Do NOT skip this step. Do NOT proceed without reading these files first.

gradle/libs.versions.toml

@@ -236,3 +236,4 @@ msgpack = { module = "org.msgpack:msgpack-core", version = "0.9.8" }
 okhttp-mockwebserver = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "okhttp" }
 okio = { module = "com.squareup.okio:okio", version = "1.13.0" }
 roboelectric = { module = "org.robolectric:robolectric", version = "4.14" }
+dropbox-differ = { module = "com.dropbox.differ:differ-jvm", version = "0.3.0" }

sentry-android-core/api/sentry-android-core.api

@@ -326,7 +326,7 @@ public final class io/sentry/android/core/NetworkBreadcrumbsIntegration : io/sen
 }
 
 public final class io/sentry/android/core/ScreenshotEventProcessor : io/sentry/EventProcessor {
-	public fun <init> (Lio/sentry/android/core/SentryAndroidOptions;Lio/sentry/android/core/BuildInfoProvider;)V
+	public fun <init> (Lio/sentry/android/core/SentryAndroidOptions;Lio/sentry/android/core/BuildInfoProvider;Z)V
 	public fun getOrder ()Ljava/lang/Long;
 	public fun process (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Lio/sentry/SentryEvent;
 	public fun process (Lio/sentry/protocol/SentryTransaction;Lio/sentry/Hint;)Lio/sentry/protocol/SentryTransaction;
@@ -354,6 +354,7 @@ public final class io/sentry/android/core/SentryAndroidOptions : io/sentry/Sentr
 	public fun getFrameMetricsCollector ()Lio/sentry/android/core/internal/util/SentryFrameMetricsCollector;
 	public fun getNativeSdkName ()Ljava/lang/String;
 	public fun getNdkHandlerStrategy ()I
+	public fun getScreenshot ()Lio/sentry/android/core/SentryScreenshotOptions;
 	public fun getStartupCrashDurationThresholdMillis ()J
 	public fun isAnrEnabled ()Z
 	public fun isAnrReportInDebug ()Z
@@ -450,6 +451,12 @@ public final class io/sentry/android/core/SentryPerformanceProvider {
 	public fun shutdown ()V
 }
 
+public final class io/sentry/android/core/SentryScreenshotOptions : io/sentry/SentryMaskingOptions {
+	public fun <init> ()V
+	public fun setMaskAllImages (Z)V
+	public fun trackCustomMasking ()V
+}
+
 public class io/sentry/android/core/SentryUserFeedbackButton : android/widget/Button {
 	public fun <init> (Landroid/content/Context;)V
 	public fun <init> (Landroid/content/Context;Landroid/util/AttributeSet;)V

sentry-android-core/build.gradle.kts

@@ -108,6 +108,7 @@ dependencies {
   testImplementation(projects.sentryAndroidReplay)
   testImplementation(projects.sentryCompose)
   testImplementation(projects.sentryAndroidNdk)
+  testImplementation(libs.dropbox.differ)
   testRuntimeOnly(libs.androidx.compose.ui)
   testRuntimeOnly(libs.androidx.fragment.ktx)
   testRuntimeOnly(libs.timber)

sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java

@@ -188,7 +188,8 @@ static void initializeIntegrationsAndProcessors(
     options.addEventProcessor(
         new DefaultAndroidEventProcessor(context, buildInfoProvider, options));
     options.addEventProcessor(new PerformanceAndroidEventProcessor(options, activityFramesTracker));
-    options.addEventProcessor(new ScreenshotEventProcessor(options, buildInfoProvider));
+    options.addEventProcessor(
+        new ScreenshotEventProcessor(options, buildInfoProvider, isReplayAvailable));
     options.addEventProcessor(new ViewHierarchyEventProcessor(options));
     options.addEventProcessor(
         new ApplicationExitInfoEventProcessor(context, options, buildInfoProvider));

sentry-android-core/src/main/java/io/sentry/android/core/ManifestMetadataReader.java

@@ -170,6 +170,10 @@ final class ManifestMetadataReader {
 
   static final String SPOTLIGHT_CONNECTION_URL = "io.sentry.spotlight.url";
 
+  static final String SCREENSHOT_MASK_ALL_TEXT = "io.sentry.screenshot.mask-all-text";
+
+  static final String SCREENSHOT_MASK_ALL_IMAGES = "io.sentry.screenshot.mask-all-images";
+
   /** ManifestMetadataReader ctor */
   private ManifestMetadataReader() {}
 
@@ -659,6 +663,14 @@ static void applyMetadata(
         if (spotlightUrl != null) {
           options.setSpotlightConnectionUrl(spotlightUrl);
         }
+
+        // Screenshot masking options (default to false for backwards compatibility)
+        options
+            .getScreenshot()
+            .setMaskAllText(readBool(metadata, logger, SCREENSHOT_MASK_ALL_TEXT, false));
+        options
+            .getScreenshot()
+            .setMaskAllImages(readBool(metadata, logger, SCREENSHOT_MASK_ALL_IMAGES, false));
       }
       options
           .getLogger()

sentry-android-core/src/main/java/io/sentry/android/core/ScreenshotEventProcessor.java

@@ -6,6 +6,7 @@
 
 import android.app.Activity;
 import android.graphics.Bitmap;
+import android.view.View;
 import io.sentry.Attachment;
 import io.sentry.EventProcessor;
 import io.sentry.Hint;
@@ -14,9 +15,16 @@
 import io.sentry.android.core.internal.util.AndroidCurrentDateProvider;
 import io.sentry.android.core.internal.util.Debouncer;
 import io.sentry.android.core.internal.util.ScreenshotUtils;
+import io.sentry.android.replay.util.MaskRenderer;
+import io.sentry.android.replay.util.ViewsKt;
+import io.sentry.android.replay.viewhierarchy.ViewHierarchyNode;
 import io.sentry.protocol.SentryTransaction;
 import io.sentry.util.HintUtils;
 import io.sentry.util.Objects;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicReference;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -34,10 +42,15 @@ public final class ScreenshotEventProcessor implements EventProcessor {
   private final @NotNull Debouncer debouncer;
   private static final long DEBOUNCE_WAIT_TIME_MS = 2000;
   private static final int DEBOUNCE_MAX_EXECUTIONS = 3;
+  private static final long MASKING_TIMEOUT_MS = 2000;
+
+  private final boolean isReplayAvailable;
+  private final AtomicBoolean isReplayModuleAbsenceLogged = new AtomicBoolean(false);
 
   public ScreenshotEventProcessor(
       final @NotNull SentryAndroidOptions options,
-      final @NotNull BuildInfoProvider buildInfoProvider) {
+      final @NotNull BuildInfoProvider buildInfoProvider,
+      final boolean isReplayAvailable) {
     this.options = Objects.requireNonNull(options, "SentryAndroidOptions is required");
     this.buildInfoProvider =
         Objects.requireNonNull(buildInfoProvider, "BuildInfoProvider is required");
@@ -47,11 +60,17 @@ public ScreenshotEventProcessor(
             DEBOUNCE_WAIT_TIME_MS,
             DEBOUNCE_MAX_EXECUTIONS);
 
+    this.isReplayAvailable = isReplayAvailable;
+
     if (options.isAttachScreenshot()) {
       addIntegrationToSdkVersion("Screenshot");
     }
   }
 
+  private boolean isMaskingEnabled() {
+    return !options.getScreenshot().getMaskViewClasses().isEmpty() && isReplayAvailable;
+  }
+
   @Override
   public @NotNull SentryTransaction process(
       @NotNull SentryTransaction transaction, @NotNull Hint hint) {
@@ -71,6 +90,15 @@ public ScreenshotEventProcessor(
 
       return event;
     }
+    if (!isReplayAvailable && !options.getScreenshot().getMaskViewClasses().isEmpty()) {
+      if (!isReplayModuleAbsenceLogged.getAndSet(true)) {
+        options
+            .getLogger()
+            .log(SentryLevel.WARNING, "Screenshot masking requires sentry-android-replay module");
+      }
+      return event;
+    }
+
     final @Nullable Activity activity = CurrentActivityHolder.getInstance().getActivity();
     if (activity == null || HintUtils.isFromHybridSdk(hint)) {
       return event;
@@ -89,23 +117,135 @@ public ScreenshotEventProcessor(
       return event;
     }
 
-    final Bitmap screenshot =
+    Bitmap screenshot =
         captureScreenshot(
             activity, options.getThreadChecker(), options.getLogger(), buildInfoProvider);
     if (screenshot == null) {
       return event;
     }
 
+    // Apply masking if enabled and replay module is available
+    if (isMaskingEnabled()) {
+      final @Nullable ViewHierarchyNode rootNode = captureViewHierarchy(activity);
+      if (rootNode == null) {
+        screenshot.recycle();
+        return event;
+      }
+      final @Nullable Bitmap masked = applyMasking(screenshot, rootNode);
+      if (masked == null) {
+        // applyMasking already recycles its bitmaps on failure
+        return event;
+      }
+      screenshot = masked;
+    }
+
+    final Bitmap finalScreenshot = screenshot;
     hint.setScreenshot(
         Attachment.fromByteProvider(
-            () -> ScreenshotUtils.compressBitmapToPng(screenshot, options.getLogger()),
+            () -> ScreenshotUtils.compressBitmapToPng(finalScreenshot, options.getLogger()),
             "screenshot.png",
             "image/png",
             false));
     hint.set(ANDROID_ACTIVITY, activity);
     return event;
   }
 
+  /**
+   * Captures the view hierarchy on the main thread, since view traversal requires it. If already on
+   * the main thread, captures directly; otherwise posts to the main thread and waits.
+   */
+  private @Nullable ViewHierarchyNode captureViewHierarchy(final @NotNull Activity activity) {
+    if (options.getThreadChecker().isMainThread()) {
+      return buildViewHierarchy(activity);
+    }
+
+    final AtomicReference<ViewHierarchyNode> result = new AtomicReference<>(null);
+    final CountDownLatch latch = new CountDownLatch(1);
+
+    try {
+      activity.runOnUiThread(
+          () -> {
+            try {
+              result.set(buildViewHierarchy(activity));
+            } finally {
+              latch.countDown();
+            }
+          });
+
+      if (!latch.await(MASKING_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+        options
+            .getLogger()
+            .log(
+                SentryLevel.WARNING, "Timed out waiting for view hierarchy capture on main thread");
+        return null;
+      }
+    } catch (Throwable e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to capture view hierarchy", e);
+      return null;
+    }
+
+    return result.get();
+  }
+
+  private @Nullable ViewHierarchyNode buildViewHierarchy(final @NotNull Activity activity) {
+    try {
+      final @Nullable View rootView =
+          activity.getWindow() != null
+                  && activity.getWindow().peekDecorView() != null
+                  && activity.getWindow().peekDecorView().getRootView() != null
+              ? activity.getWindow().peekDecorView().getRootView()
+              : null;
+      if (rootView == null) {
+        return null;
+      }
+
+      final ViewHierarchyNode rootNode =
+          ViewHierarchyNode.Companion.fromView(rootView, null, 0, options.getScreenshot());
+      ViewsKt.traverse(rootView, rootNode, options.getScreenshot(), options.getLogger());
+      return rootNode;
+    } catch (Throwable e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to build view hierarchy", e);
+      return null;
+    }
+  }
+
+  private @Nullable Bitmap applyMasking(
+      final @NotNull Bitmap screenshot, final @NotNull ViewHierarchyNode rootNode) {
+    Bitmap mutableBitmap = screenshot;
+    boolean createdCopy = false;
+    try (final MaskRenderer maskRenderer = new MaskRenderer()) {
+      // Make bitmap mutable if needed
+      if (!screenshot.isMutable()) {
+        mutableBitmap = screenshot.copy(Bitmap.Config.ARGB_8888, true);
+        if (mutableBitmap == null) {
+          screenshot.recycle();
+          return null;
+        }
+        createdCopy = true;
+      }
+
+      maskRenderer.renderMasks(mutableBitmap, rootNode, null);
+
+      // Recycle original if we created a copy
+      if (createdCopy && !screenshot.isRecycled()) {
+        screenshot.recycle();
+      }
+
+      return mutableBitmap;
+    } catch (Throwable e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to mask screenshot", e);
+      if (createdCopy) {
+        if (!mutableBitmap.isRecycled()) {
+          mutableBitmap.recycle();
+        }
+      }
+      if (!screenshot.isRecycled()) {
+        screenshot.recycle();
+      }
+      return null;
+    }
+  }
+
   @Override
   public @Nullable Long getOrder() {
     return 10000L;

sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroidOptions.java

@@ -243,6 +243,15 @@ public interface BeforeCaptureCallback {
 
   private boolean enableTombstone = false;
 
+  /**
+   * Screenshot masking options. Configure which views should be masked when capturing screenshots
+   * on error events.
+   *
+   * <p>Note: Screenshot masking requires the {@code sentry-android-replay} module to be present at
+   * runtime. If the replay module is not available, screenshots will be captured without masking.
+   */
+  private final @NotNull SentryScreenshotOptions screenshot = new SentryScreenshotOptions();
+
   public SentryAndroidOptions() {
     setSentryClientName(BuildConfig.SENTRY_ANDROID_SDK_NAME + "/" + BuildConfig.VERSION_NAME);
     setSdkVersion(createSdkVersion());
@@ -677,6 +686,15 @@ public void setEnableSystemEventBreadcrumbsExtras(
     this.enableSystemEventBreadcrumbsExtras = enableSystemEventBreadcrumbsExtras;
   }
 
+  /**
+   * Returns the screenshot masking options.
+   *
+   * @return the screenshot masking options
+   */
+  public @NotNull SentryScreenshotOptions getScreenshot() {
+    return screenshot;
+  }
+
   static class AndroidUserFeedbackIDialogHandler implements SentryFeedbackOptions.IDialogHandler {
     @Override
     public void showDialog(