From 2a228c73bb5cc2aa64f70f2b6e2a75fee3daf7f5 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Thu, 7 May 2026 10:37:08 +0200 Subject: [PATCH] docs(android): Document experimental SurfaceView capture option for Session Replay Co-Authored-By: Claude Opus 4.6 (1M context) --- .../android/session-replay/configuration.mdx | 1 + .../android/session-replay/index.mdx | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx index dc4e435a6a3a6..cdc5d500ab56f 100644 --- 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<String> | `['Content-Type', 'Content-Length', 'Accept']` | Request header names to capture for enabled URLs. | | networkResponseHeaders| `io.sentry.session-replay.network-response-headers` | List<String> | `['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 index 057c0b2362105..2f0fab42d0011 100644 --- 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 ``` +## 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. + +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). + + + +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. + + + +```kotlin +options.sessionReplay.isCaptureSurfaceViews = true +``` + +```XML {filename:AndroidManifest.xml} + +``` + ## 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: