/sentry-cocoa-sdk

Session Replay — Sentry Cocoa SDK

Minimum SDK: sentry-cocoa v8.31.1+
View Renderer V2 (default): v8.50.0+
iOS 26 auto-disable safeguard: v8.57.0+

Configuration

Code Examples

Basic setup

import Sentry

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"

    // Continuously record 10% of sessions
    options.sessionReplay.sessionSampleRate = 0.1

    // Buffer and upload on error for all other sessions
    options.sessionReplay.onErrorSampleRate = 1.0
}

Sampling logic: sessionSampleRate is evaluated first. If not selected for continuous recording, the SDK switches to buffered mode and evaluates onErrorSampleRate — keeping a rolling buffer that is uploaded only when an error fires.

Session lifecycle

• Starts: SDK init or app foreground
• Ends: 30+ seconds in background, or 60-minute maximum
• Buffer mode: Keeps a rolling 30-second window; uploaded on error capture
• Segments: Chunked into 5-second segments for upload
• Resumes: Within 30 seconds of foreground using the same replay_id

Privacy masking defaults

What is masked by default:

• ✅ All text content (maskAllText = true)
• ✅ All images (maskAllImages = true)
• ✅ User input fields (always masked, regardless of settings)
• ✅ Video players
• ✅ WebViews
• ❌ Bundled image assets (considered low PII risk — shown in replay)

SwiftUI view modifiers

import Sentry

// UNMASK a specific view (show in replay despite global maskAllText/maskAllImages)
Text("Public promotion text")
    .sentryReplayUnmask()

// MASK a specific view (hide in replay even if global masking is off)
Text("\(user.creditCardNumber)")
    .sentryReplayMask()

// Visualize masking overlay in DEBUG builds / Xcode Previews
ContentView()
    .sentryReplayPreviewMask()

UIKit view instance masking

// Mask a single UIView instance
myView.sentryReplayMask()
// equivalent:
SentrySDK.replay.maskView(view: myView)

// Unmask a single UIView instance
myLabel.sentryReplayUnmask()
// equivalent:
SentrySDK.replay.unmaskView(view: myLabel)

Note: Masking targets UIView subclasses only. You cannot target UIViewController types directly.

Class-level masking (all instances of a class)

SentrySDK.start { options in
    options.sessionReplay.maskedViewClasses   = [MySecretView.self, CreditCardField.self]
    options.sessionReplay.unmaskedViewClasses = [MyPublicBanner.self]
}

Debug — visualize the masking overlay live

#if DEBUG
SentrySDK.replay.showMaskPreview()       // full opacity
SentrySDK.replay.showMaskPreview(0.5)    // 50% opacity
#endif

Exclude views from subtree traversal

For views that cause crashes or performance issues during replay capture:

options.sessionReplay.excludeViewTypeFromSubtreeTraversal("MyProblematicView")
// Force-include a system view normally excluded:
options.sessionReplay.includeViewTypeInSubtreeTraversal("CameraUI.ChromeSwiftUIView")

Reducing performance overhead

SentrySDK.start { options in
    options.sessionReplay.quality = .low                    // lower bitrate/resolution
    options.sessionReplay.enableFastViewRendering = true    // CALayer renderer (faster, less accurate)
}

// Disable entirely on low-power / low-end devices:
if ProcessInfo.processInfo.isLowPowerModeEnabled {
    options.sessionReplay.sessionSampleRate  = 0.0
    options.sessionReplay.onErrorSampleRate  = 0.0
}

Quality enum values

⚠️ iOS 26 / Xcode 26 / Liquid Glass Caveat

Apple's Liquid Glass rendering engine in iOS 26 breaks the SDK's view-snapshotting approach, causing unreliable masking and potential PII leaks.

Starting with v8.57.0, Session Replay is automatically and silently disabled when both:

• App is running on iOS 26.0 or later
• App was compiled with Xcode 26.0 or later

Replay continues to work if:

• The device runs iOS < 26
• The app was built with Xcode < 26
• UIDesignRequiresCompatibility = YES is set in Info.plist

SDKs older than v8.57.0 do not include this safeguard and may crash or leak PII on iOS 26. Upgrade immediately.

Force-enable on iOS 26+ (experimental — will be removed once masking is fixed):

SentrySDK.start { options in
    // ⚠️ WARNING: May leak PII. Only use if you understand the risk.
    options.experimental.enableSessionReplayInUnreliableEnvironment = true
}

Track the fix at getsentry/sentry-cocoa#6390.

Performance Overhead (iPhone 14 Pro benchmarks)

iPhone 8 and older: The ~25 ms capture time exceeds the 16.7 ms frame budget, causing scrolling jank. View Renderer V2 (default since v8.50.0) improved from ~155 ms to ~25 ms per capture.

Best Practices

• Never enable enableSessionReplayInUnreliableEnvironment in production without understanding the PII risk
• Set maskAllText = true and maskAllImages = true (both default) — only unmasked explicitly what's safe to show
• Use .sentryReplayUnmask() sparingly on known-safe content rather than globally disabling masking
• Start with onErrorSampleRate = 1.0 and sessionSampleRate = 0 to capture replays only on errors (lowest overhead)
• Test masking on real devices — use SentrySDK.replay.showMaskPreview() in DEBUG builds to verify

Troubleshooting