From 298cb5b2102b2fd6145d834b7cfd95fd7b5d36d4 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 16 Jul 2026 11:19:19 -0400 Subject: [PATCH 1/5] docs: capturing native screens in Flutter session replay Documents the new captureNativeScreens option (posthog-flutter 5.31.0): what it records, the placeholder fallback, masking interplay, and what is not detected. Co-Authored-By: Claude Fable 5 --- .../_snippets/flutter-privacy.mdx | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/contents/docs/session-replay/_snippets/flutter-privacy.mdx b/contents/docs/session-replay/_snippets/flutter-privacy.mdx index 7f8b8727ee1e..3f578f794446 100644 --- a/contents/docs/session-replay/_snippets/flutter-privacy.mdx +++ b/contents/docs/session-replay/_snippets/flutter-privacy.mdx @@ -55,4 +55,33 @@ PostHogPlatformView( > **Platform support:** On iOS, only `WKWebView`-backed platform views (for example `webview_flutter` in its default mode) are captured. Other platform view types (Google Maps, camera previews, and so on) are always masked, because the iOS compositor cannot safely snapshot arbitrary native views without risking leaking unmasked content. +### Capturing native screens + +> Requires PostHog Flutter SDK version >= [5.31.0](https://github.com/PostHog/posthog-flutter/releases). + +By default, session replay only records your Flutter UI. When a fully native screen is presented over your app (a native paywall, a presented view controller, a native activity), the replay keeps showing the last Flutter frame until the user returns. + +To record those screens too, enable `captureNativeScreens`: + +```dart +final config = PostHogConfig(''); +config.sessionReplay = true; +/// Capture full-screen native screens that cover the Flutter app. +/// Default: false. +config.sessionReplayConfig.captureNativeScreens = true; +``` + +While a native screen covers the app, capture is handed to the native PostHog SDK, so the screen's content appears in the replay. If a detected screen can't be captured, a single black placeholder frame is shown for it instead. + +Captured native screens follow your app-wide `maskAllTexts` and `maskAllImages` settings — with the defaults (both `true`), all native text and images are masked. Setting either to `false` reveals it on native screens too, including native input fields. + +Not everything is detected as a native screen. The following keep the previous behavior (replay keeps showing the covered Flutter UI): + +- Partial-height sheets (Apple Pay, share sheet, `.pageSheet`/`.formSheet` modals) +- Content rendered by another process (Apple Pay, photo picker) — blank if the surrounding screen is captured +- On Android, anything that is not a full activity in your app's process (Chrome Custom Tabs, Google Pay, dialogs, bottom sheets, permission prompts) +- On iOS, covers without an opaque background (camera previews, image/blur backdrops) + +This setting applies to whole screens presented over your app. For native views embedded inside your Flutter layout (WebViews, maps), see [masking platform views](#masking-platform-views) above. + \ No newline at end of file From 7a664f55d3f410e0e0e6f7cb67669d7d6223a182 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 16 Jul 2026 11:23:03 -0400 Subject: [PATCH 2/5] =?UTF-8?q?docs:=20clarify=20default=20behavior=20?= =?UTF-8?q?=E2=80=94=20covering=20native=20screens=20are=20not=20blacked?= =?UTF-8?q?=20out?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- contents/docs/session-replay/_snippets/flutter-privacy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contents/docs/session-replay/_snippets/flutter-privacy.mdx b/contents/docs/session-replay/_snippets/flutter-privacy.mdx index 3f578f794446..4a0a802611bd 100644 --- a/contents/docs/session-replay/_snippets/flutter-privacy.mdx +++ b/contents/docs/session-replay/_snippets/flutter-privacy.mdx @@ -59,7 +59,7 @@ PostHogPlatformView( > Requires PostHog Flutter SDK version >= [5.31.0](https://github.com/PostHog/posthog-flutter/releases). -By default, session replay only records your Flutter UI. When a fully native screen is presented over your app (a native paywall, a presented view controller, a native activity), the replay keeps showing the last Flutter frame until the user returns. +By default, session replay only records your Flutter UI. When a fully native screen is presented over your app (a native paywall, a presented view controller, a native activity), the replay keeps showing the covered Flutter UI until the user returns — unlike embedded platform views, the native screen is **not** replaced with a black box, and the Flutter UI behind it keeps recording. To record those screens too, enable `captureNativeScreens`: From 7eb77b94c26558e4201d02ef90fc15aec20ed3d5 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 16 Jul 2026 13:03:49 -0400 Subject: [PATCH 3/5] docs: native screen capture ships in 5.32.0 (5.31.0 was taken by bootstrap) Co-Authored-By: Claude Fable 5 --- contents/docs/session-replay/_snippets/flutter-privacy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contents/docs/session-replay/_snippets/flutter-privacy.mdx b/contents/docs/session-replay/_snippets/flutter-privacy.mdx index 4a0a802611bd..75c01fe22114 100644 --- a/contents/docs/session-replay/_snippets/flutter-privacy.mdx +++ b/contents/docs/session-replay/_snippets/flutter-privacy.mdx @@ -57,7 +57,7 @@ PostHogPlatformView( ### Capturing native screens -> Requires PostHog Flutter SDK version >= [5.31.0](https://github.com/PostHog/posthog-flutter/releases). +> Requires PostHog Flutter SDK version >= [5.32.0](https://github.com/PostHog/posthog-flutter/releases). By default, session replay only records your Flutter UI. When a fully native screen is presented over your app (a native paywall, a presented view controller, a native activity), the replay keeps showing the covered Flutter UI until the user returns — unlike embedded platform views, the native screen is **not** replaced with a black box, and the Flutter UI behind it keeps recording. From cd1da38c7f760cc1b4876c549b7339d8e1e1fd2e Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 16 Jul 2026 19:17:25 -0400 Subject: [PATCH 4/5] docs: runtime toggling of captureNativeScreens Co-Authored-By: Claude Fable 5 --- .../docs/session-replay/_snippets/flutter-privacy.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/contents/docs/session-replay/_snippets/flutter-privacy.mdx b/contents/docs/session-replay/_snippets/flutter-privacy.mdx index 75c01fe22114..dcef1ba2e9dc 100644 --- a/contents/docs/session-replay/_snippets/flutter-privacy.mdx +++ b/contents/docs/session-replay/_snippets/flutter-privacy.mdx @@ -75,6 +75,15 @@ While a native screen covers the app, capture is handed to the native PostHog SD Captured native screens follow your app-wide `maskAllTexts` and `maskAllImages` settings — with the defaults (both `true`), all native text and images are masked. Setting either to `false` reveals it on native screens too, including native input fields. +You can also toggle `captureNativeScreens` at runtime for per-screen control. Turning it off takes effect immediately: setting it to `false` right before presenting a sensitive native screen guarantees that screen is not captured. + +```dart +config.sessionReplayConfig.captureNativeScreens = false; +presentSensitiveNativeScreen(); +``` + +Enable it before presenting a screen you want captured — turning it on while a native screen is already up may not capture that screen on Android. + Not everything is detected as a native screen. The following keep the previous behavior (replay keeps showing the covered Flutter UI): - Partial-height sheets (Apple Pay, share sheet, `.pageSheet`/`.formSheet` modals) From ee776df264b06116d65de8b0316c0aad33ccd25c Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 16 Jul 2026 19:36:30 -0400 Subject: [PATCH 5/5] docs: en dashes per Vale, generalize the enable-before-presenting caveat Co-Authored-By: Claude Fable 5 --- .../docs/session-replay/_snippets/flutter-privacy.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contents/docs/session-replay/_snippets/flutter-privacy.mdx b/contents/docs/session-replay/_snippets/flutter-privacy.mdx index dcef1ba2e9dc..59859a497a6e 100644 --- a/contents/docs/session-replay/_snippets/flutter-privacy.mdx +++ b/contents/docs/session-replay/_snippets/flutter-privacy.mdx @@ -59,7 +59,7 @@ PostHogPlatformView( > Requires PostHog Flutter SDK version >= [5.32.0](https://github.com/PostHog/posthog-flutter/releases). -By default, session replay only records your Flutter UI. When a fully native screen is presented over your app (a native paywall, a presented view controller, a native activity), the replay keeps showing the covered Flutter UI until the user returns — unlike embedded platform views, the native screen is **not** replaced with a black box, and the Flutter UI behind it keeps recording. +By default, session replay only records your Flutter UI. When a fully native screen is presented over your app (a native paywall, a presented view controller, a native activity), the replay keeps showing the covered Flutter UI until the user returns – unlike embedded platform views, the native screen is **not** replaced with a black box, and the Flutter UI behind it keeps recording. To record those screens too, enable `captureNativeScreens`: @@ -73,7 +73,7 @@ config.sessionReplayConfig.captureNativeScreens = true; While a native screen covers the app, capture is handed to the native PostHog SDK, so the screen's content appears in the replay. If a detected screen can't be captured, a single black placeholder frame is shown for it instead. -Captured native screens follow your app-wide `maskAllTexts` and `maskAllImages` settings — with the defaults (both `true`), all native text and images are masked. Setting either to `false` reveals it on native screens too, including native input fields. +Captured native screens follow your app-wide `maskAllTexts` and `maskAllImages` settings – with the defaults (both `true`), all native text and images are masked. Setting either to `false` reveals it on native screens too, including native input fields. You can also toggle `captureNativeScreens` at runtime for per-screen control. Turning it off takes effect immediately: setting it to `false` right before presenting a sensitive native screen guarantees that screen is not captured. @@ -82,12 +82,12 @@ config.sessionReplayConfig.captureNativeScreens = false; presentSensitiveNativeScreen(); ``` -Enable it before presenting a screen you want captured — turning it on while a native screen is already up may not capture that screen on Android. +Enable it before presenting a screen you want captured – turning it on while a native screen is already up may not capture that screen. Not everything is detected as a native screen. The following keep the previous behavior (replay keeps showing the covered Flutter UI): - Partial-height sheets (Apple Pay, share sheet, `.pageSheet`/`.formSheet` modals) -- Content rendered by another process (Apple Pay, photo picker) — blank if the surrounding screen is captured +- Content rendered by another process (Apple Pay, photo picker) – blank if the surrounding screen is captured - On Android, anything that is not a full activity in your app's process (Chrome Custom Tabs, Google Pay, dialogs, bottom sheets, permission prompts) - On iOS, covers without an opaque background (camera previews, image/blur backdrops)