This article covers how to install Session Replay using the iOS plugin. If your app already uses the Amplitude [iOS Swift SDK](/docs/sdks/analytics/ios/ios-swift-sdk) or legacy Amplitude [iOS SDK](/docs/sdks/analytics/ios/ios-sdk), use this option. 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). {% callout type="info" heading="Unified SDK" %} Install the [Unified SDK for Swift](/docs/sdks/analytics/ios/unified-sdk) to access Session Replay along with other Amplitude products (Analytics, Experiment). The Unified SDK provides a single entry point for all Amplitude features and simplifies integration by handling initialization and configuration of all components. {% /callout %} {% partial file="session-replay/sr-ios-performance.md" /%} Session Replay captures changes to an app's view tree, including the main view and all its child views recursively. Session Replay then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each view change as a diff. When you watch the replay of a session, Session Replay applies each diff back to the original view tree in sequential order to construct the replay. Session replays have no maximum length. {% callout type="tip" heading="Report issues" %} To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios). {% /callout %} ## Before you begin The method you use depends on the version of the Amplitude iOS SDK you use. {% tabs tabs="iOS Swift SDK, iOS SDK (maintenance)" %} {% tab name="iOS Swift SDK" %} The Session Replay iOS Plugin requires that: 1. Your application runs on iOS or iPadOS. 2. You use `1.9.0` or higher of the [iOS Swift SDK](/docs/sdks/analytics/ios/ios-swift-sdk). {% /tab %} {% tab name="iOS SDK (maintenance)" %} 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. {% /tab %} {% /tabs %} {% partial file="session-replay/sr-ios-supported-versions.md" /%} ## Quickstart Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the plugin to your project dependencies. {% tabs tabs="Swift SDK, Legacy SDK" %} {% tab name="Swift SDK" %} **Swift Package Manager** 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-Swift`, use the `AmplitudeSwiftSessionReplayPlugin` target. ```swift .product(name: "AmplitudeSwiftSessionReplayPlugin", package: "AmplitudeSessionReplay") ``` **CocoaPods** Add the core library and the plugin to your Podfile. ``` pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.11.1' pod 'AmplitudeSwiftSessionReplayPlugin', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.11.1' ``` **Configure your application code** ```swift import AmplitudeSwift import AmplitudeSwiftSessionReplayPlugin // Initialize Amplitude Analytics SDK instance let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY)) // Create and Install Session Replay Plugin // Recording will be handled automatically amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0)) ``` {% /tab %} {% tab name="Legacy SDK" %} **Swift Package Manager** 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") ``` **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' ``` **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) ``` {% /tab %} {% /tabs %} ## Configuration Pass the following option when you initialize the Session Replay plugin: | Name | Type | Required | Default | Description | | ------------------------------------ | ---------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `sampleRate` | `Float` | No | `0` | Controls how many sessions Amplitude selects for replay collection. The value is a decimal between 0 and 1 (for example, `0.4`), representing the fraction of sessions Amplitude randomly selects for replay collection. Over a large number of sessions, `0.4` selects `40%` of those sessions. | | `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration ](#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-remote-config-test.md" /%} {% partial file="session-replay/sr-ios-mask-data.md" /%} ### User opt-out The Session Replay plugin follows the Amplitude-Swift SDK's `optOut` setting, and doesn't support user opt-outs on its own. ```swift // Set optOut on the Amplitude SDK let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY, optOut: true, /* other configuration */)) amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */)) ``` {% partial file="session-replay/sr-eu-data-residency.md" /%} ```swift // Set serverZone on the Amplitude SDK let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY, serverZone: .EU, /* other configuration */)) amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(/* session replay options */)) ``` {% partial file="session-replay/sr-sampling-rate.md" /%} ```swift // This configuration samples 1% of all sessions amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(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.add(plugin: AmplitudeSwiftSessionReplayPlugin( sampleRate: 0.1, quality: .automatic )) // Or set a fixed profile (low, medium, or high) amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin( 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 // Set uploadConfig through the plugin's Config initializer let config = AmplitudeSwiftSessionReplayPlugin.Config( sampleRate: 0.1, uploadConfig: UploadConfig(disableMeteredUploads: true) ) amplitude.add(plugin: AmplitudeSwiftSessionReplayPlugin(config: config)) ``` ### Disable replay collection After you enable Session Replay, it runs on your app until either: - The user leaves your app. - You call `sessionReplayPlugin.stop()`. - You remove the plugin from the SDK with `amplitude.remove(plugin: sessionReplayPlugin)`. Call `sessionReplayPlugin.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 SessionReplayPlugin instance `let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(/* session replay options */)`. {% /callout %} Call `sessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app. To capture only specific screens, initialize the plugin 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 plugin once, without starting capture let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0, autoStart: false) amplitude.add(plugin: sessionReplayPlugin) // Start capture when the user enters a screen you want to record sessionReplayPlugin.start() // Stop capture when the user leaves that screen sessionReplayPlugin.stop() ``` You can also use a feature-flag product such as [Amplitude Experiment](/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria such as location. For example, you can create a feature flag that targets a specific user group, and add that to your initialization logic: ```swift import AmplitudeSwift import AmplitudeSwiftSessionReplayPlugin // Your existing initialization logic with Amplitude-Swift SDK let amplitude = Amplitude(configuration: Configuration(apiKey: API_KEY, /* other configuration */)) if (nonEUCountryFlagEnabled) { // Create and Install Session Replay Plugin let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 0.1) amplitude.add(plugin: sessionReplayPlugin) } ``` {% 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" /%}