{% partial file="session-replay/sr-ios-eap.md" /%} This article covers Session Replay installation through the [iOS SDK middleware](/docs/sdks/sdk-middleware). If your app already uses the [(maintenance) Amplitude SDK](/docs/sdks/analytics/ios/ios-sdk), use this option. If your app already uses the [(latest) iOS Swift SDK](/docs/sdks/analytics/ios/ios-swift-sdk), choose the [Session Replay iOS SDK Plugin](/docs/sdks/session-replay/session-replay-ios-plugin). If you use Segment through their Analytics-Swift SDK and [Amplitude (Actions) destination](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/), choose the [Segment Plugin](/docs/sdks/session-replay/session-replay-ios-segment-integration). If you use a provider other than Amplitude for in-product analytics, choose the [standalone implementation](/docs/sdks/session-replay/session-replay-ios-standalone-sdk). {% partial file="session-replay/sr-ios-performance.md" /%} ## Before you begin The Session Replay Middleware requires that: 1. Your application runs on iOS or iPadOS. 2. You use `8.22.0` or higher of the [(maintenance) Amplitude iOS SDK](/docs/sdks/analytics/ios/ios-sdk). 3. You can provide a device ID to the SDK. {% partial file="session-replay/sr-ios-supported-versions.md" /%} ## Quickstart Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the middleware to your project dependencies. {% tabs tabs="SPM, CocoaPods" %} {% tab name="SPM" %} Add Session Replay as a dependency in your Package.swift file, or the Package list in Xcode. ```swift dependencies: [ .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.11.1") ] ``` For integrating with `Amplitude-iOS`, use the `AmplitudeiOSSessionReplayMiddleware` target. ```swift .product(name: "AmplitudeiOSSessionReplayMiddleware", package: "AmplitudeSessionReplay") ``` {% /tab %} {% tab name="CocoaPods" %} Add the core library and the middleware to your Podfile. ``` pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.11.1' pod 'AmplitudeiOSSessionReplayMiddleware', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.11.1' ``` {% /tab %} {% /tabs %} Configure your application code: ```swift import Amplitude import AmplitudeiOSSessionReplayMiddleware // Initialize Amplitude Analytics SDK instance let amplitude = Amplitude.instance() // Although not required, we recommend enabling session start and end events when enabling Session Replay amplitude.defaultTracking.sessions = true // Create and Install Session Replay Middleware // Recording will be handled automatically amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1)) amplitude.initializeApiKey(API_KEY) ``` ## Configuration Pass the following options when you initialize the Session Replay middleware: | Option | Type | Required | Default | Description | | ------------------------------------ | ---------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `sampleRate` | `Float` | No | `0` | Controls how many sessions to select for replay collection. Use a decimal between 0 and 1, for example `0.4`, representing the fraction of sessions randomly selected for replay collection. Over a large number of sessions, `0.4` selects `40%` of those sessions. For more information, refer to [Sampling rate](#sampling-rate). | | `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables remote configuration for this instance of Session Replay. | | `autoStart` | `Bool` | No | `true` | Controls whether Session Replay begins capturing automatically when it initializes. | | `maskLevel` | `MaskLevel` | No | `.medium` | Sets how much on-screen content Session Replay masks. Use `.light`, `.medium`, or `.conservative`. For more detail, refer to [Mask level](#mask-level). | | `captureWebViews` | `Bool` | No | `false` | Enables capture of web view content. By default, Session Replay blocks web views. | | `webviewMappings` | `[String: String]` | No | `[:]` | Maps substrings in captured web view content to replacement values. When you enable `captureWebViews`, Session Replay applies each entry as a case-insensitive find-and-replace on the web view recording data before upload. This is an advanced option; most apps leave it empty. | | `recordLogOptions.logCountThreshold` | `Int` | No | `1000` | Sets the maximum number of logs per session. | | `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Sets the maximum length of a log message. | | `quality` | `QualityProfile` | No | `.high` | Controls capture and encoding quality (for example, frame rate and image resolution). Use `.low`, `.medium`, or `.high` to balance replay fidelity with performance and storage. Use `QualityProfile.automatic` to let the SDK choose a profile based on the device. | | `uploadConfig` | `UploadConfig` | No | `UploadConfig()` | Controls when Session Replay uploads data. Use `UploadConfig(disableMeteredUploads: true)` to pause uploads on metered networks (for example, cellular). | {% partial file="session-replay/sr-ios-mask-data.md" /%} ### User opt-out The Session Replay middleware follows the Amplitude-iOS SDK's `optOut` setting and doesn't support user opt-outs on its own. ```swift // Set optOut on the Amplitude SDK amplitude.optOut = true amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */)) ``` {% partial file="session-replay/sr-eu-data-residency.md" /%} ```swift // Set serverZone on the Amplitude SDK amplitude.setServerZone(.EU) amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* session replay options */)) ``` {% partial file="session-replay/sr-sampling-rate.md" /%} ```swift // This configuration samples 1% of all sessions amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.01)) ``` ### Recording quality Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device (for example, high on newer devices, lower on older ones). ```swift // Use automatic profile selection based on device amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware( sampleRate: 0.1, quality: .automatic )) // Or set a fixed profile (low, medium, or high) amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware( sampleRate: 0.1, quality: .medium )) ``` ### Disable uploads on metered networks Avoid using the user's cellular data by pausing Session Replay uploads while the device is on a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection. ```swift amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware( sampleRate: 0.1, uploadConfig: UploadConfig(disableMeteredUploads: true) )) ``` ### Disable replay collection After it's enabled, Session Replay runs on your app until either: - The user leaves your app. - You call `sessionReplayMiddleware.stop()`. - You remove the middleware from the SDK with `amplitude.removeEventMiddleware(sessionReplayMiddleware)`. Call `sessionReplayMiddleware.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area. {% callout type="note" heading="Keep a reference" %} This requires keeping a reference to the Session Replay Middleware instance `let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(/* session replay options */)`. {% /callout %} Call `sessionReplayMiddleware.start()` to re-enable replay collection when the user returns to an unrestricted area of your app. To capture only specific screens, initialize the middleware with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens: ```swift // Add the middleware once, without starting capture let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 1.0, autoStart: false) amplitude.addEventMiddleware(sessionReplayMiddleware) // Start capture when the user enters a screen you want to record sessionReplayMiddleware.start() // Stop capture when the user leaves that screen sessionReplayMiddleware.stop() ``` You can also use a feature flag product like [Amplitude Experiment](/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria like location. For example, you can create a feature flag that targets a specific user group and add that to your initialization logic: ```swift import Amplitude import AmplitudeiOSSessionReplayMiddleware // Your existing initialization logic with Amplitude-iOS SDK let amplitude = Amplitude.instance() if (nonEUCountryFlagEnabled) { // Create and Install Session Replay Middleware let sessionReplayMiddleware = AmplitudeiOSSessionReplayMiddleware(sampleRate: 0.1) amplitude.addEventMiddleware(sessionReplayMiddleware) } amplitude.initializeApiKey(API_KEY) ``` {% partial file="session-replay/sr-ios-webview.md" /%} {% partial file="session-replay/sr-ios-mapview-support.md" /%} {% partial file="session-replay/sr-ios-log-recording.md" /%} {% partial file="session-replay/sr-data-retention.md" /%} {% partial file="session-replay/sr-ios-storage.md" /%} {% partial file="session-replay/sr-ios-known-limitations.md" /%}