diff --git a/contents/docs/session-replay/_snippets/android-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/android-manual-replay-control.mdx new file mode 100644 index 000000000000..e6f7b33a25f0 --- /dev/null +++ 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 index 1e45fadc222a..9829258ba4c0 100644 --- 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() -``` + \ No newline at end of file diff --git a/contents/docs/session-replay/_snippets/flutter-installation.mdx b/contents/docs/session-replay/_snippets/flutter-installation.mdx index 6941c48261c1..ba9bcb5a40a6 100644 --- 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(''); diff --git a/contents/docs/session-replay/_snippets/flutter-manual-replay-control.mdx b/contents/docs/session-replay/_snippets/flutter-manual-replay-control.mdx new file mode 100644 index 000000000000..0cc095fca5be --- /dev/null +++ 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 index 1b2cc51b2cc1..af8bb9310f15 100644 --- 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!')) ... ``` + + \ No newline at end of file diff --git a/contents/docs/session-replay/_snippets/ios-installation.mdx b/contents/docs/session-replay/_snippets/ios-installation.mdx index 687f234014bb..8f023e57956f 100644 --- 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 new file mode 100644 index 000000000000..590b400eb605 --- /dev/null +++ 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 index 5deed81c96cb..163cd3b9a5e5 100644 --- 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 -### 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() -``` + \ No newline at end of file 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 new file mode 100644 index 000000000000..deec6dab9cf6 --- /dev/null +++ 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 new file mode 100644 index 000000000000..17925d0f265b --- /dev/null +++ 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 new file mode 100644 index 000000000000..3f771fc7b21c --- /dev/null +++ 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('', { + api_host: '', + 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). \ No newline at end of file diff --git a/contents/docs/session-replay/_snippets/web-privacy.mdx b/contents/docs/session-replay/_snippets/web-privacy.mdx index f00d9d22e09e..38a96e73e199 100644 --- 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 `

\ No newline at end of file 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 index ebb3917e326c..f62ed7d085ee 100644 --- 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('', { - api_host: '', - 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 -}) -``` + + + Web + iOS + Android + React Native + Flutter + + + + + + + + + ## With URL trigger conditions