captureNativeScreens property

bool get captureNativeScreens

Capture native screens that cover the Flutter UI (full-screen paywalls, presented view controllers, native activities) via the native replay SDK, so they appear in replay instead of a frozen Flutter frame. When enabled and a detected screen cannot be captured, a single black placeholder frame is sent instead; if that also fails, replay keeps showing the last Flutter frame. With this flag off there is no placeholder — nothing about replay changes.

Only full-screen, same-process screens are detected. Not captured: partial-height sheets (e.g. Apple Pay, share sheet), other-process content, Android dialogs/Custom Tabs, and iOS covers without an opaque background — replay keeps showing the covered Flutter UI for those.

Opt-in: enabling this starts a lightweight occlusion detector. When false (the default), the covered Flutter tree keeps recording, as before.

Captured native frames honor your maskAllTexts / maskAllImages settings — with the defaults (both true) all native text and images are masked; setting either false reveals it on native screens too.

Applies only to native screens presented over the whole app. For native views embedded in the Flutter layout, see maskAllPlatformViews.

Can be changed at runtime after setup — turning it off before presenting a sensitive native screen guarantees that screen is not captured.

Default: false. Requires native SDK support for on-demand capture.

Implementation

bool get captureNativeScreens => _captureNativeScreens;
set captureNativeScreens (bool value)

Implementation

set captureNativeScreens(bool value) {
  if (_captureNativeScreens == value) {
    return;
  }
  _captureNativeScreens = value;
  // Propagated immediately (not lazily at the next episode) so a toggle-off
  // right before presenting a native screen can never race the detector into
  // capturing it. Before setup the value crosses inside the config instead.
  if (identical(Posthog().config?.sessionReplayConfig, this)) {
    PosthogFlutterPlatformInterface.instance.setCaptureNativeScreens(value);
  }
}