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>

Author: romtsn

CLAUDE.md

@@ -127,6 +127,11 @@ The repository is organized into multiple modules:
 - System tests validate end-to-end functionality with sample applications
 - Coverage reports are generated for both JaCoCo (Java/Android) and Kover (KMP modules)
 
+### Dependency Management
+- All dependencies must be declared in `gradle/libs.versions.toml` (Gradle version catalog)
+- Reference dependencies in build files using the `libs.` accessor (e.g., `libs.dropbox.differ`)
+- Never hardcode version strings directly in `build.gradle.kts` files
+
 ### Contributing Guidelines
 1. Follow existing code style and language
 2. Do not modify API files (e.g. sentry.api) manually - run `./gradlew apiDump` to regenerate them

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

@@ -312,8 +312,9 @@ public final class io/sentry/android/core/NetworkBreadcrumbsIntegration : io/sen
 	public fun register (Lio/sentry/IScopes;Lio/sentry/SentryOptions;)V
 }
 
-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 final class io/sentry/android/core/ScreenshotEventProcessor : io/sentry/EventProcessor, java/io/Closeable {
+	public fun <init> (Lio/sentry/android/core/SentryAndroidOptions;Lio/sentry/android/core/BuildInfoProvider;Z)V
+	public fun close ()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;
@@ -341,6 +342,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 getScreenshotOptions ()Lio/sentry/android/core/SentryScreenshotOptions;
 	public fun getStartupCrashDurationThresholdMillis ()J
 	public fun isAnrEnabled ()Z
 	public fun isAnrReportInDebug ()Z
@@ -437,6 +439,11 @@ 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 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

@@ -168,6 +168,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() {}
 
@@ -655,6 +659,14 @@ static void applyMetadata(
         if (spotlightUrl != null) {
           options.setSpotlightConnectionUrl(spotlightUrl);
         }
+
+        // Screenshot masking options (default to false for backwards compatibility)
+        options
+            .getScreenshotOptions()
+            .setMaskAllText(readBool(metadata, logger, SCREENSHOT_MASK_ALL_TEXT, false));
+        options
+            .getScreenshotOptions()
+            .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,14 @@
 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.io.Closeable;
+import java.io.IOException;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -26,7 +32,7 @@
  * captured.
  */
 @ApiStatus.Internal
-public final class ScreenshotEventProcessor implements EventProcessor {
+public final class ScreenshotEventProcessor implements EventProcessor, Closeable {
 
   private final @NotNull SentryAndroidOptions options;
   private final @NotNull BuildInfoProvider buildInfoProvider;
@@ -35,9 +41,12 @@ public final class ScreenshotEventProcessor implements EventProcessor {
   private static final long DEBOUNCE_WAIT_TIME_MS = 2000;
   private static final int DEBOUNCE_MAX_EXECUTIONS = 3;
 
+  private @Nullable MaskRenderer maskRenderer = null;
+
   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 +56,25 @@ public ScreenshotEventProcessor(
             DEBOUNCE_WAIT_TIME_MS,
             DEBOUNCE_MAX_EXECUTIONS);
 
+    if (isReplayAvailable) {
+      maskRenderer = new MaskRenderer();
+    }
+
     if (options.isAttachScreenshot()) {
       addIntegrationToSdkVersion("Screenshot");
     }
   }
 
+  private boolean isMaskingEnabled() {
+    if (maskRenderer == null) {
+      options
+          .getLogger()
+          .log(SentryLevel.WARNING, "Screenshot masking requires sentry-android-replay module");
+      return false;
+    }
+    return !options.getScreenshotOptions().getMaskViewClasses().isEmpty();
+  }
+
   @Override
   public @NotNull SentryTransaction process(
       @NotNull SentryTransaction transaction, @NotNull Hint hint) {
@@ -89,25 +112,81 @@ 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 View rootView =
+          activity.getWindow() != null
+                  && activity.getWindow().getDecorView() != null
+                  && activity.getWindow().getDecorView().getRootView() != null
+              ? activity.getWindow().getDecorView().getRootView()
+              : null;
+      if (rootView != null) {
+        screenshot = applyMasking(screenshot, rootView);
+      }
+    }
+
+    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;
   }
 
+  private @NotNull Bitmap applyMasking(
+      final @NotNull Bitmap screenshot, final @NotNull View rootView) {
+    try {
+      // Make bitmap mutable if needed
+      Bitmap mutableBitmap = screenshot;
+      if (!screenshot.isMutable()) {
+        mutableBitmap = screenshot.copy(Bitmap.Config.ARGB_8888, true);
+        if (mutableBitmap == null) {
+          return screenshot;
+        }
+      }
+
+      // we can access it here, since it's "internal" only for Kotlin
+
+      // Build view hierarchy and apply masks
+      final ViewHierarchyNode rootNode =
+          ViewHierarchyNode.Companion.fromView(rootView, null, 0, options.getScreenshotOptions());
+      ViewsKt.traverse(rootView, rootNode, options.getScreenshotOptions(), options.getLogger());
+
+      if (maskRenderer != null) {
+        maskRenderer.renderMasks(mutableBitmap, rootNode, null);
+      }
+
+      // Recycle original if we created a copy
+      if (mutableBitmap != screenshot && !screenshot.isRecycled()) {
+        screenshot.recycle();
+      }
+
+      return mutableBitmap;
+    } catch (Throwable e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to mask screenshot", e);
+      return screenshot;
+    }
+  }
+
   @Override
   public @Nullable Long getOrder() {
     return 10000L;
   }
+
+  @Override
+  public void close() throws IOException {
+    if (maskRenderer != null) {
+      maskRenderer.close();
+    }
+  }
 }

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 screenshotOptions = new SentryScreenshotOptions();
+
   public SentryAndroidOptions() {
     setSentryClientName(BuildConfig.SENTRY_ANDROID_SDK_NAME + "/" + BuildConfig.VERSION_NAME);
     setSdkVersion(createSdkVersion());
@@ -681,6 +690,15 @@ public void setEnableSystemEventBreadcrumbsExtras(
     this.enableSystemEventBreadcrumbsExtras = enableSystemEventBreadcrumbsExtras;
   }
 
+  /**
+   * Returns the screenshot masking options.
+   *
+   * @return the screenshot masking options
+   */
+  public @NotNull SentryScreenshotOptions getScreenshotOptions() {
+    return screenshotOptions;
+  }
+
   static class AndroidUserFeedbackIDialogHandler implements SentryFeedbackOptions.IDialogHandler {
     @Override
     public void showDialog(

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

@@ -0,0 +1,43 @@
+package io.sentry.android.core;
+
+import io.sentry.SentryMaskingOptions;
+
+/**
+ * Screenshot masking options for error screenshots. Extends the base {@link SentryMaskingOptions}
+ * with screenshot-specific defaults.
+ *
+ * <p>By default, masking is disabled for screenshots. Enable masking by calling {@link
+ * #setMaskAllText(boolean)} and/or {@link #setMaskAllImages(boolean)}.
+ *
+ * <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.
+ */
+public final class SentryScreenshotOptions extends SentryMaskingOptions {
+
+  public SentryScreenshotOptions() {
+    // Default to NO masking until next major version.
+    // maskViewClasses starts empty, so nothing is masked by default.
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * <p>When enabling image masking for screenshots, this also adds masking for WebView, VideoView,
+   * and media player views (ExoPlayer, Media3) since they may contain sensitive content.
+   */
+  @Override
+  public void setMaskAllImages(final boolean maskAllImages) {
+    super.setMaskAllImages(maskAllImages);
+    if (maskAllImages) {
+      addSensitiveViewClasses();
+    }
+  }
+
+  private void addSensitiveViewClasses() {
+    addMaskViewClass(WEB_VIEW_CLASS_NAME);
+    addMaskViewClass(VIDEO_VIEW_CLASS_NAME);
+    addMaskViewClass(ANDROIDX_MEDIA_VIEW_CLASS_NAME);
+    addMaskViewClass(EXOPLAYER_CLASS_NAME);
+    addMaskViewClass(EXOPLAYER_STYLED_CLASS_NAME);
+  }
+}