docs(android): Document manual Session Replay controls

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:
 
@@ -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
+
+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 ->
+  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}
+<application>
+  <meta-data
+    android:name="io.sentry.session-replay.session-sample-rate"
+    android:value="0.0" />
+  <meta-data
+    android:name="io.sentry.session-replay.on-error-sample-rate"
+    android:value="0.0" />
+</application>
+```
+
+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
 
 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.

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.
@@ -152,6 +152,83 @@ 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. 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. 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. 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()
+
+// 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();
+```
+
+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. 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()
+```
+
+```java {tabTitle:Java}
+Sentry.replay().stop();
+```
+
+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()
+```
+
+```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.