From 9ff22e68986096b9fe47d2a5c05ba35169c3efb7 Mon Sep 17 00:00:00 2001 From: NinjaLikesCheez Date: Thu, 7 May 2026 12:50:38 +0200 Subject: [PATCH 1/6] docs(apple): Add Session Replay configuration page to match Android Add a configuration reference page for Apple Session Replay, mirroring the existing Android configuration page. Covers all sessionReplay options including sampling rates, masking, quality, performance renderer flags, and network detail capture. Includes Swift and Objective-C examples for both string and NSRegularExpression URL patterns. Also shifts sidebar_order of sibling pages to make room. Co-Authored-By: Claude Sonnet 4.6 --- .../common/session-replay/configuration.mdx | 131 ++++++++++++++++++ .../common/session-replay/customredact.mdx | 2 +- .../session-replay/performance-overhead.mdx | 2 +- .../common/session-replay/troubleshooting.mdx | 2 +- 4 files changed, 134 insertions(+), 3 deletions(-) create mode 100644 docs/platforms/apple/common/session-replay/configuration.mdx diff --git a/docs/platforms/apple/common/session-replay/configuration.mdx b/docs/platforms/apple/common/session-replay/configuration.mdx new file mode 100644 index 0000000000000..c0e4210ffaae9 --- /dev/null +++ b/docs/platforms/apple/common/session-replay/configuration.mdx @@ -0,0 +1,131 @@ +--- +title: Configuration +sidebar_order: 5501 +description: "Learn about the general Session Replay configuration fields." +notSupported: + - apple.macos + - apple.watchos + - apple.tvos + - apple.visionos +--- + + + + + + + + + +## General Configuration + +Configure Session Replay inside your `SentrySDK.start` call by setting properties on `options.sessionReplay` ([Manual Initialization](/platforms/apple/guides/ios/configuration/options/)). + +The SDK exposes the following main options to configure Session Replay for your project: + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `sessionSampleRate` | `Float` | `0.0` | Sample rate for replays that start immediately and last the entirety of the user's session. `1.0` collects all sessions. | +| `onErrorSampleRate` | `Float` | `0.0` | Sample rate for buffered replays 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. | + +The following options provide further customization: + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| `maskAllText` | `Bool` | `true` | Masks all text-containing views by default. Setting this to `false` removes text views from the mask list so text appears in replays. | +| `maskAllImages` | `Bool` | `true` | Masks image views by default. Setting this to `false` removes image views from the mask list so image content is visible in replays. | +| `quality` | `SentryReplayQuality` | `.medium` | Defines the image quality of the session replay. Higher quality yields a more accurate replay at the cost of more data transfer and CPU usage. Possible values: `.low`, `.medium`, `.high`. | +| `enableViewRendererV2` | `Bool` | `true` | Enables a significantly faster view renderer (up to 5x) that reduces per-frame rendering time on the main thread. Disable only if you observe rendering issues. | +| `enableFastViewRendering` | `Bool` | `false` | Enables additional rendering speed by using the underlying `CALayer` instead of `UIView.drawHierarchy`. May produce incomplete renders for complex custom views. Only takes effect when `enableViewRendererV2` is also enabled. | +| `networkDetailAllowUrls` | `[String \| NSRegularExpression]` | `[]` | URL patterns that enable capture of request/response bodies and headers. String patterns use substring matching; `NSRegularExpression` patterns use full regex matching. See [Network Details](#network-details) below. | +| `networkDetailDenyUrls` | `[String \| NSRegularExpression]` | `[]` | URL patterns to never capture request/response bodies and headers, even if an allow pattern matches them. String patterns use substring matching; `NSRegularExpression` patterns use full regex matching. See [Network Details](#network-details) below. | +| `networkCaptureBodies` | `Bool` | `true` | Controls whether request and response bodies are captured for allowed URLs. | +| `networkRequestHeaders` | `[String]` | `["Content-Type", "Content-Length", "Accept"]` | Request header names to capture for enabled URLs. Default headers are always included alongside any additional headers you configure. | +| `networkResponseHeaders` | `[String]` | `["Content-Type", "Content-Length", "Accept"]` | Response header names to capture for enabled URLs. Default headers are always included alongside any additional headers you configure. | + +To configure masking by view class, see [Custom Masking](/platforms/apple/guides/ios/session-replay/customredact/). + +## Network Details + +By default, Replay captures basic information about all outgoing HTTP requests in your application, including the URL, request and response body sizes, method, and status code. This limits the chance of collecting private data. + +To capture additional information such as request and response headers or bodies, you need to: + +1. Enable the experimental flag: `options.experimental.enableReplayNetworkDetailsCapturing = true` +2. Specify which URLs to capture via `networkDetailAllowUrls` + +This opt-in approach lets you choose only URLs that are safe for capturing bodies and avoid any endpoints that may contain Personally Identifiable Information (PII). + + + +Body and header content will be PII-sanitized server-side, based on object keys and values. Refer to [Server-Side Scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) for more details. + + + +### Requirements +- SDK version >= [9.12.0](https://github.com/getsentry/sentry-cocoa/releases/tag/9.12.0) + +Any URL matching the given pattern(s) will be captured with additional details: + +```swift {tabTitle:Swift} +SentrySDK.start { options in + options.sessionReplay.networkDetailAllowUrls = ["https://example.com"] +} +``` + +```objc {tabTitle:Objective-C} +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.sessionReplay.networkDetailAllowUrls = @[@"https://example.com"]; +}]; +``` + +String patterns use substring matching — any URL containing the string will match. To use exact or more complex matching, pass an `NSRegularExpression`: + +```swift {tabTitle:Swift} +let apiRegex = try? NSRegularExpression(pattern: "^https://api\\.example\\.com/.*") + +SentrySDK.start { options in + options.sessionReplay.networkDetailAllowUrls = [ + "api.example.com", // substring match + apiRegex!, // regex match + ] +} +``` + +```objc {tabTitle:Objective-C} +NSRegularExpression *apiRegex = [NSRegularExpression regularExpressionWithPattern:@"^https://api\\.example\\.com/.*" + options:0 + error:nil]; + +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.sessionReplay.networkDetailAllowUrls = @[@"api.example.com", apiRegex]; +}]; +``` + +Requests to a matching URL will include request and response bodies, as well as the following default headers: + +- `Content-Type` +- `Content-Length` +- `Accept` + +To capture additional headers, configure `networkRequestHeaders` and `networkResponseHeaders`. The default headers above are always included: + +```swift {tabTitle:Swift} +SentrySDK.start { options in + options.sessionReplay.networkDetailAllowUrls = ["https://api.example.com"] + options.sessionReplay.networkRequestHeaders = ["Cache-Control", "X-My-Header"] + options.sessionReplay.networkResponseHeaders = ["Referrer-Policy", "X-Response-Header"] +} +``` + +```objc {tabTitle:Objective-C} +[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { + options.sessionReplay.networkDetailAllowUrls = @[@"https://api.example.com"]; + options.sessionReplay.networkRequestHeaders = @[@"Cache-Control", @"X-My-Header"]; + options.sessionReplay.networkResponseHeaders = @[@"Referrer-Policy", @"X-Response-Header"]; +}]; +``` + +Captured bodies are truncated to 150KB maximum. + + diff --git a/docs/platforms/apple/common/session-replay/customredact.mdx b/docs/platforms/apple/common/session-replay/customredact.mdx index 1dc783a34855d..314ba1422327c 100644 --- a/docs/platforms/apple/common/session-replay/customredact.mdx +++ b/docs/platforms/apple/common/session-replay/customredact.mdx @@ -1,6 +1,6 @@ --- title: Using Custom Masking for Session Replay -sidebar_order: 5501 +sidebar_order: 5502 description: "Learn how to mask parts of your app's data in Session Replay." notSupported: - apple.macos diff --git a/docs/platforms/apple/common/session-replay/performance-overhead.mdx b/docs/platforms/apple/common/session-replay/performance-overhead.mdx index df0672e823632..f95215135f887 100644 --- a/docs/platforms/apple/common/session-replay/performance-overhead.mdx +++ b/docs/platforms/apple/common/session-replay/performance-overhead.mdx @@ -1,6 +1,6 @@ --- title: Performance Overhead -sidebar_order: 5502 +sidebar_order: 5503 description: "Learn about how enabling Session Replay impacts the performance of your application." notSupported: - apple.macos diff --git a/docs/platforms/apple/common/session-replay/troubleshooting.mdx b/docs/platforms/apple/common/session-replay/troubleshooting.mdx index bc8d763198301..42b2018788f9f 100644 --- a/docs/platforms/apple/common/session-replay/troubleshooting.mdx +++ b/docs/platforms/apple/common/session-replay/troubleshooting.mdx @@ -1,6 +1,6 @@ --- title: Troubleshooting -sidebar_order: 5503 +sidebar_order: 5504 description: "Troubleshoot and resolve common issues with the iOS Session Replay." notSupported: - apple.macos From c811d6cbabe8f917ed9e8831c73c3a6503283397 Mon Sep 17 00:00:00 2001 From: NinjaLikesCheez Date: Thu, 7 May 2026 13:17:51 +0200 Subject: [PATCH 2/6] chore(cleanup): remove experimental option reference --- docs/platforms/apple/common/session-replay/configuration.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/platforms/apple/common/session-replay/configuration.mdx b/docs/platforms/apple/common/session-replay/configuration.mdx index c0e4210ffaae9..82daa94a168f8 100644 --- a/docs/platforms/apple/common/session-replay/configuration.mdx +++ b/docs/platforms/apple/common/session-replay/configuration.mdx @@ -51,8 +51,7 @@ By default, Replay captures basic information about all outgoing HTTP requests i To capture additional information such as request and response headers or bodies, you need to: -1. Enable the experimental flag: `options.experimental.enableReplayNetworkDetailsCapturing = true` -2. Specify which URLs to capture via `networkDetailAllowUrls` +1. Specify which URLs to capture via `networkDetailAllowUrls` This opt-in approach lets you choose only URLs that are safe for capturing bodies and avoid any endpoints that may contain Personally Identifiable Information (PII). From e0af28611a5c4df89e166958eb05ab438b669eb7 Mon Sep 17 00:00:00 2001 From: NinjaLikesCheez Date: Thu, 7 May 2026 14:34:18 +0200 Subject: [PATCH 3/6] chore(apple): Remove non-functional Objective-C examples from Replay network config docs The Objective-C code examples for networkDetailAllowUrls, networkRequestHeaders, and networkResponseHeaders do not currently work, so remove them to avoid confusion. Co-Authored-By: Claude Sonnet 4.6 --- .../common/session-replay/configuration.mdx | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/docs/platforms/apple/common/session-replay/configuration.mdx b/docs/platforms/apple/common/session-replay/configuration.mdx index 82daa94a168f8..e90099965611b 100644 --- a/docs/platforms/apple/common/session-replay/configuration.mdx +++ b/docs/platforms/apple/common/session-replay/configuration.mdx @@ -72,12 +72,6 @@ SentrySDK.start { options in } ``` -```objc {tabTitle:Objective-C} -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.sessionReplay.networkDetailAllowUrls = @[@"https://example.com"]; -}]; -``` - String patterns use substring matching — any URL containing the string will match. To use exact or more complex matching, pass an `NSRegularExpression`: ```swift {tabTitle:Swift} @@ -91,16 +85,6 @@ SentrySDK.start { options in } ``` -```objc {tabTitle:Objective-C} -NSRegularExpression *apiRegex = [NSRegularExpression regularExpressionWithPattern:@"^https://api\\.example\\.com/.*" - options:0 - error:nil]; - -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.sessionReplay.networkDetailAllowUrls = @[@"api.example.com", apiRegex]; -}]; -``` - Requests to a matching URL will include request and response bodies, as well as the following default headers: - `Content-Type` @@ -117,14 +101,6 @@ SentrySDK.start { options in } ``` -```objc {tabTitle:Objective-C} -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.sessionReplay.networkDetailAllowUrls = @[@"https://api.example.com"]; - options.sessionReplay.networkRequestHeaders = @[@"Cache-Control", @"X-My-Header"]; - options.sessionReplay.networkResponseHeaders = @[@"Referrer-Policy", @"X-Response-Header"]; -}]; -``` - Captured bodies are truncated to 150KB maximum. From efa80c1a06dc9fd3ccee39601f643bdab0bec898 Mon Sep 17 00:00:00 2001 From: NinjaLikesCheez Date: Fri, 8 May 2026 10:58:34 +0200 Subject: [PATCH 4/6] Move force unwrap to variable init Co-authored-by: Philip Niedertscheider --- docs/platforms/apple/common/session-replay/configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/apple/common/session-replay/configuration.mdx b/docs/platforms/apple/common/session-replay/configuration.mdx index e90099965611b..a42fc125ee35c 100644 --- a/docs/platforms/apple/common/session-replay/configuration.mdx +++ b/docs/platforms/apple/common/session-replay/configuration.mdx @@ -75,12 +75,12 @@ SentrySDK.start { options in String patterns use substring matching — any URL containing the string will match. To use exact or more complex matching, pass an `NSRegularExpression`: ```swift {tabTitle:Swift} -let apiRegex = try? NSRegularExpression(pattern: "^https://api\\.example\\.com/.*") +let apiRegex = try! NSRegularExpression(pattern: "^https://api\\.example\\.com/.*") SentrySDK.start { options in options.sessionReplay.networkDetailAllowUrls = [ "api.example.com", // substring match - apiRegex!, // regex match + apiRegex, // regex match ] } ``` From d03e65d7a0009b577284f74ed2cc7df1739ef2ff Mon Sep 17 00:00:00 2001 From: NinjaLikesCheez Date: Fri, 8 May 2026 11:14:24 +0200 Subject: [PATCH 5/6] chore: address some of the PR comments --- .../common/session-replay/configuration.mdx | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/platforms/apple/common/session-replay/configuration.mdx b/docs/platforms/apple/common/session-replay/configuration.mdx index a42fc125ee35c..c68f525c3abe6 100644 --- a/docs/platforms/apple/common/session-replay/configuration.mdx +++ b/docs/platforms/apple/common/session-replay/configuration.mdx @@ -19,7 +19,7 @@ notSupported: ## General Configuration -Configure Session Replay inside your `SentrySDK.start` call by setting properties on `options.sessionReplay` ([Manual Initialization](/platforms/apple/guides/ios/configuration/options/)). +Configure Session Replay inside your `SentrySDK.start` call by setting properties on `options.sessionReplay` ([Session Replay Options](/platforms/apple/guides/ios/configuration/options/#session-replay-options)). The SDK exposes the following main options to configure Session Replay for your project: @@ -39,19 +39,26 @@ The following options provide further customization: | `enableFastViewRendering` | `Bool` | `false` | Enables additional rendering speed by using the underlying `CALayer` instead of `UIView.drawHierarchy`. May produce incomplete renders for complex custom views. Only takes effect when `enableViewRendererV2` is also enabled. | | `networkDetailAllowUrls` | `[String \| NSRegularExpression]` | `[]` | URL patterns that enable capture of request/response bodies and headers. String patterns use substring matching; `NSRegularExpression` patterns use full regex matching. See [Network Details](#network-details) below. | | `networkDetailDenyUrls` | `[String \| NSRegularExpression]` | `[]` | URL patterns to never capture request/response bodies and headers, even if an allow pattern matches them. String patterns use substring matching; `NSRegularExpression` patterns use full regex matching. See [Network Details](#network-details) below. | -| `networkCaptureBodies` | `Bool` | `true` | Controls whether request and response bodies are captured for allowed URLs. | -| `networkRequestHeaders` | `[String]` | `["Content-Type", "Content-Length", "Accept"]` | Request header names to capture for enabled URLs. Default headers are always included alongside any additional headers you configure. | -| `networkResponseHeaders` | `[String]` | `["Content-Type", "Content-Length", "Accept"]` | Response header names to capture for enabled URLs. Default headers are always included alongside any additional headers you configure. | +| `networkCaptureBodies` | `Bool` | `true` | Controls whether request and response bodies are captured for allowed URLs. See [Network Details](#network-details) below. | +| `networkRequestHeaders` | `[String]` | `["Content-Type", "Content-Length", "Accept"]` | Request header names to capture for enabled URLs. Default headers are always included alongside any additional headers you configure. See [Network Details](#network-details) below. | +| `networkResponseHeaders` | `[String]` | `["Content-Type", "Content-Length", "Accept"]` | Response header names to capture for enabled URLs. Default headers are always included alongside any additional headers you configure. See [Network Details](#network-details) below. | To configure masking by view class, see [Custom Masking](/platforms/apple/guides/ios/session-replay/customredact/). ## Network Details -By default, Replay captures basic information about all outgoing HTTP requests in your application, including the URL, request and response body sizes, method, and status code. This limits the chance of collecting private data. + + +`enableReplayNetworkDetailsCapturing` is an experimental feature and is **disabled by default**. + + + +When enabled, Replay can capture basic information about all outgoing HTTP requests in your application, including the URL, request and response body sizes, method, and status code. This limits the chance of collecting private data. To capture additional information such as request and response headers or bodies, you need to: -1. Specify which URLs to capture via `networkDetailAllowUrls` +1. Enable the experimental flag `options.experimental.enableReplayNetworkDetailsCapturing` +2. Specify which URLs to capture via `networkDetailAllowUrls` This opt-in approach lets you choose only URLs that are safe for capturing bodies and avoid any endpoints that may contain Personally Identifiable Information (PII). @@ -68,6 +75,7 @@ Any URL matching the given pattern(s) will be captured with additional details: ```swift {tabTitle:Swift} SentrySDK.start { options in + options.experimental.enableReplayNetworkDetailsCapturing = true options.sessionReplay.networkDetailAllowUrls = ["https://example.com"] } ``` @@ -78,6 +86,7 @@ String patterns use substring matching — any URL containing the string will ma let apiRegex = try! NSRegularExpression(pattern: "^https://api\\.example\\.com/.*") SentrySDK.start { options in + options.experimental.enableReplayNetworkDetailsCapturing = true options.sessionReplay.networkDetailAllowUrls = [ "api.example.com", // substring match apiRegex, // regex match @@ -95,6 +104,7 @@ To capture additional headers, configure `networkRequestHeaders` and `networkRes ```swift {tabTitle:Swift} SentrySDK.start { options in + options.experimental.enableReplayNetworkDetailsCapturing = true options.sessionReplay.networkDetailAllowUrls = ["https://api.example.com"] options.sessionReplay.networkRequestHeaders = ["Cache-Control", "X-My-Header"] options.sessionReplay.networkResponseHeaders = ["Referrer-Policy", "X-Response-Header"] From e6b992dcc036bdfdf226ddc2b5ddc4ae62207db0 Mon Sep 17 00:00:00 2001 From: NinjaLikesCheez Date: Fri, 8 May 2026 11:41:10 +0200 Subject: [PATCH 6/6] docs(apple): Update common options with new session replay & experimental options --- .../apple/common/configuration/options.mdx | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/platforms/apple/common/configuration/options.mdx b/docs/platforms/apple/common/configuration/options.mdx index 9a453d55b0e3a..9996039ea66b1 100644 --- a/docs/platforms/apple/common/configuration/options.mdx +++ b/docs/platforms/apple/common/configuration/options.mdx @@ -830,6 +830,48 @@ Learn more about session replay performance in the + +URL patterns that enable detailed capture of request/response bodies and headers for matching network requests during session replay. Supports `String` (substring match) and `NSRegularExpression` (full regex match) patterns. + +Requires `options.experimental.enableReplayNetworkDetailsCapturing = true`. + + + + + +URL patterns to exclude from detailed network capture, even if they match `networkDetailAllowUrls`. Supports `String` (substring match) and `NSRegularExpression` (full regex match) patterns. + +Requires `options.experimental.enableReplayNetworkDetailsCapturing = true`. + + + + + +When enabled, request and response bodies are captured for URLs matching `networkDetailAllowUrls`. When disabled, only headers and metadata are captured. Bodies are truncated to 150KB. + +Requires `options.experimental.enableReplayNetworkDetailsCapturing = true`. + + + + + + + +Request header names to capture for URLs matching `networkDetailAllowUrls`. The default headers (`Content-Type`, `Content-Length`, `Accept`) are always included alongside any additional headers you configure. + +Requires `options.experimental.enableReplayNetworkDetailsCapturing = true`. + + + + + +Response header names to capture for URLs matching `networkDetailAllowUrls`. The default headers (`Content-Type`, `Content-Length`, `Accept`) are always included alongside any additional headers you configure. + +Requires `options.experimental.enableReplayNetworkDetailsCapturing = true`. + + + ## Profiling Options Profiling options allow you to configure how profiling data is collected. Set these via the `options.configureProfiling` closure, which receives a `SentryProfileOptions` object. @@ -1136,6 +1178,14 @@ SentrySDK.start { options in + + +When enabled, the SDK can capture request and response headers and bodies for network requests during session replay. You must also configure `options.sessionReplay.networkDetailAllowUrls` to specify which requests are captured. + +Learn more in the Network Details documentation. + + + **Removed in version 9.12.0** — Metrics has graduated to GA. Use the top-level option instead. See [sentry-cocoa#7842](https://github.com/getsentry/sentry-cocoa/pull/7842).