feat(screenshot): Add screenshot masking using view hierarchy

CHANGELOG.md

@@ -4,6 +4,23 @@
 
 ### 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 before sending to Sentry
+  - Reuses Session Replay's masking logic; **requires `sentry-android-replay` module at runtime**
+  - To enable masking programmatically:
+    ```kotlin
+    SentryAndroid.init(context) { options ->
+        options.isAttachScreenshot = true
+        options.screenshotOptions.setMaskAllText(true)
+        options.screenshotOptions.setMaskAllImages(true)
+    }
+    ```
+  - 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" />
+    ```
 - Add `installGroupsOverride` parameter and `installGroups` property to Build Distribution SDK ([#5062](https://github.com/getsentry/sentry-java/pull/5062))
 - Update Android targetSdk to API 36 (Android 16) ([#5016](https://github.com/getsentry/sentry-java/pull/5016))
 - Add AndroidManifest support for Spotlight configuration via `io.sentry.spotlight.enable` and `io.sentry.spotlight.url` ([#5064](https://github.com/getsentry/sentry-java/pull/5064))

CLAUDE.md

@@ -127,13 +127,33 @@ 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
 3. Write comprehensive tests
 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'
+```
+
 ## Domain-Specific Knowledge Areas
 
 For complex SDK functionality, refer to the detailed cursor rules in `.cursor/rules/`:

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,28 @@ public ScreenshotEventProcessor(
             DEBOUNCE_WAIT_TIME_MS,
             DEBOUNCE_MAX_EXECUTIONS);
 
+    if (isReplayAvailable) {
+      maskRenderer = new MaskRenderer();
+    }
+
     if (options.isAttachScreenshot()) {
       addIntegrationToSdkVersion("Screenshot");
     }
   }
 
+  private boolean isMaskingEnabled() {
+    if (options.getScreenshotOptions().getMaskViewClasses().isEmpty()) {
+      return false;
+    }
+    if (maskRenderer == null) {
+      options
+          .getLogger()
+          .log(SentryLevel.WARNING, "Screenshot masking requires sentry-android-replay module");
+      return false;
+    }
+    return true;
+  }
+
   @Override
   public @NotNull SentryTransaction process(
       @NotNull SentryTransaction transaction, @NotNull Hint hint) {
@@ -89,25 +115,87 @@ 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) {
+    Bitmap mutableBitmap = screenshot;
+    boolean createdCopy = false;
+    try {
+      // Make bitmap mutable if needed
+      if (!screenshot.isMutable()) {
+        mutableBitmap = screenshot.copy(Bitmap.Config.ARGB_8888, true);
+        if (mutableBitmap == null) {
+          return screenshot;
+        }
+        createdCopy = true;
+      }
+
+      // 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 (createdCopy && !screenshot.isRecycled()) {
+        screenshot.recycle();
+      }
+
+      return mutableBitmap;
+    } catch (Throwable e) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to mask screenshot", e);
+      // Recycle the copy if we created one, to avoid memory leak
+      if (createdCopy && !mutableBitmap.isRecycled()) {
+        mutableBitmap.recycle();
+      }
+      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,53 @@
+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();
+    } else {
+      removeSensitiveViewClasses();
+    }
+  }
+
+  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);
+  }
+
+  private void removeSensitiveViewClasses() {
+    getMaskViewClasses().remove(WEB_VIEW_CLASS_NAME);
+    getMaskViewClasses().remove(VIDEO_VIEW_CLASS_NAME);
+    getMaskViewClasses().remove(ANDROIDX_MEDIA_VIEW_CLASS_NAME);
+    getMaskViewClasses().remove(EXOPLAYER_CLASS_NAME);
+    getMaskViewClasses().remove(EXOPLAYER_STYLED_CLASS_NAME);
+  }
+}