docs(apple): Document manual Session Replay controls

docs/platforms/apple/common/session-replay/configuration.mdx

@@ -45,6 +45,33 @@ The following options provide further customization:
 
 To configure masking by view class, see [Custom Masking](/platforms/apple/guides/ios/session-replay/customredact/).
 
+## Disable Automatic Replay Sampling
+
+To start Replay only after user consent, a feature flag, or a user action, set both sample rates to `0.0` during initialization. This keeps the Replay integration available for manual control without starting a recording automatically.
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+SentrySDK.start { options in
+    options.sessionReplay.sessionSampleRate = 0.0
+    options.sessionReplay.onErrorSampleRate = 0.0
+}
+```
+
+```objc {tabTitle:Objective-C}
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.sessionReplay.sessionSampleRate = 0.0;
+    options.sessionReplay.onErrorSampleRate = 0.0;
+}];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[SentryObjCSDK startWithConfigureOptions:^(SentryObjCOptions *options) {
+    options.sessionReplay.sessionSampleRate = 0.0;
+    options.sessionReplay.onErrorSampleRate = 0.0;
+}];
+```
+
+Explicit calls to `start()` and `startBuffering()` bypass these sample rates. With `onErrorSampleRate` set to `0.0`, call `flush()` to send a manually started buffer. Replay uploads remain subject to active server-side rate limits. See [Manual Control](/platforms/apple/guides/ios/session-replay/#manual-control) for the complete API behavior.
+
 ## Network Details
 
 <Alert level="warning">

docs/platforms/apple/common/session-replay/index.mdx

@@ -21,7 +21,6 @@ Before enabling Session Replay in production, verify your masking configuration
 
 </Alert>
 
-
 [Session Replay](/product/session-replay/) helps you get to the root cause of an error or latency issue faster by providing you with a reproduction of what was happening in the user's device before, during, and after the issue. You can rewind and replay your application's state and see key user interactions, like taps, swipes, network requests, and console entries, in a single UI.
 
 By default, our Session Replay SDK masks all text content, images, and user input, giving you heightened confidence that no sensitive data will leave the device. To learn more, see [product docs](/product/session-replay/).
@@ -66,7 +65,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 30 seconds worth of replay data 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 replay data 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
 
@@ -76,11 +75,105 @@ Sampling allows you to control how much of your app's traffic will result in a S
    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.
 
+## 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/apple/guides/ios/session-replay/configuration/#disable-automatic-replay-sampling).
+
+Replay lifecycle calls can be made from any thread and return before the requested operation completes.
+
+### Start Recording
+
+Choose the recording mode that fits your use case:
+
+- `start()` starts a full-session replay.
+- `startBuffering()` starts a rolling buffer of up to 30 seconds. If an error occurs, `onErrorSampleRate` determines whether the SDK sends the buffer automatically. Call `flush()` to send it without an error sampling decision.
+
+If a replay is already recording, both methods do nothing.
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+// Start a full-session replay.
+SentrySDK.replay.start()
+
+// Or start a buffered replay instead.
+// SentrySDK.replay.startBuffering()
+```
+
+```objc {tabTitle:Objective-C}
+// Start a full-session replay.
+[SentrySDK.replay start];
+
+// Or start a buffered replay instead.
+// [SentrySDK.replay startBuffering];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+// Start a full-session replay.
+[SentryObjCSDK.replay start];
+
+// Or start a buffered replay instead.
+// [SentryObjCSDK.replay startBuffering];
+```
+
+### Pause Recording on Sensitive Screens
+
+Call `pause()` before showing sensitive content, such as a PIN or payment entry screen. The SDK keeps the current replay active but excludes screenshots and touches from the paused interval. Call `resume()` after the sensitive content is hidden to continue the same replay.
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+SentrySDK.replay.pause()
+
+// Resume the same replay after leaving the sensitive screen.
+SentrySDK.replay.resume()
+```
+
+```objc {tabTitle:Objective-C}
+[SentrySDK.replay pause];
+
+// Resume the same replay after leaving the sensitive screen.
+[SentrySDK.replay resume];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[SentryObjCSDK.replay pause];
+
+// Resume the same replay after leaving the sensitive screen.
+[SentryObjCSDK.replay resume];
+```
+
+### Stop or Flush Recording
+
+Call `stop()` to end the current replay. A later call to `start()` or `startBuffering()` creates a new replay instead of resuming the stopped one.
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+SentrySDK.replay.stop()
+```
+
+```objc {tabTitle:Objective-C}
+[SentrySDK.replay stop];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[SentryObjCSDK.replay stop];
+```
+
+Call `flush()` to send the current replay data to Sentry without stopping recording. In session mode, the SDK sends the pending data and continues recording. In buffer mode, it sends the buffer and continues in session mode. If Replay is inactive, `flush()` starts a new full-session replay.
+
+```swift {tabTitle:Swift} {mdExpandTabs}
+SentrySDK.replay.flush()
+```
+
+```objc {tabTitle:Objective-C}
+[SentrySDK.replay flush];
+```
+
+```objc {tabTitle:Objective-C (SentryObjC)}
+[SentryObjCSDK.replay flush];
+```
+
 ## Privacy
 
 The SDK is recording and aggressively masking all text, images, PDF viewers, 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.