From 27a778073103d87d47f0ed646d0fd10d71b99dc7 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Wed, 19 Aug 2026 15:05:33 +0200 Subject: [PATCH 1/6] docs(android): Document manual Session Replay controls Explain how to start full-session or buffered recording. Document how pause, resume, stop, and flush affect the active replay. Describe manual startup with zero sample rates and the remaining on-error sampling behavior. Refs JAVA-691 Co-Authored-By: OpenAI Codex --- .../android/session-replay/configuration.mdx | 31 ++++++++ .../android/session-replay/index.mdx | 71 +++++++++++++++++++ 2 files changed, 102 insertions(+) diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx index 2134f040fd3b6..18b94d95200db 100644 --- a/docs/platforms/android/session-replay/configuration.mdx +++ b/docs/platforms/android/session-replay/configuration.mdx @@ -33,6 +33,37 @@ and the following options provide further customization: | 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). | +## Disable Automatic Replay Sampling + +If Session Replay should start only after user consent or an app-specific condition, set both sample rates to `0.0` during initialization. This disables automatic session and error recording while keeping the Session Replay integration available for manual control. + +```kotlin {tabTitle:Kotlin} {mdExpandTabs} +SentryAndroid.init(context) { options -> + options.sessionReplay.sessionSampleRate = 0.0 + options.sessionReplay.onErrorSampleRate = 0.0 +} +``` + +```java {tabTitle:Java} +SentryAndroid.init(context, options -> { + options.getSessionReplay().setSessionSampleRate(0.0); + options.getSessionReplay().setOnErrorSampleRate(0.0); +}); +``` + +```xml {tabTitle:AndroidManifest.xml} + + + + +``` + +Explicit calls to `Sentry.replay().start()` and `Sentry.replay().startBuffering()` bypass these sample rates when starting recording. With `onErrorSampleRate` set to `0.0`, call `flush()` to send a manually started buffer. See [Manual Control](/platforms/android/session-replay/#manual-control) for the complete API behavior. + ## Network Details By default, Replay will capture basic information about all outgoing http requests in your application. This includes the URL, request and response body sizes, method, and status code. The intention is to limit the chance of collecting private data. diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx index b86c62054bf55..6e5ac744513f6 100644 --- a/docs/platforms/android/session-replay/index.mdx +++ b/docs/platforms/android/session-replay/index.mdx @@ -152,6 +152,77 @@ SentryAndroid.init(context, options -> { }); ``` +## Manual Control + +Use manual control when replay recording depends on user consent, authentication, or a specific workflow. To disable automatic recording, [set both replay sample rates to `0.0`](/platforms/android/session-replay/configuration/#disable-automatic-replay-sampling). + +You can call the manual control APIs from any thread. Calls return before the requested operation completes because the SDK queues it. + +### Start Recording + +Choose the recording mode that fits your use case: + +- `start()` starts a full-session replay. +- `startBuffering()` keeps a rolling buffer of up to 30 seconds. The SDK sends the buffer when an error is sampled or you call `flush()`, then continues recording in session mode. + +Explicit calls to `start()` and `startBuffering()` bypass the configured replay sample rates when starting recording. `onErrorSampleRate` still controls whether an error sends a buffered replay. If a replay is already recording, both methods do nothing. + +```kotlin {tabTitle:Kotlin} +// Start a full-session replay. +Sentry.replay().start() + +// Or start a buffered replay instead. +// Sentry.replay().startBuffering() +``` + +```java {tabTitle:Java} +// Start a full-session replay. +Sentry.replay().start(); + +// Or start a buffered replay instead. +// Sentry.replay().startBuffering(); +``` + +### Pause Recording on Sensitive Screens + +Pause recording before showing sensitive content, such as a PIN entry screen, and resume it after the content is hidden. A manually paused replay stays paused across app background and foreground transitions until you call `resume()`. Calling `resume()` when replay is stopped does nothing. + +```kotlin {tabTitle:Kotlin} +Sentry.replay().pause() + +// Resume the same replay after leaving the sensitive screen. +Sentry.replay().resume() +``` + +```java {tabTitle:Java} +Sentry.replay().pause(); + +// Resume the same replay after leaving the sensitive screen. +Sentry.replay().resume(); +``` + +### Stop or Flush Recording + +Call `stop()` to end the current replay. A later call to `start()` or `startBuffering()` creates a new replay session. + +```kotlin {tabTitle:Kotlin} +Sentry.replay().stop() +``` + +```java {tabTitle:Java} +Sentry.replay().stop(); +``` + +Call `flush()` to send the current replay data without stopping recording. In session mode, it sends the pending segment and continues recording. In buffer mode, it sends the buffer and switches to session mode. Calling `flush()` while recording is stopped starts a new full-session replay. + +```kotlin {tabTitle:Kotlin} +Sentry.replay().flush() +``` + +```java {tabTitle:Java} +Sentry.replay().flush(); +``` + ## Privacy The SDK is recording and aggressively masking all text, images, and webviews by default. If your app has any sensitive data, you should only turn the default masking off after explicitly masking out the sensitive data, using the APIs described below. From 95ff0f9b78f3351dc517cc1e3d0c43cc7d51a7e0 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Wed, 26 Aug 2026 19:00:42 +0200 Subject: [PATCH 2/6] docs(android): Clarify replay pause lifetime Document that manual pause survives automatic replay restarts in the same process and requires an explicit resume. Refs JAVA-691 Co-Authored-By: Codex --- docs/platforms/android/session-replay/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx index 6e5ac744513f6..22917f68624a3 100644 --- a/docs/platforms/android/session-replay/index.mdx +++ b/docs/platforms/android/session-replay/index.mdx @@ -185,7 +185,7 @@ Sentry.replay().start(); ### Pause Recording on Sensitive Screens -Pause recording before showing sensitive content, such as a PIN entry screen, and resume it after the content is hidden. A manually paused replay stays paused across app background and foreground transitions until you call `resume()`. Calling `resume()` when replay is stopped does nothing. +Pause recording before showing sensitive content, such as a PIN entry screen, and resume it after the content is hidden. The SDK preserves a manual pause across app background and foreground transitions and when it automatically starts a new replay session in the same app process. Call `resume()` to continue recording. The pause state resets when the app process restarts. Calling `resume()` when replay is stopped does nothing. ```kotlin {tabTitle:Kotlin} Sentry.replay().pause() From 30afa01ce28789be0ee45a5a027f6f74d934a3c4 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Wed, 26 Aug 2026 19:02:57 +0200 Subject: [PATCH 3/6] docs(android): Add replay resume examples Explain when to keep replay paused and where to resume after deep links, notifications, or normal navigation. Refs JAVA-691 Co-Authored-By: Codex --- docs/platforms/android/session-replay/index.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx index 22917f68624a3..3e0fac940151b 100644 --- a/docs/platforms/android/session-replay/index.mdx +++ b/docs/platforms/android/session-replay/index.mdx @@ -201,6 +201,12 @@ Sentry.replay().pause(); Sentry.replay().resume(); ``` +The SDK can't determine whether foregrounding returns to the same sensitive screen or opens a different screen. For example: + +- If the app returns to the PIN entry screen, leave replay paused. +- If a deep link opens a non-sensitive product screen, call `resume()` from that destination after the sensitive content is no longer visible. +- If a notification or normal navigation opens another non-sensitive screen, call `resume()` from the new screen instead of from the sensitive screen's exit callback. + ### Stop or Flush Recording Call `stop()` to end the current replay. A later call to `start()` or `startBuffering()` creates a new replay session. From 2fac5c6384db2f624e87ce6ab5fe9d26e7bcb8f9 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Thu, 27 Aug 2026 09:55:01 +0200 Subject: [PATCH 4/6] docs(android): Clarify replay control behavior Address review wording and distinguish automatic buffered replay uploads from explicit flushes. Document how stop handles pending session and buffer data. Refs JAVA-691 Co-Authored-By: Codex --- .../platforms/android/session-replay/configuration.mdx | 4 ++-- docs/platforms/android/session-replay/index.mdx | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx index 18b94d95200db..f03c2e89db4ff 100644 --- a/docs/platforms/android/session-replay/configuration.mdx +++ b/docs/platforms/android/session-replay/configuration.mdx @@ -35,7 +35,7 @@ and the following options provide further customization: ## Disable Automatic Replay Sampling -If Session Replay should start only after user consent or an app-specific condition, set both sample rates to `0.0` during initialization. This disables automatic session and error recording while keeping the Session Replay integration available for manual control. +To configure Session Replay to start only after user consent or an app-specific condition, set both sample rates to `0.0` during initialization. This disables automatic session and error recording while keeping the Session Replay integration available for manual control. ```kotlin {tabTitle:Kotlin} {mdExpandTabs} SentryAndroid.init(context) { options -> @@ -62,7 +62,7 @@ SentryAndroid.init(context, options -> { ``` -Explicit calls to `Sentry.replay().start()` and `Sentry.replay().startBuffering()` bypass these sample rates when starting recording. With `onErrorSampleRate` set to `0.0`, call `flush()` to send a manually started buffer. See [Manual Control](/platforms/android/session-replay/#manual-control) for the complete API behavior. +Explicit calls to `Sentry.replay().start()` and `Sentry.replay().startBuffering()` bypass these sample rates. With `onErrorSampleRate` set to `0.0`, call `flush()` to send a manually started buffer. See [Manual Control](/platforms/android/session-replay/#manual-control) for the complete API behavior. ## Network Details diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx index 3e0fac940151b..7389813e3afde 100644 --- a/docs/platforms/android/session-replay/index.mdx +++ b/docs/platforms/android/session-replay/index.mdx @@ -163,9 +163,9 @@ You can call the manual control APIs from any thread. Calls return before the re Choose the recording mode that fits your use case: - `start()` starts a full-session replay. -- `startBuffering()` keeps a rolling buffer of up to 30 seconds. The SDK sends the buffer when an error is sampled or you call `flush()`, then continues recording in session mode. +- `startBuffering()` keeps a rolling buffer of up to 30 seconds. If `onErrorSampleRate` samples an error, the SDK sends the buffer automatically. Call `flush()` to send it without an error or sampling decision. After either action, recording continues in session mode. -Explicit calls to `start()` and `startBuffering()` bypass the configured replay sample rates when starting recording. `onErrorSampleRate` still controls whether an error sends a buffered replay. If a replay is already recording, both methods do nothing. +Explicit calls to `start()` and `startBuffering()` bypass the configured replay sample rates when starting recording. If a replay is already recording, both methods do nothing. ```kotlin {tabTitle:Kotlin} // Start a full-session replay. @@ -185,7 +185,7 @@ Sentry.replay().start(); ### Pause Recording on Sensitive Screens -Pause recording before showing sensitive content, such as a PIN entry screen, and resume it after the content is hidden. The SDK preserves a manual pause across app background and foreground transitions and when it automatically starts a new replay session in the same app process. Call `resume()` to continue recording. The pause state resets when the app process restarts. Calling `resume()` when replay is stopped does nothing. +Pause recording before showing sensitive content, such as a PIN entry screen, and resume it after the content is hidden. The SDK preserves a manual pause across app background and foreground transitions and when it automatically starts a new replay session in the same app process. Call `resume()` to continue recording. The pause state resets when the app process restarts. Calling `resume()` when replay is stopped does nothing; call `start()` or `startBuffering()` to create a new replay. ```kotlin {tabTitle:Kotlin} Sentry.replay().pause() @@ -209,7 +209,7 @@ The SDK can't determine whether foregrounding returns to the same sensitive scre ### Stop or Flush Recording -Call `stop()` to end the current replay. A later call to `start()` or `startBuffering()` creates a new replay session. +Call `stop()` to end the current replay. In session mode, the SDK sends any pending segment before stopping. In buffer mode, it discards the unsent buffer. A later call to `start()` or `startBuffering()` creates a new replay session. ```kotlin {tabTitle:Kotlin} Sentry.replay().stop() @@ -219,7 +219,7 @@ Sentry.replay().stop() Sentry.replay().stop(); ``` -Call `flush()` to send the current replay data without stopping recording. In session mode, it sends the pending segment and continues recording. In buffer mode, it sends the buffer and switches to session mode. Calling `flush()` while recording is stopped starts a new full-session replay. +Call `flush()` to send the current replay data without stopping the recording. In session mode, it sends the pending segment and continues recording. In buffer mode, it sends the buffer and switches to session mode. Calling `flush()` while recording is stopped starts a new full-session replay. ```kotlin {tabTitle:Kotlin} Sentry.replay().flush() From 12a224429580c189efc72243b4e6b56e52df8e69 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Thu, 27 Aug 2026 10:13:58 +0200 Subject: [PATCH 5/6] docs(android): Fix replay buffer duration Use the SDK default of 30 seconds consistently for buffered Session Replay documentation. Refs JAVA-691 Co-Authored-By: Codex --- docs/platforms/android/session-replay/configuration.mdx | 2 +- docs/platforms/android/session-replay/index.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx index f03c2e89db4ff..6f728fc660794 100644 --- a/docs/platforms/android/session-replay/configuration.mdx +++ b/docs/platforms/android/session-replay/configuration.mdx @@ -13,7 +13,7 @@ The SDK exposes the following main options to configure Session Replay for your | Key | AndroidManifest | Type | Default | Description | |-------------------------|--------------------------------------------------------|----------------------------------------------------------------------|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | sessionSampleRate | `io.sentry.session-replay.session-sample-rate` | double | `0.0` | Sample rate for replay sessions that start immediately and last the entirety of the user's session. `1.0` collects all sessions. | - | onErrorSampleRate | `io.sentry.session-replay.on-error-sample-rate` | double | `0.0` | Sample rate for buffered replays that are triggered when an error occurs. The SDK keeps the previous minute of activity and continues until the session ends when an error is sampled. | + | onErrorSampleRate | `io.sentry.session-replay.on-error-sample-rate` | double | `0.0` | Sample rate for buffered replays that are triggered when an error occurs. The SDK keeps the previous 30 seconds of activity and continues until the session ends when an error is sampled. | and the following options provide further customization: diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx index 7389813e3afde..960258a6162c1 100644 --- a/docs/platforms/android/session-replay/index.mdx +++ b/docs/platforms/android/session-replay/index.mdx @@ -106,7 +106,7 @@ The session will be terminated if the application has spent in the background mo ### Replay Captures on Errors Only -If you prefer not to record an entire session, you can elect to capture a replay only if an error occurs. In this case, the integration will buffer up to one minute worth of events prior to the error being thrown. It will continue to record the session, following the rules above regarding session life and activity. Read the [sampling](#sampling) section for configuration options. +If you prefer not to record an entire session, you can elect to capture a replay only if an error occurs. In this case, the integration will buffer up to 30 seconds of events before the error. It will continue to record the session, following the rules above regarding session life and activity. Read the [sampling](#sampling) section for configuration options. ## Sampling @@ -116,7 +116,7 @@ Sampling allows you to control how much of your website's traffic will result in replays that begin recording immediately and last the entirety of the user's session. 2. `onErrorSampleRate` - The sample rate for replays that are recorded when an error happens. This type of replay will record - up to a minute of events prior to the error and continue recording until the session + up to 30 seconds of events before the error and continue recording until the session ends. Sampling begins as soon as a session starts. `sessionSampleRate` is evaluated first. If it's sampled, the replay recording will begin. Otherwise, `onErrorSampleRate` is evaluated and if it's sampled, the integration will begin buffering the replay and will only upload it to Sentry if an error occurs. The remainder of the replay will behave similarly to a whole-session replay. From 67e68c653b62c18e8ae956aa423cac977fc4fd61 Mon Sep 17 00:00:00 2001 From: Roman Zavarnitsyn Date: Thu, 27 Aug 2026 10:57:21 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Roman Zavarnitsyn --- docs/platforms/android/session-replay/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx index 960258a6162c1..723bf7cbfb0cd 100644 --- a/docs/platforms/android/session-replay/index.mdx +++ b/docs/platforms/android/session-replay/index.mdx @@ -172,7 +172,7 @@ Explicit calls to `start()` and `startBuffering()` bypass the configured replay Sentry.replay().start() // Or start a buffered replay instead. -// Sentry.replay().startBuffering() +Sentry.replay().startBuffering() ``` ```java {tabTitle:Java} @@ -180,7 +180,7 @@ Sentry.replay().start() Sentry.replay().start(); // Or start a buffered replay instead. -// Sentry.replay().startBuffering(); +Sentry.replay().startBuffering(); ``` ### Pause Recording on Sensitive Screens