refactor(replay): Rename ReplaySnapshotObserver to ReplayFrameObserver (JAVA-504)

Rename the interface to ReplayFrameObserver and the callback method
to onMaskedFrameCaptured to clarify that frames have masking applied.
Also update the changelog with a usage snippet.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: runningcode

CHANGELOG.md

@@ -5,7 +5,24 @@
 ### Features
 
 - Add support to configure reporting historical ANRs via `AndroidManifest.xml` using the  `io.sentry.anr.report-historical` attribute ([#5387](https://github.com/getsentry/sentry-java/pull/5387))
-- Session Replay: Add `ReplaySnapshotObserver` for observing captured replay frames ([#5386](https://github.com/getsentry/sentry-java/pull/5386))
+- Session Replay: Add `ReplayFrameObserver` for observing captured replay frames ([#5386](https://github.com/getsentry/sentry-java/pull/5386))
+
+  ```kotlin
+  SentryAndroid.init(context) { options ->
+    options.sessionReplay.frameObserver =
+      SentryReplayOptions.ReplayFrameObserver { hint, frameTimestamp, screenName ->
+        val bitmap = hint.getAs(TypeCheckHint.REPLAY_FRAME_BITMAP, Bitmap::class.java)
+        if (bitmap != null) {
+          try {
+            // Process the masked replay frame
+            myAnalyzer.processFrame(bitmap, frameTimestamp, screenName)
+          } finally {
+            bitmap.recycle()
+          }
+        }
+      }
+  }
+  ```
 
 ### Dependencies
 

sentry-android-integration-tests/sentry-uitest-android/src/androidTestReplay/java/io/sentry/uitest/android/ReplaySnapshotTest.kt

@@ -44,11 +44,11 @@ class ReplaySnapshotTest : BaseUiTest() {
 
     initSentry {
       it.sessionReplay.sessionSampleRate = 1.0
-      it.sessionReplay.snapshotObserver =
-        SentryReplayOptions.ReplaySnapshotObserver { hint, frameTimestamp, screenName ->
+      it.sessionReplay.frameObserver =
+        SentryReplayOptions.ReplayFrameObserver { hint, frameTimestamp, screenName ->
           val bitmap =
             hint.getAs(TypeCheckHint.REPLAY_FRAME_BITMAP, Bitmap::class.java)
-              ?: return@ReplaySnapshotObserver
+              ?: return@ReplayFrameObserver
           val name = screenName ?: "unknown"
           if (capturedScreens.add(name)) {
             val file = File(snapshotsDir, "${name}_$frameTimestamp.png")

sentry-android-replay/src/main/java/io/sentry/android/replay/ReplayIntegration.kt

@@ -311,16 +311,16 @@ public class ReplayIntegration(
     var screen: String? = null
     scopes?.configureScope { screen = it.screen?.substringAfterLast('.') }
     captureStrategy?.onScreenshotRecorded(bitmap) { frameTimeStamp ->
-      val observer = options.sessionReplay.snapshotObserver
+      val observer = options.sessionReplay.frameObserver
       if (observer != null) {
         val copy = bitmap.copy(bitmap.config!!, false)
         if (copy != null) {
           try {
             val hint = Hint()
             hint.set(TypeCheckHint.REPLAY_FRAME_BITMAP, copy)
-            observer.onSnapshotCaptured(hint, frameTimeStamp, screen)
+            observer.onMaskedFrameCaptured(hint, frameTimeStamp, screen)
           } catch (e: Throwable) {
-            options.logger.log(ERROR, "Error in ReplaySnapshotObserver", e)
+            options.logger.log(ERROR, "Error in ReplayFrameObserver", e)
             copy.recycle()
           }
         }

sentry-android-replay/src/test/java/io/sentry/android/replay/ReplayIntegrationTest.kt

@@ -996,8 +996,8 @@ class ReplayIntegrationTest {
     replay.register(fixture.scopes, fixture.options)
     replay.start()
 
-    fixture.options.sessionReplay.snapshotObserver =
-      SentryReplayOptions.ReplaySnapshotObserver { hint, frameTimestamp, screenName ->
+    fixture.options.sessionReplay.frameObserver =
+      SentryReplayOptions.ReplayFrameObserver { hint, frameTimestamp, screenName ->
         callbackInvoked = true
         receivedTimestamp = frameTimestamp
         receivedScreen = screenName
@@ -1036,8 +1036,8 @@ class ReplayIntegrationTest {
     replay.register(fixture.scopes, fixture.options)
     replay.start()
 
-    fixture.options.sessionReplay.snapshotObserver =
-      SentryReplayOptions.ReplaySnapshotObserver { _, _, _ -> throw RuntimeException("test") }
+    fixture.options.sessionReplay.frameObserver =
+      SentryReplayOptions.ReplayFrameObserver { _, _, _ -> throw RuntimeException("test") }
 
     val sourceBitmap =
       mock<Bitmap> {

sentry/api/sentry.api

@@ -4056,6 +4056,7 @@ public final class io/sentry/SentryReplayOptions : io/sentry/SentryMaskingOption
 	public fun addUnmaskViewClass (Ljava/lang/String;)V
 	public fun getBeforeErrorSampling ()Lio/sentry/SentryReplayOptions$BeforeErrorSamplingCallback;
 	public fun getErrorReplayDuration ()J
+	public fun getFrameObserver ()Lio/sentry/SentryReplayOptions$ReplayFrameObserver;
 	public fun getFrameRate ()I
 	public fun getNetworkDetailAllowUrls ()Ljava/util/List;
 	public fun getNetworkDetailDenyUrls ()Ljava/util/List;
@@ -4069,7 +4070,6 @@ public final class io/sentry/SentryReplayOptions : io/sentry/SentryMaskingOption
 	public fun getSessionDuration ()J
 	public fun getSessionSampleRate ()Ljava/lang/Double;
 	public fun getSessionSegmentDuration ()J
-	public fun getSnapshotObserver ()Lio/sentry/SentryReplayOptions$ReplaySnapshotObserver;
 	public fun isCaptureSurfaceViews ()Z
 	public fun isDebug ()Z
 	public fun isNetworkCaptureBodies ()Z
@@ -4079,6 +4079,7 @@ public final class io/sentry/SentryReplayOptions : io/sentry/SentryMaskingOption
 	public fun setBeforeErrorSampling (Lio/sentry/SentryReplayOptions$BeforeErrorSamplingCallback;)V
 	public fun setCaptureSurfaceViews (Z)V
 	public fun setDebug (Z)V
+	public fun setFrameObserver (Lio/sentry/SentryReplayOptions$ReplayFrameObserver;)V
 	public fun setMaskAllImages (Z)V
 	public fun setMaskAllText (Z)V
 	public fun setNetworkCaptureBodies (Z)V
@@ -4091,7 +4092,6 @@ public final class io/sentry/SentryReplayOptions : io/sentry/SentryMaskingOption
 	public fun setScreenshotStrategy (Lio/sentry/ScreenshotStrategyType;)V
 	public fun setSdkVersion (Lio/sentry/protocol/SdkVersion;)V
 	public fun setSessionSampleRate (Ljava/lang/Double;)V
-	public fun setSnapshotObserver (Lio/sentry/SentryReplayOptions$ReplaySnapshotObserver;)V
 	public fun setTrackConfiguration (Z)V
 	public fun trackCustomMasking ()V
 }
@@ -4100,8 +4100,8 @@ public abstract interface class io/sentry/SentryReplayOptions$BeforeErrorSamplin
 	public abstract fun execute (Lio/sentry/SentryEvent;Lio/sentry/Hint;)Z
 }
 
-public abstract interface class io/sentry/SentryReplayOptions$ReplaySnapshotObserver {
-	public abstract fun onSnapshotCaptured (Lio/sentry/Hint;JLjava/lang/String;)V
+public abstract interface class io/sentry/SentryReplayOptions$ReplayFrameObserver {
+	public abstract fun onMaskedFrameCaptured (Lio/sentry/Hint;JLjava/lang/String;)V
 }
 
 public final class io/sentry/SentryReplayOptions$SentryReplayQuality : java/lang/Enum {

sentry/src/main/java/io/sentry/SentryReplayOptions.java

@@ -37,8 +37,9 @@ public interface BeforeErrorSamplingCallback {
   }
 
   /**
-   * Observer that is notified when a replay snapshot is captured. The snapshot bitmap (with masking
-   * applied) is passed via a {@link Hint} using the key {@link TypeCheckHint#REPLAY_FRAME_BITMAP}.
+   * Observer that is notified when a masked replay frame is captured. The frame bitmap (with
+   * masking already applied) is passed via a {@link Hint} using the key {@link
+   * TypeCheckHint#REPLAY_FRAME_BITMAP}.
    *
    * <p>On Android, retrieve the bitmap with: {@code hint.getAs(TypeCheckHint.REPLAY_FRAME_BITMAP,
    * Bitmap.class)}.
@@ -47,15 +48,15 @@ public interface BeforeErrorSamplingCallback {
    * the caller. Call {@code Bitmap.recycle()} when done to free native memory.
    */
   @ApiStatus.Experimental
-  public interface ReplaySnapshotObserver {
+  public interface ReplayFrameObserver {
     /**
-     * Called when a replay snapshot is captured.
+     * Called when a masked replay frame is captured.
      *
      * @param hint contains the frame bitmap under {@link TypeCheckHint#REPLAY_FRAME_BITMAP}
      * @param frameTimestamp the timestamp (in milliseconds since epoch) when the frame was captured
      * @param screenName the current screen name, or {@code null} if unknown
      */
-    void onSnapshotCaptured(@NotNull Hint hint, long frameTimestamp, @Nullable String screenName);
+    void onMaskedFrameCaptured(@NotNull Hint hint, long frameTimestamp, @Nullable String screenName);
   }
 
   private static final String CUSTOM_MASKING_INTEGRATION_NAME = "ReplayCustomMasking";
@@ -233,7 +234,7 @@ public enum SentryReplayQuality {
    */
   private @Nullable BeforeErrorSamplingCallback beforeErrorSampling;
 
-  @ApiStatus.Experimental private @Nullable ReplaySnapshotObserver snapshotObserver;
+  @ApiStatus.Experimental private @Nullable ReplayFrameObserver frameObserver;
 
   public SentryReplayOptions(final boolean empty, final @Nullable SdkVersion sdkVersion) {
     if (!empty) {
@@ -576,23 +577,24 @@ public void setBeforeErrorSampling(
   }
 
   /**
-   * Gets the observer that is notified when a replay snapshot is captured.
+   * Gets the observer that is notified when a masked replay frame is captured.
    *
    * @return the observer, or {@code null} if not set
    */
   @ApiStatus.Experimental
-  public @Nullable ReplaySnapshotObserver getSnapshotObserver() {
-    return snapshotObserver;
+  public @Nullable ReplayFrameObserver getFrameObserver() {
+    return frameObserver;
   }
 
   /**
-   * Sets the observer that is notified when a replay snapshot is captured. The frame bitmap is
-   * passed via a {@link Hint} using the key {@link TypeCheckHint#REPLAY_FRAME_BITMAP}.
+   * Sets the observer that is notified when a masked replay frame is captured. The frame bitmap
+   * (with masking already applied) is passed via a {@link Hint} using the key {@link
+   * TypeCheckHint#REPLAY_FRAME_BITMAP}.
    *
-   * @param snapshotObserver the observer, or {@code null} to clear
+   * @param frameObserver the observer, or {@code null} to clear
    */
   @ApiStatus.Experimental
-  public void setSnapshotObserver(final @Nullable ReplaySnapshotObserver snapshotObserver) {
-    this.snapshotObserver = snapshotObserver;
+  public void setFrameObserver(final @Nullable ReplayFrameObserver frameObserver) {
+    this.frameObserver = frameObserver;
   }
 }

sentry/src/main/java/io/sentry/TypeCheckHint.java

@@ -141,6 +141,6 @@ public final class TypeCheckHint {
   /** Used for Ktor Request breadcrumbs. */
   public static final String KTOR_CLIENT_REQUEST = "ktorClient:request";
 
-  /** Used for Session Replay frame bitmaps in the ReplaySnapshotObserver callback. */
+  /** Used for Session Replay frame bitmaps in the ReplayFrameObserver callback. */
   public static final String REPLAY_FRAME_BITMAP = "replay:frameBitmap";
 }