From d1a9c4566b288f839395b558d996e612306fc802 Mon Sep 17 00:00:00 2001
From: Markus Hintersteiner <markus.hintersteiner@sentry.io>
Date: Fri, 25 Apr 2025 10:07:47 +0200
Subject: [PATCH 1/9] Add masking debug overlay

---
 .../android/replay/ScreenshotRecorder.kt      | 24 +++++++
 .../replay/util/DebugOverlayDrawable.kt       | 66 +++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt

diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
index 39ad176c8d1..0a406094a72 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
@@ -1,5 +1,6 @@
 package io.sentry.android.replay
 
+import android.annotation.SuppressLint
 import android.annotation.TargetApi
 import android.content.Context
 import android.graphics.Bitmap
@@ -21,6 +22,7 @@ import io.sentry.SentryLevel.INFO
 import io.sentry.SentryLevel.WARNING
 import io.sentry.SentryOptions
 import io.sentry.SentryReplayOptions
+import io.sentry.android.replay.util.DebugOverlayDrawable
 import io.sentry.android.replay.util.MainLooperHandler
 import io.sentry.android.replay.util.addOnDrawListenerSafe
 import io.sentry.android.replay.util.getVisibleRects
@@ -37,6 +39,7 @@ import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.LazyThreadSafetyMode.NONE
 import kotlin.math.roundToInt
 
+@SuppressLint("UseKtx")
 @TargetApi(26)
 internal class ScreenshotRecorder(
     val config: ScreenshotRecorderConfig,
@@ -46,6 +49,10 @@ internal class ScreenshotRecorder(
     private val screenshotRecorderCallback: ScreenshotRecorderCallback?
 ) : ViewTreeObserver.OnDrawListener {
 
+    private companion object {
+        private const val DEBUG_MODE = false
+    }
+
     private var rootView: WeakReference<View>? = null
     private val maskingPaint by lazy(NONE) { Paint() }
     private val singlePixelBitmap: Bitmap by lazy(NONE) {
@@ -70,6 +77,8 @@ internal class ScreenshotRecorder(
     private val isCapturing = AtomicBoolean(true)
     private val lastCaptureSuccessful = AtomicBoolean(false)
 
+    private val debugOverlayDrawable = DebugOverlayDrawable()
+
     fun capture() {
         if (!isCapturing.get()) {
             if (options.sessionReplay.isDebug) {
@@ -121,6 +130,8 @@ internal class ScreenshotRecorder(
                         root.traverse(viewHierarchy, options)
 
                         recorder.submitSafely(options, "screenshot_recorder.mask") {
+                            val debugMasks = mutableListOf<Rect>()
+
                             val canvas = Canvas(screenshot)
                             canvas.setMatrix(prescaledMatrix)
                             viewHierarchy.traverse { node ->
@@ -158,10 +169,16 @@ internal class ScreenshotRecorder(
                                     visibleRects.forEach { rect ->
                                         canvas.drawRoundRect(RectF(rect), 10f, 10f, maskingPaint)
                                     }
+                                    if (DEBUG_MODE) {
+                                        debugMasks.addAll(visibleRects)
+                                    }
                                 }
                                 return@traverse true
                             }
 
+                            if (DEBUG_MODE) {
+                                mainLooperHandler.post { debugOverlayDrawable.update(debugMasks) }
+                            }
                             screenshotRecorderCallback?.onScreenshotRecorded(screenshot)
                             lastCaptureSuccessful.set(true)
                             contentChanged.set(false)
@@ -194,11 +211,18 @@ internal class ScreenshotRecorder(
         // next bind the new root
         rootView = WeakReference(root)
         root.addOnDrawListenerSafe(this)
+        if (DEBUG_MODE) {
+            root.overlay.add(debugOverlayDrawable)
+        }
+
         // invalidate the flag to capture the first frame after new window is attached
         contentChanged.set(true)
     }
 
     fun unbind(root: View?) {
+        if (DEBUG_MODE) {
+            root?.overlay?.remove(debugOverlayDrawable)
+        }
         root?.removeOnDrawListenerSafe(this)
     }
 
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
new file mode 100644
index 00000000000..e3b0117dc38
--- /dev/null
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
@@ -0,0 +1,66 @@
+package io.sentry.android.replay.util
+
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.ColorFilter
+import android.graphics.Paint
+import android.graphics.PixelFormat
+import android.graphics.Rect
+import android.graphics.drawable.Drawable
+
+internal class DebugOverlayDrawable : Drawable() {
+
+    private val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+    private val padding = 6f
+    private val tmpRect = Rect()
+    private var masks: List<Rect> = emptyList()
+
+    override fun draw(canvas: Canvas) {
+        paint.textSize = 32f
+        paint.setColor(Color.BLACK)
+
+        paint.strokeWidth = 4f
+
+        for (mask in masks) {
+            paint.setColor(Color.BLACK)
+            paint.style = Paint.Style.STROKE
+            canvas.drawRect(mask, paint)
+
+            paint.style = Paint.Style.FILL
+            val label = "${mask.left} ${mask.top}"
+            paint.getTextBounds(label, 0, label.length, tmpRect)
+
+            paint.setColor(Color.WHITE)
+            canvas.drawRect(
+                mask.left.toFloat() + paint.strokeWidth / 2,
+                mask.top.toFloat() + paint.strokeWidth / 2,
+                mask.left.toFloat() + tmpRect.width() + padding + padding,
+                mask.top.toFloat() + tmpRect.height() + padding + padding,
+                paint
+            )
+            paint.setColor(Color.BLACK)
+            canvas.drawText(
+                label,
+                mask.left.toFloat() + padding + paint.strokeWidth / 2,
+                mask.top.toFloat() + tmpRect.height() - tmpRect.bottom + padding + paint.strokeWidth / 2,
+                paint
+            )
+        }
+    }
+
+    override fun setAlpha(alpha: Int) {
+        // no-op
+    }
+
+    override fun setColorFilter(colorFilter: ColorFilter?) {
+        // no-op
+    }
+
+    @Deprecated("Deprecated in Java")
+    override fun getOpacity(): Int = PixelFormat.TRANSLUCENT
+
+    fun update(masks: List<Rect>) {
+        this.masks = masks
+        invalidateSelf()
+    }
+}

From ac42ba69c25b91ccc546cf2c3524cc8f4f8f7226 Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Wed, 7 May 2025 13:11:18 +0200
Subject: [PATCH 2/9] Improve contrast for debug mode

---
 .../main/java/io/sentry/android/replay/ScreenshotRecorder.kt  | 3 +++
 .../io/sentry/android/replay/util/DebugOverlayDrawable.kt     | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
index 0a406094a72..ec714b3a8e6 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
@@ -201,6 +201,9 @@ internal class ScreenshotRecorder(
         }
 
         contentChanged.set(true)
+        if (DEBUG_MODE) {
+            debugOverlayDrawable.invalidateSelf()
+        }
     }
 
     fun bind(root: View) {
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
index e3b0117dc38..d7b0381e310 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
@@ -22,7 +22,7 @@ internal class DebugOverlayDrawable : Drawable() {
         paint.strokeWidth = 4f
 
         for (mask in masks) {
-            paint.setColor(Color.BLACK)
+            paint.setColor(Color.argb(128, 255, 20, 20))
             paint.style = Paint.Style.STROKE
             canvas.drawRect(mask, paint)
 
@@ -30,7 +30,7 @@ internal class DebugOverlayDrawable : Drawable() {
             val label = "${mask.left} ${mask.top}"
             paint.getTextBounds(label, 0, label.length, tmpRect)
 
-            paint.setColor(Color.WHITE)
+            paint.setColor(Color.argb(128, 255, 255, 255))
             canvas.drawRect(
                 mask.left.toFloat() + paint.strokeWidth / 2,
                 mask.top.toFloat() + paint.strokeWidth / 2,

From 63940e0159027247a02c6c5464ecb9eb7a11a093 Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Mon, 12 May 2025 19:12:03 +0200
Subject: [PATCH 3/9] Improve readability

---
 .../replay/util/DebugOverlayDrawable.kt       | 39 +++++++++++++------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
index d7b0381e310..9b18779cde5 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
@@ -15,30 +15,44 @@ internal class DebugOverlayDrawable : Drawable() {
     private val tmpRect = Rect()
     private var masks: List<Rect> = emptyList()
 
+    companion object {
+        private val maskBackgroundColor = Color.argb(64, 255, 20, 20)
+        private val maskBorderColor = Color.argb(128, 255, 20, 20)
+        private const val TEXT_COLOR = Color.BLACK
+        private const val TEXT_OUTLINE_COLOR = Color.WHITE
+
+        private const val STROKE_WIDTH = 6f
+        private const val TEXT_SIZE = 32f
+    }
+
     override fun draw(canvas: Canvas) {
-        paint.textSize = 32f
+        paint.textSize = TEXT_SIZE
         paint.setColor(Color.BLACK)
 
-        paint.strokeWidth = 4f
+        paint.strokeWidth = STROKE_WIDTH
 
         for (mask in masks) {
-            paint.setColor(Color.argb(128, 255, 20, 20))
+            paint.setColor(maskBackgroundColor)
+            paint.style = Paint.Style.FILL
+            canvas.drawRect(mask, paint)
+
+            paint.setColor(maskBorderColor)
             paint.style = Paint.Style.STROKE
             canvas.drawRect(mask, paint)
 
-            paint.style = Paint.Style.FILL
             val label = "${mask.left} ${mask.top}"
             paint.getTextBounds(label, 0, label.length, tmpRect)
-
-            paint.setColor(Color.argb(128, 255, 255, 255))
-            canvas.drawRect(
-                mask.left.toFloat() + paint.strokeWidth / 2,
-                mask.top.toFloat() + paint.strokeWidth / 2,
-                mask.left.toFloat() + tmpRect.width() + padding + padding,
-                mask.top.toFloat() + tmpRect.height() + padding + padding,
+            paint.style = Paint.Style.STROKE
+            paint.setColor(TEXT_OUTLINE_COLOR)
+            canvas.drawText(
+                label,
+                mask.left.toFloat() + padding + paint.strokeWidth / 2,
+                mask.top.toFloat() + tmpRect.height() - tmpRect.bottom + padding + paint.strokeWidth / 2,
                 paint
             )
-            paint.setColor(Color.BLACK)
+
+            paint.style = Paint.Style.FILL
+            paint.setColor(TEXT_COLOR)
             canvas.drawText(
                 label,
                 mask.left.toFloat() + padding + paint.strokeWidth / 2,
@@ -61,6 +75,7 @@ internal class DebugOverlayDrawable : Drawable() {
 
     fun update(masks: List<Rect>) {
         this.masks = masks
+
         invalidateSelf()
     }
 }

From bee207ed4582466e407c99e3690f1484cfa57697 Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Fri, 16 May 2025 11:00:44 +0200
Subject: [PATCH 4/9] Add ReplayIntegration.enableDebugMasking API, improve
 debug overlay

---
 .../api/sentry-android-replay.api             |  7 +++
 .../android/replay/ReplayIntegration.kt       | 10 +++-
 .../android/replay/ScreenshotRecorder.kt      | 24 ++++----
 .../replay/util/DebugOverlayDrawable.kt       | 60 +++++++++++++------
 .../sentry/samples/android/MainActivity.java  |  6 ++
 .../src/main/res/layout/activity_main.xml     |  6 ++
 .../src/main/res/values/strings.xml           |  1 +
 7 files changed, 80 insertions(+), 34 deletions(-)

diff --git a/sentry-android-replay/api/sentry-android-replay.api b/sentry-android-replay/api/sentry-android-replay.api
index d4e20da038c..2dd2de6e3b8 100644
--- a/sentry-android-replay/api/sentry-android-replay.api
+++ b/sentry-android-replay/api/sentry-android-replay.api
@@ -52,11 +52,13 @@ public final class io/sentry/android/replay/ReplayCache : java/io/Closeable {
 
 public final class io/sentry/android/replay/ReplayIntegration : android/content/ComponentCallbacks, io/sentry/IConnectionStatusProvider$IConnectionStatusObserver, io/sentry/Integration, io/sentry/ReplayController, io/sentry/android/replay/ScreenshotRecorderCallback, io/sentry/android/replay/gestures/TouchRecorderCallback, io/sentry/transport/RateLimiter$IRateLimitObserver, java/io/Closeable {
 	public static final field $stable I
+	public static final field Companion Lio/sentry/android/replay/ReplayIntegration$Companion;
 	public fun <init> (Landroid/content/Context;Lio/sentry/transport/ICurrentDateProvider;)V
 	public fun <init> (Landroid/content/Context;Lio/sentry/transport/ICurrentDateProvider;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
 	public synthetic fun <init> (Landroid/content/Context;Lio/sentry/transport/ICurrentDateProvider;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun captureReplay (Ljava/lang/Boolean;)V
 	public fun close ()V
+	public static final fun enableDebugMasking ()V
 	public fun getBreadcrumbConverter ()Lio/sentry/ReplayBreadcrumbConverter;
 	public final fun getReplayCacheDir ()Ljava/io/File;
 	public fun getReplayId ()Lio/sentry/protocol/SentryId;
@@ -76,6 +78,11 @@ public final class io/sentry/android/replay/ReplayIntegration : android/content/
 	public fun stop ()V
 }
 
+public final class io/sentry/android/replay/ReplayIntegration$Companion {
+	public final fun enableDebugMasking ()V
+	public final fun getDebugMaskingEnabled ()Z
+}
+
 public abstract interface class io/sentry/android/replay/ScreenshotRecorderCallback {
 	public abstract fun onScreenshotRecorded (Landroid/graphics/Bitmap;)V
 	public abstract fun onScreenshotRecorded (Ljava/io/File;J)V
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt
index 094ce469b1a..e9bb1a24666 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt
@@ -71,11 +71,19 @@ public class ReplayIntegration(
     IConnectionStatusObserver,
     IRateLimitObserver {
 
-    private companion object {
+    public companion object {
         init {
             SentryIntegrationPackageStorage.getInstance()
                 .addPackage("maven:io.sentry:sentry-android-replay", BuildConfig.VERSION_NAME)
         }
+
+        public var debugMaskingEnabled: Boolean = false
+            private set
+
+        @JvmStatic
+        public fun enableDebugMasking() {
+            debugMaskingEnabled = true
+        }
     }
 
     // needed for the Java's call site
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
index ec714b3a8e6..35c66d1738c 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
@@ -49,10 +49,6 @@ internal class ScreenshotRecorder(
     private val screenshotRecorderCallback: ScreenshotRecorderCallback?
 ) : ViewTreeObserver.OnDrawListener {
 
-    private companion object {
-        private const val DEBUG_MODE = false
-    }
-
     private var rootView: WeakReference<View>? = null
     private val maskingPaint by lazy(NONE) { Paint() }
     private val singlePixelBitmap: Bitmap by lazy(NONE) {
@@ -169,15 +165,21 @@ internal class ScreenshotRecorder(
                                     visibleRects.forEach { rect ->
                                         canvas.drawRoundRect(RectF(rect), 10f, 10f, maskingPaint)
                                     }
-                                    if (DEBUG_MODE) {
+                                    if (ReplayIntegration.debugMaskingEnabled) {
                                         debugMasks.addAll(visibleRects)
                                     }
                                 }
                                 return@traverse true
                             }
 
-                            if (DEBUG_MODE) {
-                                mainLooperHandler.post { debugOverlayDrawable.update(debugMasks) }
+                            if (ReplayIntegration.debugMaskingEnabled) {
+                                mainLooperHandler.post {
+                                    if (debugOverlayDrawable.callback == null) {
+                                        root.overlay.add(debugOverlayDrawable)
+                                    }
+                                    debugOverlayDrawable.updateMasks(debugMasks)
+                                    root.postInvalidate()
+                                }
                             }
                             screenshotRecorderCallback?.onScreenshotRecorded(screenshot)
                             lastCaptureSuccessful.set(true)
@@ -201,9 +203,6 @@ internal class ScreenshotRecorder(
         }
 
         contentChanged.set(true)
-        if (DEBUG_MODE) {
-            debugOverlayDrawable.invalidateSelf()
-        }
     }
 
     fun bind(root: View) {
@@ -214,16 +213,13 @@ internal class ScreenshotRecorder(
         // next bind the new root
         rootView = WeakReference(root)
         root.addOnDrawListenerSafe(this)
-        if (DEBUG_MODE) {
-            root.overlay.add(debugOverlayDrawable)
-        }
 
         // invalidate the flag to capture the first frame after new window is attached
         contentChanged.set(true)
     }
 
     fun unbind(root: View?) {
-        if (DEBUG_MODE) {
+        if (ReplayIntegration.debugMaskingEnabled) {
             root?.overlay?.remove(debugOverlayDrawable)
         }
         root?.removeOnDrawListenerSafe(this)
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
index 9b18779cde5..97054a4f80e 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/util/DebugOverlayDrawable.kt
@@ -16,7 +16,7 @@ internal class DebugOverlayDrawable : Drawable() {
     private var masks: List<Rect> = emptyList()
 
     companion object {
-        private val maskBackgroundColor = Color.argb(64, 255, 20, 20)
+        private val maskBackgroundColor = Color.argb(32, 255, 20, 20)
         private val maskBorderColor = Color.argb(128, 255, 20, 20)
         private const val TEXT_COLOR = Color.BLACK
         private const val TEXT_OUTLINE_COLOR = Color.WHITE
@@ -40,28 +40,51 @@ internal class DebugOverlayDrawable : Drawable() {
             paint.style = Paint.Style.STROKE
             canvas.drawRect(mask, paint)
 
-            val label = "${mask.left} ${mask.top}"
-            paint.getTextBounds(label, 0, label.length, tmpRect)
-            paint.style = Paint.Style.STROKE
-            paint.setColor(TEXT_OUTLINE_COLOR)
-            canvas.drawText(
-                label,
-                mask.left.toFloat() + padding + paint.strokeWidth / 2,
-                mask.top.toFloat() + tmpRect.height() - tmpRect.bottom + padding + paint.strokeWidth / 2,
-                paint
+            val topLeftLabel = "${mask.left}/${mask.top}"
+            paint.getTextBounds(topLeftLabel, 0, topLeftLabel.length, tmpRect)
+            drawTextWithOutline(
+                canvas,
+                topLeftLabel,
+                mask.left.toFloat(),
+                mask.top.toFloat()
             )
 
-            paint.style = Paint.Style.FILL
-            paint.setColor(TEXT_COLOR)
-            canvas.drawText(
-                label,
-                mask.left.toFloat() + padding + paint.strokeWidth / 2,
-                mask.top.toFloat() + tmpRect.height() - tmpRect.bottom + padding + paint.strokeWidth / 2,
-                paint
+            val bottomRightLabel = "${mask.right}/${mask.bottom}"
+            paint.getTextBounds(bottomRightLabel, 0, bottomRightLabel.length, tmpRect)
+            drawTextWithOutline(
+                canvas,
+                bottomRightLabel,
+                mask.right.toFloat() - tmpRect.width(),
+                mask.bottom.toFloat() + tmpRect.height()
             )
         }
     }
 
+    private fun drawTextWithOutline(
+        canvas: Canvas,
+        bottomRightLabel: String,
+        x: Float,
+        y: Float
+    ) {
+        paint.setColor(TEXT_OUTLINE_COLOR)
+        paint.style = Paint.Style.STROKE
+        canvas.drawText(
+            bottomRightLabel,
+            x,
+            y,
+            paint
+        )
+
+        paint.setColor(TEXT_COLOR)
+        paint.style = Paint.Style.FILL
+        canvas.drawText(
+            bottomRightLabel,
+            x,
+            y,
+            paint
+        )
+    }
+
     override fun setAlpha(alpha: Int) {
         // no-op
     }
@@ -73,9 +96,8 @@ internal class DebugOverlayDrawable : Drawable() {
     @Deprecated("Deprecated in Java")
     override fun getOpacity(): Int = PixelFormat.TRANSLUCENT
 
-    fun update(masks: List<Rect>) {
+    fun updateMasks(masks: List<Rect>) {
         this.masks = masks
-
         invalidateSelf()
     }
 }
diff --git a/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java b/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
index 802e765a9e4..a8d0d923aaa 100644
--- a/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
+++ b/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
@@ -9,6 +9,7 @@
 import io.sentry.MeasurementUnit;
 import io.sentry.Sentry;
 import io.sentry.UserFeedback;
+import io.sentry.android.replay.ReplayIntegration;
 import io.sentry.instrumentation.file.SentryFileOutputStream;
 import io.sentry.protocol.SentryId;
 import io.sentry.protocol.User;
@@ -275,6 +276,11 @@ public void run() {
           CoroutinesUtil.INSTANCE.throwInCoroutine();
         });
 
+    binding.enableReplayDebugMode.setOnClickListener(
+        view -> {
+          ReplayIntegration.enableDebugMasking();
+        });
+
     setContentView(binding.getRoot());
   }
 
diff --git a/sentry-samples/sentry-samples-android/src/main/res/layout/activity_main.xml b/sentry-samples/sentry-samples-android/src/main/res/layout/activity_main.xml
index 71c8059d588..fcb0553a58d 100644
--- a/sentry-samples/sentry-samples-android/src/main/res/layout/activity_main.xml
+++ b/sentry-samples/sentry-samples-android/src/main/res/layout/activity_main.xml
@@ -154,6 +154,12 @@
       android:layout_height="wrap_content"
       android:text="@string/throw_in_coroutine"/>
 
+    <Button
+      android:id="@+id/enable_replay_debug_mode"
+      android:layout_width="wrap_content"
+      android:layout_height="wrap_content"
+      android:text="@string/enable_replay_debug_mode"/>
+
   </LinearLayout>
 
 </ScrollView>
diff --git a/sentry-samples/sentry-samples-android/src/main/res/values/strings.xml b/sentry-samples/sentry-samples-android/src/main/res/values/strings.xml
index 7c1e82cfcb6..68e1d9c0c14 100644
--- a/sentry-samples/sentry-samples-android/src/main/res/values/strings.xml
+++ b/sentry-samples/sentry-samples-android/src/main/res/values/strings.xml
@@ -27,6 +27,7 @@
   <string name="open_metrics">Delightful Developer Metrics</string>
   <string name="test_timber_integration">Test Timber</string>
   <string name="throw_in_coroutine">Throw exception in coroutine</string>
+  <string name="enable_replay_debug_mode">Enable Replay Debug Mode</string>
   <string name="back_main">Back to Main Activity</string>
   <string name="tap_me">text</string>
   <string name="lipsum">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin nibh lorem, venenatis sed nulla vel, venenatis sodales augue. Mauris varius elit eu ligula volutpat, sed tincidunt orci porttitor. Donec et dignissim lacus, sed luctus ipsum. Praesent ornare luctus tortor sit amet ultricies. Cras iaculis et diam et vulputate. Cras ut iaculis mauris, non pellentesque diam. Nunc in laoreet diam, vitae accumsan eros. Morbi non nunc ac eros molestie placerat vitae id dolor. Quisque ornare aliquam ipsum, a dapibus tortor. In eu sodales tellus.

From 5110b0fc08f8deba4085618d3b2a90ebd2092abb Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Fri, 16 May 2025 11:10:21 +0200
Subject: [PATCH 5/9] Update Changelog

---
 CHANGELOG.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7fb3faa2441..5fe2700a384 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add debug mode for Session Replay masking ([#4357](https://github.com/getsentry/sentry-java/pull/4357))
+  Use `ReplayIntegration.enableDebugMasking()` to overlay the screen with the Session Replay masks
+
 ## 8.12.0
 
 ### Features

From 5d4cf78c863e2a17ad18b7db29242e66105a2fef Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Mon, 19 May 2025 08:21:26 +0200
Subject: [PATCH 6/9] Introduce IReplayApi

---
 .../api/sentry-android-core.api               |  1 +
 .../io/sentry/android/core/SentryAndroid.java |  6 +++++
 .../sentry/android/core/SentryAndroidTest.kt  | 16 ++++++++++++++
 .../api/sentry-android-replay.api             | 10 +++------
 .../android/replay/ReplayIntegration.kt       | 22 ++++++++++---------
 .../android/replay/ScreenshotRecorder.kt      |  6 ++---
 .../android/replay/ReplayIntegrationTest.kt   | 20 +++++++++++++++++
 sentry/api/sentry.api                         | 11 +++++++++-
 .../src/main/java/io/sentry/IReplayApi.java   | 16 ++++++++++++++
 .../java/io/sentry/NoOpReplayController.java  | 11 ++++++++++
 .../main/java/io/sentry/ReplayController.java |  4 +++-
 11 files changed, 101 insertions(+), 22 deletions(-)
 create mode 100644 sentry/src/main/java/io/sentry/IReplayApi.java

diff --git a/sentry-android-core/api/sentry-android-core.api b/sentry-android-core/api/sentry-android-core.api
index afb6b6a1752..3d574cde9d5 100644
--- a/sentry-android-core/api/sentry-android-core.api
+++ b/sentry-android-core/api/sentry-android-core.api
@@ -280,6 +280,7 @@ public final class io/sentry/android/core/SentryAndroid {
 	public static fun init (Landroid/content/Context;Lio/sentry/ILogger;)V
 	public static fun init (Landroid/content/Context;Lio/sentry/ILogger;Lio/sentry/Sentry$OptionsConfiguration;)V
 	public static fun init (Landroid/content/Context;Lio/sentry/Sentry$OptionsConfiguration;)V
+	public static fun replay ()Lio/sentry/IReplayApi;
 }
 
 public final class io/sentry/android/core/SentryAndroidDateProvider : io/sentry/SentryDateProvider {
diff --git a/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java b/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java
index d183d4c45be..41fcb596d2b 100644
--- a/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java
+++ b/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java
@@ -6,6 +6,7 @@
 import android.os.Process;
 import android.os.SystemClock;
 import io.sentry.ILogger;
+import io.sentry.IReplayApi;
 import io.sentry.IScopes;
 import io.sentry.ISentryLifecycleToken;
 import io.sentry.Integration;
@@ -254,4 +255,9 @@ private static void deduplicateIntegrations(
       }
     }
   }
+
+  @NotNull
+  public static IReplayApi replay() {
+    return Sentry.getCurrentScopes().getScope().getOptions().getReplayController();
+  }
 }
diff --git a/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt b/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt
index bb3401aa59f..43b7346f854 100644
--- a/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt
+++ b/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt
@@ -15,6 +15,7 @@ import io.sentry.DateUtils
 import io.sentry.Hint
 import io.sentry.ILogger
 import io.sentry.ISentryClient
+import io.sentry.ReplayController
 import io.sentry.Sentry
 import io.sentry.Sentry.OptionsConfiguration
 import io.sentry.SentryEnvelope
@@ -540,6 +541,21 @@ class SentryAndroidTest {
         assertTrue(optionsRef.eventProcessors.any { it is AnrV2EventProcessor })
     }
 
+    @Test
+    fun `replay debug masking is forwarded to replay controller`() {
+        val replayController = mock<ReplayController>()
+        fixture.initSut(context = mock<Application>()) { options ->
+            options.dsn = "https://key@sentry.io/123"
+            options.setReplayController(replayController)
+        }
+
+        SentryAndroid.replay().enableDebugMaskingOverlay()
+        verify(replayController).enableDebugMaskingOverlay()
+
+        SentryAndroid.replay().disableDebugMaskingOverlay()
+        verify(replayController).disableDebugMaskingOverlay()
+    }
+
     private fun prefillScopeCache(options: SentryOptions, cacheDir: String) {
         val scopeDir = File(cacheDir, SCOPE_CACHE).also { it.mkdirs() }
         val queueFile = QueueFile.Builder(File(scopeDir, BREADCRUMBS_FILENAME)).build()
diff --git a/sentry-android-replay/api/sentry-android-replay.api b/sentry-android-replay/api/sentry-android-replay.api
index 2dd2de6e3b8..4566158f0a5 100644
--- a/sentry-android-replay/api/sentry-android-replay.api
+++ b/sentry-android-replay/api/sentry-android-replay.api
@@ -52,16 +52,17 @@ public final class io/sentry/android/replay/ReplayCache : java/io/Closeable {
 
 public final class io/sentry/android/replay/ReplayIntegration : android/content/ComponentCallbacks, io/sentry/IConnectionStatusProvider$IConnectionStatusObserver, io/sentry/Integration, io/sentry/ReplayController, io/sentry/android/replay/ScreenshotRecorderCallback, io/sentry/android/replay/gestures/TouchRecorderCallback, io/sentry/transport/RateLimiter$IRateLimitObserver, java/io/Closeable {
 	public static final field $stable I
-	public static final field Companion Lio/sentry/android/replay/ReplayIntegration$Companion;
 	public fun <init> (Landroid/content/Context;Lio/sentry/transport/ICurrentDateProvider;)V
 	public fun <init> (Landroid/content/Context;Lio/sentry/transport/ICurrentDateProvider;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)V
 	public synthetic fun <init> (Landroid/content/Context;Lio/sentry/transport/ICurrentDateProvider;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun captureReplay (Ljava/lang/Boolean;)V
 	public fun close ()V
-	public static final fun enableDebugMasking ()V
+	public fun disableDebugMaskingOverlay ()V
+	public fun enableDebugMaskingOverlay ()V
 	public fun getBreadcrumbConverter ()Lio/sentry/ReplayBreadcrumbConverter;
 	public final fun getReplayCacheDir ()Ljava/io/File;
 	public fun getReplayId ()Lio/sentry/protocol/SentryId;
+	public fun isDebugMaskingOverlayEnabled ()Z
 	public fun isRecording ()Z
 	public fun onConfigurationChanged (Landroid/content/res/Configuration;)V
 	public fun onConnectionStatusChanged (Lio/sentry/IConnectionStatusProvider$ConnectionStatus;)V
@@ -78,11 +79,6 @@ public final class io/sentry/android/replay/ReplayIntegration : android/content/
 	public fun stop ()V
 }
 
-public final class io/sentry/android/replay/ReplayIntegration$Companion {
-	public final fun enableDebugMasking ()V
-	public final fun getDebugMaskingEnabled ()Z
-}
-
 public abstract interface class io/sentry/android/replay/ScreenshotRecorderCallback {
 	public abstract fun onScreenshotRecorded (Landroid/graphics/Bitmap;)V
 	public abstract fun onScreenshotRecorded (Ljava/io/File;J)V
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt
index e9bb1a24666..3f7099d1319 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt
@@ -71,19 +71,11 @@ public class ReplayIntegration(
     IConnectionStatusObserver,
     IRateLimitObserver {
 
-    public companion object {
+    private companion object {
         init {
             SentryIntegrationPackageStorage.getInstance()
                 .addPackage("maven:io.sentry:sentry-android-replay", BuildConfig.VERSION_NAME)
         }
-
-        public var debugMaskingEnabled: Boolean = false
-            private set
-
-        @JvmStatic
-        public fun enableDebugMasking() {
-            debugMaskingEnabled = true
-        }
     }
 
     // needed for the Java's call site
@@ -109,7 +101,7 @@ public class ReplayIntegration(
         this.mainLooperHandler = mainLooperHandler ?: MainLooperHandler()
         this.gestureRecorderProvider = gestureRecorderProvider
     }
-
+    private var debugMaskingEnabled: Boolean = false
     private lateinit var options: SentryOptions
     private var scopes: IScopes? = null
     private var recorder: Recorder? = null
@@ -259,6 +251,16 @@ public class ReplayIntegration(
         pauseInternal()
     }
 
+    override fun enableDebugMaskingOverlay() {
+        debugMaskingEnabled = true
+    }
+
+    override fun disableDebugMaskingOverlay() {
+        debugMaskingEnabled = false
+    }
+
+    override fun isDebugMaskingOverlayEnabled(): Boolean = debugMaskingEnabled
+
     private fun pauseInternal() {
         lifecycleLock.acquire().use {
             if (!isEnabled.get() || !lifecycle.isAllowed(PAUSED)) {
diff --git a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
index 35c66d1738c..8d86636ca7e 100644
--- a/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
+++ b/sentry-android-replay/src/main/java/io/sentry/android/replay/ScreenshotRecorder.kt
@@ -165,14 +165,14 @@ internal class ScreenshotRecorder(
                                     visibleRects.forEach { rect ->
                                         canvas.drawRoundRect(RectF(rect), 10f, 10f, maskingPaint)
                                     }
-                                    if (ReplayIntegration.debugMaskingEnabled) {
+                                    if (options.replayController.isDebugMaskingOverlayEnabled()) {
                                         debugMasks.addAll(visibleRects)
                                     }
                                 }
                                 return@traverse true
                             }
 
-                            if (ReplayIntegration.debugMaskingEnabled) {
+                            if (options.replayController.isDebugMaskingOverlayEnabled()) {
                                 mainLooperHandler.post {
                                     if (debugOverlayDrawable.callback == null) {
                                         root.overlay.add(debugOverlayDrawable)
@@ -219,7 +219,7 @@ internal class ScreenshotRecorder(
     }
 
     fun unbind(root: View?) {
-        if (ReplayIntegration.debugMaskingEnabled) {
+        if (options.replayController.isDebugMaskingOverlayEnabled()) {
             root?.overlay?.remove(debugOverlayDrawable)
         }
         root?.removeOnDrawListenerSafe(this)
diff --git a/sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt b/sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt
index 7ba893d4076..b3c092553f7 100644
--- a/sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt
+++ b/sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt
@@ -867,6 +867,26 @@ class ReplayIntegrationTest {
         verify(recorder).resume()
     }
 
+    @Test
+    fun `debug masking is disabled by default`() {
+        val replay = fixture.getSut(
+            context
+        )
+        assertFalse(replay.isDebugMaskingOverlayEnabled)
+    }
+
+    @Test
+    fun `debug masking can be enabled and disabled`() {
+        val replay = fixture.getSut(
+            context
+        )
+        replay.enableDebugMaskingOverlay()
+        assertTrue(replay.isDebugMaskingOverlayEnabled)
+
+        replay.disableDebugMaskingOverlay()
+        assertFalse(replay.isDebugMaskingOverlayEnabled)
+    }
+
     private fun getSessionCaptureStrategy(options: SentryOptions): SessionCaptureStrategy {
         return SessionCaptureStrategy(
             options,
diff --git a/sentry/api/sentry.api b/sentry/api/sentry.api
index a38986a65f7..c4492e91635 100644
--- a/sentry/api/sentry.api
+++ b/sentry/api/sentry.api
@@ -817,6 +817,11 @@ public abstract interface class io/sentry/IPerformanceSnapshotCollector : io/sen
 	public abstract fun setup ()V
 }
 
+public abstract interface class io/sentry/IReplayApi {
+	public abstract fun disableDebugMaskingOverlay ()V
+	public abstract fun enableDebugMaskingOverlay ()V
+}
+
 public abstract interface class io/sentry/IScope {
 	public abstract fun addAttachment (Lio/sentry/Attachment;)V
 	public abstract fun addBreadcrumb (Lio/sentry/Breadcrumb;)V
@@ -1567,9 +1572,12 @@ public final class io/sentry/NoOpReplayBreadcrumbConverter : io/sentry/ReplayBre
 
 public final class io/sentry/NoOpReplayController : io/sentry/ReplayController {
 	public fun captureReplay (Ljava/lang/Boolean;)V
+	public fun disableDebugMaskingOverlay ()V
+	public fun enableDebugMaskingOverlay ()V
 	public fun getBreadcrumbConverter ()Lio/sentry/ReplayBreadcrumbConverter;
 	public static fun getInstance ()Lio/sentry/NoOpReplayController;
 	public fun getReplayId ()Lio/sentry/protocol/SentryId;
+	public fun isDebugMaskingOverlayEnabled ()Z
 	public fun isRecording ()Z
 	public fun pause ()V
 	public fun resume ()V
@@ -2170,10 +2178,11 @@ public abstract interface class io/sentry/ReplayBreadcrumbConverter {
 	public abstract fun convert (Lio/sentry/Breadcrumb;)Lio/sentry/rrweb/RRWebEvent;
 }
 
-public abstract interface class io/sentry/ReplayController {
+public abstract interface class io/sentry/ReplayController : io/sentry/IReplayApi {
 	public abstract fun captureReplay (Ljava/lang/Boolean;)V
 	public abstract fun getBreadcrumbConverter ()Lio/sentry/ReplayBreadcrumbConverter;
 	public abstract fun getReplayId ()Lio/sentry/protocol/SentryId;
+	public abstract fun isDebugMaskingOverlayEnabled ()Z
 	public abstract fun isRecording ()Z
 	public abstract fun pause ()V
 	public abstract fun resume ()V
diff --git a/sentry/src/main/java/io/sentry/IReplayApi.java b/sentry/src/main/java/io/sentry/IReplayApi.java
new file mode 100644
index 00000000000..f1dd003b525
--- /dev/null
+++ b/sentry/src/main/java/io/sentry/IReplayApi.java
@@ -0,0 +1,16 @@
+package io.sentry;
+
+public interface IReplayApi {
+
+  /**
+   * Draws a masking overlay on top of the screen to help visualize which parts of the screen are
+   * masked by Session Replay. This is only useful for debugging purposes and should not be used in
+   * production environments.
+   *
+   * <p>Expect the top level view to be invalidated more often than usual, as the overlay is drawn
+   * on top of it.
+   */
+  void enableDebugMaskingOverlay();
+
+  void disableDebugMaskingOverlay();
+}
diff --git a/sentry/src/main/java/io/sentry/NoOpReplayController.java b/sentry/src/main/java/io/sentry/NoOpReplayController.java
index e868038db2d..fec95b5d66d 100644
--- a/sentry/src/main/java/io/sentry/NoOpReplayController.java
+++ b/sentry/src/main/java/io/sentry/NoOpReplayController.java
@@ -46,4 +46,15 @@ public void setBreadcrumbConverter(@NotNull ReplayBreadcrumbConverter converter)
   public @NotNull ReplayBreadcrumbConverter getBreadcrumbConverter() {
     return NoOpReplayBreadcrumbConverter.getInstance();
   }
+
+  @Override
+  public boolean isDebugMaskingOverlayEnabled() {
+    return false;
+  }
+
+  @Override
+  public void enableDebugMaskingOverlay() {}
+
+  @Override
+  public void disableDebugMaskingOverlay() {}
 }
diff --git a/sentry/src/main/java/io/sentry/ReplayController.java b/sentry/src/main/java/io/sentry/ReplayController.java
index 01c0f9da121..dd40bfc9732 100644
--- a/sentry/src/main/java/io/sentry/ReplayController.java
+++ b/sentry/src/main/java/io/sentry/ReplayController.java
@@ -6,7 +6,7 @@
 import org.jetbrains.annotations.Nullable;
 
 @ApiStatus.Internal
-public interface ReplayController {
+public interface ReplayController extends IReplayApi {
   void start();
 
   void stop();
@@ -26,4 +26,6 @@ public interface ReplayController {
 
   @NotNull
   ReplayBreadcrumbConverter getBreadcrumbConverter();
+
+  boolean isDebugMaskingOverlayEnabled();
 }

From effe222ef46b888acfb2a653bc0ce2672d80c41b Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Mon, 19 May 2025 08:23:54 +0200
Subject: [PATCH 7/9] Update Changelog

---
 CHANGELOG.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5fe2700a384..a1b873a2adf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,8 @@
 ### Features
 
 - Add debug mode for Session Replay masking ([#4357](https://github.com/getsentry/sentry-java/pull/4357))
-  Use `ReplayIntegration.enableDebugMasking()` to overlay the screen with the Session Replay masks
+    - Use `SentryAndroid.replay().enableDebugMaskingOverlay()` to overlay the screen with the Session Replay masks.
+    - The masks will be invalidated at most once per `frameRate` (default 1 fps).
 
 ## 8.12.0
 

From bb574e87b83d9cd23c3e324a6d54f8e960f8e482 Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Mon, 19 May 2025 08:57:39 +0200
Subject: [PATCH 8/9] Fix Sample app

---
 .../src/main/java/io/sentry/samples/android/MainActivity.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java b/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
index aa06ee46884..de119f20d58 100644
--- a/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
+++ b/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
@@ -8,7 +8,7 @@
 import io.sentry.ISpan;
 import io.sentry.MeasurementUnit;
 import io.sentry.Sentry;
-import io.sentry.android.replay.ReplayIntegration;
+import io.sentry.android.core.SentryAndroid;
 import io.sentry.instrumentation.file.SentryFileOutputStream;
 import io.sentry.protocol.Feedback;
 import io.sentry.protocol.User;
@@ -276,7 +276,7 @@ public void run() {
 
     binding.enableReplayDebugMode.setOnClickListener(
         view -> {
-          ReplayIntegration.enableDebugMasking();
+          SentryAndroid.replay().enableDebugMaskingOverlay();
         });
 
     setContentView(binding.getRoot());

From 502618d8462f5d719a6acd7ef8450c4d4710b567 Mon Sep 17 00:00:00 2001
From: markushi <markus.hintersteiner@sentry.io>
Date: Mon, 19 May 2025 09:56:31 +0200
Subject: [PATCH 9/9] Move replay API from SentryAndroid to Sentry

---
 CHANGELOG.md                                     |  2 +-
 sentry-android-core/api/sentry-android-core.api  |  1 -
 .../io/sentry/android/core/SentryAndroid.java    |  6 ------
 .../io/sentry/android/core/SentryAndroidTest.kt  | 16 ----------------
 .../io/sentry/samples/android/MainActivity.java  |  3 +--
 sentry/api/sentry.api                            |  1 +
 sentry/src/main/java/io/sentry/Sentry.java       |  5 +++++
 sentry/src/test/java/io/sentry/SentryTest.kt     | 14 ++++++++++++++
 8 files changed, 22 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1b873a2adf..980d37262de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@
 ### Features
 
 - Add debug mode for Session Replay masking ([#4357](https://github.com/getsentry/sentry-java/pull/4357))
-    - Use `SentryAndroid.replay().enableDebugMaskingOverlay()` to overlay the screen with the Session Replay masks.
+    - Use `Sentry.replay().enableDebugMaskingOverlay()` to overlay the screen with the Session Replay masks.
     - The masks will be invalidated at most once per `frameRate` (default 1 fps).
 
 ## 8.12.0
diff --git a/sentry-android-core/api/sentry-android-core.api b/sentry-android-core/api/sentry-android-core.api
index 3d574cde9d5..afb6b6a1752 100644
--- a/sentry-android-core/api/sentry-android-core.api
+++ b/sentry-android-core/api/sentry-android-core.api
@@ -280,7 +280,6 @@ public final class io/sentry/android/core/SentryAndroid {
 	public static fun init (Landroid/content/Context;Lio/sentry/ILogger;)V
 	public static fun init (Landroid/content/Context;Lio/sentry/ILogger;Lio/sentry/Sentry$OptionsConfiguration;)V
 	public static fun init (Landroid/content/Context;Lio/sentry/Sentry$OptionsConfiguration;)V
-	public static fun replay ()Lio/sentry/IReplayApi;
 }
 
 public final class io/sentry/android/core/SentryAndroidDateProvider : io/sentry/SentryDateProvider {
diff --git a/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java b/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java
index 41fcb596d2b..d183d4c45be 100644
--- a/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java
+++ b/sentry-android-core/src/main/java/io/sentry/android/core/SentryAndroid.java
@@ -6,7 +6,6 @@
 import android.os.Process;
 import android.os.SystemClock;
 import io.sentry.ILogger;
-import io.sentry.IReplayApi;
 import io.sentry.IScopes;
 import io.sentry.ISentryLifecycleToken;
 import io.sentry.Integration;
@@ -255,9 +254,4 @@ private static void deduplicateIntegrations(
       }
     }
   }
-
-  @NotNull
-  public static IReplayApi replay() {
-    return Sentry.getCurrentScopes().getScope().getOptions().getReplayController();
-  }
 }
diff --git a/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt b/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt
index 43b7346f854..bb3401aa59f 100644
--- a/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt
+++ b/sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidTest.kt
@@ -15,7 +15,6 @@ import io.sentry.DateUtils
 import io.sentry.Hint
 import io.sentry.ILogger
 import io.sentry.ISentryClient
-import io.sentry.ReplayController
 import io.sentry.Sentry
 import io.sentry.Sentry.OptionsConfiguration
 import io.sentry.SentryEnvelope
@@ -541,21 +540,6 @@ class SentryAndroidTest {
         assertTrue(optionsRef.eventProcessors.any { it is AnrV2EventProcessor })
     }
 
-    @Test
-    fun `replay debug masking is forwarded to replay controller`() {
-        val replayController = mock<ReplayController>()
-        fixture.initSut(context = mock<Application>()) { options ->
-            options.dsn = "https://key@sentry.io/123"
-            options.setReplayController(replayController)
-        }
-
-        SentryAndroid.replay().enableDebugMaskingOverlay()
-        verify(replayController).enableDebugMaskingOverlay()
-
-        SentryAndroid.replay().disableDebugMaskingOverlay()
-        verify(replayController).disableDebugMaskingOverlay()
-    }
-
     private fun prefillScopeCache(options: SentryOptions, cacheDir: String) {
         val scopeDir = File(cacheDir, SCOPE_CACHE).also { it.mkdirs() }
         val queueFile = QueueFile.Builder(File(scopeDir, BREADCRUMBS_FILENAME)).build()
diff --git a/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java b/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
index de119f20d58..cd1d326a900 100644
--- a/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
+++ b/sentry-samples/sentry-samples-android/src/main/java/io/sentry/samples/android/MainActivity.java
@@ -8,7 +8,6 @@
 import io.sentry.ISpan;
 import io.sentry.MeasurementUnit;
 import io.sentry.Sentry;
-import io.sentry.android.core.SentryAndroid;
 import io.sentry.instrumentation.file.SentryFileOutputStream;
 import io.sentry.protocol.Feedback;
 import io.sentry.protocol.User;
@@ -276,7 +275,7 @@ public void run() {
 
     binding.enableReplayDebugMode.setOnClickListener(
         view -> {
-          SentryAndroid.replay().enableDebugMaskingOverlay();
+          Sentry.replay().enableDebugMaskingOverlay();
         });
 
     setContentView(binding.getRoot());
diff --git a/sentry/api/sentry.api b/sentry/api/sentry.api
index c4492e91635..6dec9900a0a 100644
--- a/sentry/api/sentry.api
+++ b/sentry/api/sentry.api
@@ -2589,6 +2589,7 @@ public final class io/sentry/Sentry {
 	public static fun pushScope ()Lio/sentry/ISentryLifecycleToken;
 	public static fun removeExtra (Ljava/lang/String;)V
 	public static fun removeTag (Ljava/lang/String;)V
+	public static fun replay ()Lio/sentry/IReplayApi;
 	public static fun reportFullyDisplayed ()V
 	public static fun setCurrentHub (Lio/sentry/IHub;)Lio/sentry/ISentryLifecycleToken;
 	public static fun setCurrentScopes (Lio/sentry/IScopes;)Lio/sentry/ISentryLifecycleToken;
diff --git a/sentry/src/main/java/io/sentry/Sentry.java b/sentry/src/main/java/io/sentry/Sentry.java
index c47641088db..5345178f3ec 100644
--- a/sentry/src/main/java/io/sentry/Sentry.java
+++ b/sentry/src/main/java/io/sentry/Sentry.java
@@ -1270,4 +1270,9 @@ public interface OptionsConfiguration<T extends SentryOptions> {
   public static ILoggerApi logger() {
     return getCurrentScopes().logger();
   }
+
+  @NotNull
+  public static IReplayApi replay() {
+    return getCurrentScopes().getScope().getOptions().getReplayController();
+  }
 }
diff --git a/sentry/src/test/java/io/sentry/SentryTest.kt b/sentry/src/test/java/io/sentry/SentryTest.kt
index ffcacf20b61..9384d171673 100644
--- a/sentry/src/test/java/io/sentry/SentryTest.kt
+++ b/sentry/src/test/java/io/sentry/SentryTest.kt
@@ -1443,6 +1443,20 @@ class SentryTest {
         verify(profiler, never()).stopProfiler(eq(ProfileLifecycle.MANUAL))
     }
 
+    @Test
+    fun `replay debug masking is forwarded to replay controller`() {
+        val replayController = mock<ReplayController>()
+        Sentry.init {
+            it.dsn = dsn
+            it.setReplayController(replayController)
+        }
+        Sentry.replay().enableDebugMaskingOverlay()
+        verify(replayController).enableDebugMaskingOverlay()
+
+        Sentry.replay().disableDebugMaskingOverlay()
+        verify(replayController).disableDebugMaskingOverlay()
+    }
+
     private class InMemoryOptionsObserver : IOptionsObserver {
         var release: String? = null
             private set