getsentry · romtsn · May 7, 2026 · May 7, 2026 · markushi · May 7, 2026
diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx
@@ -29,6 +29,7 @@ and the following options provide further customization:
 | networkRequestHeaders | `io.sentry.session-replay.network-request-headers`     | List&lt;String&gt;                                                       | `['Content-Type', 'Content-Length', 'Accept']`                         | Request header names to capture for enabled URLs.                                                                                       |
 | networkResponseHeaders| `io.sentry.session-replay.network-response-headers`    | List&lt;String&gt;                                                       | `['Content-Type', 'Content-Length', 'Accept']`                         | Response header names to capture for enabled URLs. |
 | debug              | `io.sentry.session-replay.debug`                        | boolean                                                            | `false`                              | Enables Session Replay debug logging, which prints diagnostic information when a replay is recorded.                                                                                                                          |
+ | captureSurfaceViews | `io.sentry.session-replay.capture-surface-views`       | boolean                                                            | `false`                              | When enabled, the SDK captures content rendered inside `SurfaceView` components (e.g. Unity, video players, maps) that are normally invisible to the default PixelCopy window capture. Only works with the `PixelCopy` strategy (default). See [SurfaceView Capture](/platforms/android/session-replay/#surfaceview-capture). **Experimental.** |
  | beforeErrorSampling | `—`                                                     | `BeforeErrorSamplingCallback`                                      | `null`                               | A callback invoked before the `onErrorSampleRate` is checked. Return `false` to skip replay capture for this error, or `true` to proceed with the normal sample rate check. If the callback throws, replay capture proceeds normally (fail-open). Only configurable in code. See [Ignore Certain Errors from Error Sampling](/platforms/android/session-replay/#ignore-certain-errors-from-error-sampling). |
 
 

diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx
@@ -201,6 +201,26 @@ options.sessionReplay.screenshotStrategy = ScreenshotStrategyType.CANVAS // or S
 <meta-data android:name="io.sentry.session-replay.screenshot-strategy" android:value="canvas|pixelCopy" />
 ```
 
+## SurfaceView Capture
+
+By default, Android `SurfaceView` components (used by Unity, video players, map SDKs, and other frameworks that render outside the normal View hierarchy) appear as black or transparent regions in session replays. This happens because `SurfaceView` renders to its own surface, which is composited by SurfaceFlinger independently from the Window and is not captured by the standard PixelCopy window capture.
-By default, Android `SurfaceView` components (used by Unity, video players, map SDKs, and other frameworks that render outside the normal View hierarchy) appear as black or transparent regions in session replays. This happens because `SurfaceView` renders to its own surface, which is composited by SurfaceFlinger independently from the Window and is not captured by the standard PixelCopy window capture.
+By default, Android `SurfaceView` components (used by Unity, video players, map SDKs, and other frameworks that render outside the normal View hierarchy) appear as black or transparent regions in session replays. This happens because `SurfaceView` renders to its own surface, which is composited by SurfaceFlinger independently from the Window and is not captured by the standard `PixelCopy` window capture.
-By default, Android `SurfaceView` components (used by Unity, video players, map SDKs, and other frameworks that render outside the normal View hierarchy) appear as black or transparent regions in session replays. This happens because `SurfaceView` renders to its own surface, which is composited by SurfaceFlinger independently from the Window and is not captured by the standard PixelCopy window capture.
+By default, Android `SurfaceView` components (used by Unity, video players, map SDKs, and other frameworks that render outside the normal View hierarchy) appear as black or transparent regions in session replays. This happens because `SurfaceView` renders to its own surface, which is composited by SurfaceFlinger independently from the Window and is not captured by the standard `PixelCopy` window capture.
+
+When `captureSurfaceViews` is enabled, the SDK captures each visible `SurfaceView` separately via `PixelCopy` and composites the result onto the replay frame. This option only works with the `PixelCopy` screenshot strategy (the default).
+
+<Alert level="warning">
+
+This option is experimental. The SDK cannot mask individual elements rendered inside a `SurfaceView` (e.g. native Unity UI, map labels, video frames) — masking granularity is at the `SurfaceView` level only. Only enable this for `SurfaceView` components whose content is safe to record.
+
+</Alert>
+
+```kotlin
+options.sessionReplay.isCaptureSurfaceViews = true
+```
+
+```XML {filename:AndroidManifest.xml}
+<meta-data android:name="io.sentry.session-replay.capture-surface-views" android:value="true" />
+```
+
 ## Error Linking
 
 Errors that happen while a replay is running will be linked to the replay, making it possible to jump between related issues and replays. However, it's **possible** that in some cases the error count reported on the **Replays Details** page won't match the actual errors that have been captured. That's because errors can be lost, and while this is uncommon, there are a few reasons why it could happen: