chore: flutter manual start and stop recording (#14487)

ioannisj · web-flow · commit c440bd567c0b · 2026-02-12T17:41:22.000Z
* chore: flutter manual start and stop recording

* feat: move manual session controls to replay section

* fix: extract privacy note
diff --git a/contents/docs/session-replay/_snippets/android-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/android-manual-replay-control.mdx
@@ -0,0 +1,13 @@
+> Requires PostHog Android SDK version >= [3.16.0](https://github.com/PostHog/posthog-android/releases/tag/3.16.0).
+
+Setting `config.sessionReplay = false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.
+
+You can manually control when to start and stop session recordings using the following methods:
+
+- `startSessionReplay(resumeCurrent: Boolean)`
+  - Set **resumeCurrent** to `true` to resume a previous session recording (Default). 
+  - Set **resumeCurrent** to `false` to start a new session recording. 
+- `stopSessionReplay()` 
+  - Stops/pauses the current session recording.
+
+> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).
diff --git a/contents/docs/session-replay/_snippets/android-privacy.mdx b/contents/docs/session-replay/_snippets/android-privacy.mdx
@@ -1,3 +1,5 @@
+import SensitiveThirdPartyScreens from "./sensitive-third-party-screens.mdx"
+
 To replace any type of `View` with a redacted version in the recording, set the [tag](https://developer.android.com/reference/android/view/View#tags) to `ph-no-capture`.
 
 ```xml
@@ -28,20 +30,4 @@ To replace any type of `View` with a redacted version in the recording, set the
 ...
 ```
 
-### Handling sensitive third-party screens
-
-Third-party components (like payment forms or authentication screens) are often rendered in separate view hierarchies that can't be accessed or modified for masking.
-
-For these cases, manually controlling the recording state is the only reliable solution. For example:
-
-```android_kotlin
-// Stop session recording before showing a third-party payment sheet
-PostHog.stopSessionReplay()
-
-// Present third-party payment sheet
-presentPaymentSheet()
-
-// ... 
-// Some time later when the sheet is dismissed, resume recording
-PostHog.startSessionReplay()
-```
+<SensitiveThirdPartyScreens />
diff --git a/contents/docs/session-replay/_snippets/flutter-installation.mdx b/contents/docs/session-replay/_snippets/flutter-installation.mdx
@@ -64,9 +64,19 @@ This is needed as Flutter renders your app using a browser canvas element.
   classes="rounded"
 />
 
-## Step three: Configure replay settings 
+## Step three: Configure replay settings
 
-Add `sessionReplay = true` to your PostHog configuration alongside any of your other configuration options:
+### Automatically start session recordings
+
+Setting `config.sessionReplay = true` in your PostHog configuration will start session recordings on SDK setup.
+
+### Manually control session recordings
+
+You can programmatically start and stop session recordings. See [how to control which sessions you record](/docs/session-replay/how-to-control-which-sessions-you-record#programmatically-start-and-stop-recordings) for details.
+
+### Configuration options
+
+You can customize session replay behavior with the following configuration options:
 
 ```dart
 final config = PostHogConfig('<ph_project_api_key>');
diff --git a/contents/docs/session-replay/_snippets/flutter-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/flutter-manual-replay-control.mdx
@@ -0,0 +1,13 @@
+> Requires PostHog Flutter SDK version >= [5.14.0](https://github.com/PostHog/posthog-flutter/releases/5.14.0). Available on iOS, Android, and Web.
+
+Setting `config.sessionReplay = false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.
+
+You can manually control when to start and stop session recordings using the following methods:
+
+- `startSessionRecording({bool resumeCurrent = true})`
+  - Set **resumeCurrent** to `true` to resume a previous session recording (Default). 
+  - Set **resumeCurrent** to `false` to start a new session recording. 
+- `stopSessionRecording()` 
+  - Stops/pauses the current session recording.
+
+> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).
diff --git a/contents/docs/session-replay/_snippets/flutter-privacy.mdx b/contents/docs/session-replay/_snippets/flutter-privacy.mdx
@@ -1,3 +1,5 @@
+import SensitiveThirdPartyScreens from "./sensitive-third-party-screens.mdx"
+
 ### Masking All Texts and Images
 
 ```dart
@@ -20,3 +22,5 @@ config.sessionReplayConfig.maskAllImages = false;
     const PostHogMaskWidget(child: Text('Sensitive!'))
 ...
 ```
+
+<SensitiveThirdPartyScreens />
diff --git a/contents/docs/session-replay/_snippets/ios-installation.mdx b/contents/docs/session-replay/_snippets/ios-installation.mdx
@@ -36,17 +36,7 @@ Setting `config.sessionReplay = true` to your PostHog configuration will start s
 
 ### Manually control session recordings
 
-Setting `config.sessionReplay = false` to your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup. 
-
-You can manually control when to start and stop session recordings using the following two methods:
-
-- `startSessionRecording(resumeCurrent: Bool)`
-  - Set **resumeCurrent** to `true` to resume a previous session recording (Default). 
-  - Set **resumeCurrent** to `false` to start a new session recording. 
-- `stopSessionRecording()` 
-  - Stops/pauses the current session recording.
-
-> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).
+You can programmatically start and stop session recordings. See [how to control which sessions you record](/docs/session-replay/how-to-control-which-sessions-you-record#programmatically-start-and-stop-recordings) for details.
 
 ## Configuration options
 
diff --git a/contents/docs/session-replay/_snippets/ios-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/ios-manual-replay-control.mdx
@@ -0,0 +1,13 @@
+> Requires PostHog iOS SDK version >= [3.19.0](https://github.com/PostHog/posthog-ios/releases/tag/3.19.0).
+
+Setting `config.sessionReplay = false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.
+
+You can manually control when to start and stop session recordings using the following methods:
+
+- `startSessionRecording(resumeCurrent: Bool)`
+  - Set **resumeCurrent** to `true` to resume a previous session recording (Default). 
+  - Set **resumeCurrent** to `false` to start a new session recording. 
+- `stopSessionRecording()` 
+  - Stops/pauses the current session recording.
+
+> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).
diff --git a/contents/docs/session-replay/_snippets/ios-privacy.mdx b/contents/docs/session-replay/_snippets/ios-privacy.mdx
@@ -1,3 +1,5 @@
+import SensitiveThirdPartyScreens from "./sensitive-third-party-screens.mdx"
+
 To replace any type of `UIView` with a redacted version in the replay, set the [accessibilityIdentifier](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification/1623132-accessibilityidentifier) to `ph-no-capture`:
 
 ```swift
@@ -35,20 +37,4 @@ Apps built with Xcode 26 use a new SwiftUI rendering model that changes how Swif
 
 </CalloutBox>
 
-### Handling sensitive third-party screens
-
-Third-party components (like payment forms or authentication screens) are often rendered in separate view hierarchies that can't be accessed or modified for masking.
-
-For these cases, manually controlling the recording state is the only reliable solution. For example:
-
-```ios_swift
-// Stop session recording before showing a third-party payment sheet
-PostHogSDK.shared.stopSessionRecording()
-
-// Present third-party payment sheet
-presentPaymentSheet()
-
-// ... 
-// Some time later when the sheet is dismissed, resume recording
-PostHogSDK.shared.startSessionRecording()
-```
+<SensitiveThirdPartyScreens />
diff --git a/contents/docs/session-replay/_snippets/react-native-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/react-native-manual-replay-control.mdx
@@ -0,0 +1 @@
+Support for programmatic start/stop in React Native is planned. You can track progress in [issue #2169](https://github.com/PostHog/posthog-js/issues/2169).
diff --git a/contents/docs/session-replay/_snippets/sensitive-third-party-screens.mdx b/contents/docs/session-replay/_snippets/sensitive-third-party-screens.mdx
@@ -0,0 +1,3 @@
+### Handling sensitive third-party screens
+
+For third-party components (like payment forms or authentication screens) that can't be masked, you can manually stop and start session recordings. See [how to control which sessions you record](/docs/session-replay/how-to-control-which-sessions-you-record#programmatically-start-and-stop-recordings) for details.
diff --git a/contents/docs/session-replay/_snippets/web-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/web-manual-replay-control.mdx
@@ -0,0 +1,38 @@
+import { ProductScreenshot } from 'components/ProductScreenshot'
+
+export const ImgSampleConfigLight = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/sampling-config-light-mode.png"
+export const ImgSampleConfigDark = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/sampling-config-dark-mode.png"
+export const ImgMinDurationLight = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/min-duration-light-mode.png"
+export const ImgMinDurationDark = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/min-duration-dark-mode.png"
+
+1. For older projects, there is a section for 'Authorized domains for replay' in the [project replay settings](https://us.posthog.com/settings/environment-replay#replay-authorized-domains). Ensure your domain is added if the section is present.
+
+2. Set `disable_session_recording: true` in your [config](/docs/libraries/js/config).
+
+```js-web
+posthog.init('<ph_project_api_key>', {
+  api_host: '<ph_client_api_host>',
+  defaults: '<ph_posthog_js_defaults>',
+    disable_session_recording: true,
+    // ... other options
+})
+```
+
+3. Manually start recording by calling `posthog.startSessionRecording()`. Similarly, you can stop the recording at any point by calling `posthog.stopSessionRecording()`.
+
+By default, `startSessionRecording` obeys any ingestion controls you've set - so you might call start and not record a session because of sampling or some other control.
+
+You can pass override options to `startSessionRecording` to change this. 
+
+```
+posthog.startSessionRecording(true) // start ignoring all ingestion controls
+posthog.startSessionRecording({
+  // you don't have to send all of these
+  sampling: true || false; 
+  linked_flag: true || false; 
+  url_trigger: true || false; 
+  event_trigger: true || false 
+})
+```
+
+> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).
diff --git a/contents/docs/session-replay/_snippets/web-privacy.mdx b/contents/docs/session-replay/_snippets/web-privacy.mdx
@@ -1,3 +1,5 @@
+import SensitiveThirdPartyScreens from "./sensitive-third-party-screens.mdx"
+
 ## Input elements
 
 As any input element is highly likely to contain sensitive text such as email or password, **we mask these by default**. You can explicitly set this to false to disable the masking. You can then specify inputs types you would like to be masked.
@@ -160,7 +162,6 @@ For passwords, it is important to note that "click to show password" buttons typ
 }
 ```
 
-
 ### Selective privacy - only reveal things that are marked as safe
 
 Instead of selectively masking, we can selectively _unmask_ fields that you are sure are safe.
@@ -177,4 +178,6 @@ This assumes you are adding a data attribute to every "safe" element like `<p da
         return '*'.repeat(text.trim().length)
     },
 }
-```
+```
+
+<SensitiveThirdPartyScreens />
diff --git a/contents/docs/session-replay/how-to-control-which-sessions-you-record.mdx b/contents/docs/session-replay/how-to-control-which-sessions-you-record.mdx
@@ -7,49 +7,40 @@ availability:
 ---
 
 import { ProductScreenshot } from 'components/ProductScreenshot'
+import Tab from "components/Tab"
+import WebManualReplayControl from "./_snippets/web-manual-replay-control.mdx"
+import IOSManualReplayControl from "./_snippets/ios-manual-replay-control.mdx"
+import AndroidManualReplayControl from "./_snippets/android-manual-replay-control.mdx"
+import ReactNativeManualReplayControl from "./_snippets/react-native-manual-replay-control.mdx"
+import FlutterManualReplayControl from "./_snippets/flutter-manual-replay-control.mdx"
+
 export const ImgSampleConfigLight = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/sampling-config-light-mode.png"
 export const ImgSampleConfigDark = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/sampling-config-dark-mode.png"
 export const ImgMinDurationLight = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/min-duration-light-mode.png"
 export const ImgMinDurationDark = "https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/min-duration-dark-mode.png"
 
-There are several ways to control which sessions you record with the Web JavaScript SDK:
+There are several ways to control which sessions you record:
 
 ## Programmatically start and stop recordings
 
 Most users should initialize PostHog with the default settings (which starts recording automatically) and use the other options on this page — like [URL triggers](#with-url-trigger-conditions), [event triggers](#with-event-trigger-conditions), [feature flags](#with-feature-flags), or [sampling](#sampling) — to control what gets recorded. Manual control is only needed for advanced use cases where you need to programmatically start and stop recording at specific points in your application.
 
-> Note: For mobile replay controls, see [iOS](/docs/session-replay/privacy?tab=iOS#handling-sensitive-third-party-screens), and [Android](/docs/session-replay/privacy?tab=Android#handling-sensitive-third-party-screens) privacy controls section. Support for this method in React Native and Flutter is planned — track progress in [issue #2169](https://github.com/PostHog/posthog-js/issues/2169).
-
-1. For older projects, there is a section for 'Authorized domains for replay' in the [project replay settings](https://us.posthog.com/settings/environment-replay#replay-authorized-domains). Ensure your domain is added if the section is present.
-
-
-2. Set `disable_session_recording: true` in your [config](/docs/libraries/js/config).
-
-```js-web
-posthog.init('<ph_project_api_key>', {
-  api_host: '<ph_client_api_host>',
-  defaults: '<ph_posthog_js_defaults>',
-    disable_session_recording: true,
-    // ... other options
-})
-```
-
-3. Manually start recording by calling `posthog.startSessionRecording()`. Similarly, you can stop the recording at any point by calling `posthog.stopSessionRecording()`.
-
-By default, `startSessionRecording` obeys any ingestion controls you've set - so you might call start and not record a session because of sampling or some other control.
-
-You can pass override options to `startSessionRecording` to change this. 
-
-```
-posthog.startSessionRecording(true) // start ignoring all ingestion controls
-posthog.startSessionRecording({
-  // you don't have to send all of these
-  sampling: true || false; 
-  linked_flag: true || false; 
-  url_trigger: true || false; 
-  event_trigger: true || false 
-})
-```
+<Tab.Group tabs={['Web', 'iOS', 'Android', 'React Native', 'Flutter']}>
+    <Tab.List>
+        <Tab>Web</Tab>
+        <Tab>iOS</Tab>
+        <Tab>Android</Tab>
+        <Tab>React Native</Tab>
+        <Tab>Flutter</Tab>
+    </Tab.List>
+    <Tab.Panels>
+        <Tab.Panel><WebManualReplayControl /></Tab.Panel>
+        <Tab.Panel><IOSManualReplayControl /></Tab.Panel>
+        <Tab.Panel><AndroidManualReplayControl /></Tab.Panel>
+        <Tab.Panel><ReactNativeManualReplayControl /></Tab.Panel>
+        <Tab.Panel><FlutterManualReplayControl /></Tab.Panel>
+    </Tab.Panels>
+</Tab.Group>
 
 ## With URL trigger conditions
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Support for programmatic start/stop in React Native is planned. You can track progress in [issue #2169](https://github.com/PostHog/posthog-js/issues/2169).`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+### Handling sensitive third-party screens`
	`2`	`+`
	`3`	`+For third-party components (like payment forms or authentication screens) that can't be masked, you can manually stop and start session recordings. See [how to control which sessions you record](/docs/session-replay/how-to-control-which-sessions-you-record#programmatically-start-and-stop-recordings) for details.`