This article covers how to install Session Replay for iOS using the standalone SDK. Choose this option if you use a provider other than Amplitude for in-product analytics. If your app already uses an [Amplitude iOS SDK](/docs/sdks/analytics/ios/ios-swift-sdk), use the [Session Replay iOS SDK Plugin](/docs/sdks/session-replay/session-replay-ios-plugin) instead. If you use Segment through the 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). {% partial file="session-replay/sr-ios-performance.md" /%} {% 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 Session Replay Standalone SDK requires that: 1. Your application runs on iOS or iPadOS. 2. You track sessions with a timestamp that you can pass to the SDK. You inform the SDK whenever a session timestamp changes. 3. You can provide a device ID to the SDK. 4. The `Session ID` and `Device ID` you pass to the Standalone SDK match those sent as event properties to Amplitude. The Standalone SDK doesn't provide session management. Your application or a third-party integration must update the SDK with changes to `Session ID` and `Device ID`. {% partial file="session-replay/sr-ios-supported-versions.md" /%} ## Quickstart Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of Session Replay 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") ] ``` To integrate with third-party analytics, use the `AmplitudeSessionReplay` target. ```swift .product(name: "AmplitudeSessionReplay", package: "AmplitudeSessionReplay") ``` {% /tab %} {% tab name="CocoaPods" %} Add Session Replay to your Podfile. ``` pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.11.1' ``` {% /tab %} {% /tabs %} Configure your application code. 1. Create a `SessionReplay` instance. Pass the API key, and a session identifier and device identifier if available. 2. Call `sessionReplay.start()` to begin capturing replays. The standalone SDK doesn't start capture automatically, so you must call `start()` once you set the device and session identifiers. 3. When the session identifier or device identifier changes, pass the new value to Amplitude with `sessionReplay.sessionId` or `sessionReplay.deviceId`, respectively. 4. Collect Session Replay properties to send with other event properties using `sessionReplay.additionalEventProperties`. ```swift import AmplitudeSessionReplay import ThirdPartyAnalytics // Initialize the standalone session replay SDK let sessionReplay = SessionReplay(apiKey: amplitude.apiKey, deviceId: DEVICE_ID, sessionId: SESSION_ID, sampleRate: 0.1) // Start capturing replays. The standalone SDK doesn't start automatically. sessionReplay.start() // Track an event // Get session replay properties for this session var eventProperties = event.eventProperties ?? [:] eventProperties.merge(sessionReplay.additionalEventProperties) { (current, _) in current } event.eventProperties = eventProperties ThirdPartyAnalytics.track(event) // Handle session ID changes // Whenever the session ID changes ThirdPartyAnalytics.setSessionId(sessionId) // Update the session ID in session replay sessionReplay.sessionId = ThirdPartyAnalytics.getSessionId() // Handle device ID changes // Whenever the device ID changes ThirdPartyAnalytics.setDeviceId(deviceId) // Update the device ID in session replay sessionReplay.deviceId = ThirdPartyAnalytics.getDeviceId() ``` ## Configuration Pass the following configuration options when you initialize the Session Replay SDK. | Name | Type | Required | Default | Description | | ------------------------------------ | ---------------- | -------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | `String` | Yes | n/a | Sets the Amplitude API key. | | `deviceId` | `String` | Yes | `nil` | Sets an identifier for the device running your application. | | `sessionId` | `Int64` | Yes | `-1` | Sets an identifier for the user's current session. The value must use milliseconds since epoch (Unix timestamp). | | `sampleRate` | `Float` | No | `0` | Controls how many sessions to select for replay collection. Use a decimal between 0 and 1, for example `0.4`, to set the fraction of sessions Amplitude randomly selects. Over a large number of sessions, `0.4` selects 40% of those sessions. | | `optOut` | `Bool` | No | `false` | Sets permission to collect replays for sessions. A value of `true` prevents Amplitude from collecting session replays. | | `logger` | `CoreLogger?` | No | `nil` | Sets a custom logger to emit log messages to a destination you choose. When `nil`, Session Replay logs errors through an OS logger. | | `serverZone` | `ServerZone` | No | `.US` | EU or US. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in the EU data center. | | `enableRemoteConfig` | `Bool` | No | `true` | Enables or disables [remote configuration](#remote-configuration) for this instance of Session Replay. | | `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` | Configures the maximum number of logs per session. | | `recordLogOptions.maxMessageLength` | `Int` | No | `2000` | Configures 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 Session Replay provides an opt-out configuration option. Passing `optOut: true` during initialization prevents Amplitude from collecting session replays. For example: ```swift // Pass a boolean value to indicate a user's opt-out status let sessionReplay = SessionReplay(apiKey: API_KEY, optOut: true, /* other session replay options */) ``` {% partial file="session-replay/sr-eu-data-residency.md" /%} ```swift // Set serverZone to EU let sessionReplay = SessionReplay(apiKey: API_KEY, serverZone: .EU, /* other session replay options */) ``` {% partial file="session-replay/sr-sampling-rate.md" /%} ```swift // This configuration samples 1% of all sessions let sessionReplay = SessionReplay(apiKey: API_KEY, sampleRate: 0.01, /* other session replay options */) ``` ### Recording quality Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and image resolution. Higher profiles use a higher frame rate and 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 let sessionReplay = SessionReplay(apiKey: API_KEY, deviceId: DEVICE_ID, sessionId: SESSION_ID, quality: .automatic, /* other session replay options */) // Or set a fixed profile (low, medium, or high) let sessionReplay = SessionReplay(apiKey: API_KEY, deviceId: DEVICE_ID, sessionId: SESSION_ID, quality: .medium, /* other session replay options */) ``` ### Disable uploads on metered networks Avoid using the user's cellular data by pausing Session Replay uploads while the device uses a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection. ```swift let sessionReplay = SessionReplay(apiKey: API_KEY, deviceId: DEVICE_ID, sessionId: SESSION_ID, uploadConfig: UploadConfig(disableMeteredUploads: true), /* other session replay options */) ``` ### Disable replay collection After you enable Session Replay, it runs on your app until either: - The user leaves your app. - You call `sessionReplay.stop()`. Call `sessionReplay.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area. Call `sessionReplay.start()` to re-enable replay collection when the user returns to an unrestricted area of your app. Because `start()` and `stop()` resume and pause capture on the same instance, you can call them on screen transitions to record only the screens you choose. 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, create a feature flag that targets a specific user group, and add it to your initialization logic: ```swift import AmplitudeSessionReplay import ThirdPartyAnalytics let sessionReplay = SessionReplay(apiKey: amplitude.apiKey, deviceId: DEVICE_ID, sessionId: SESSION_ID, sampleRate: 1.0) if (nonEUCountryFlagEnabled) { sessionReplay.start() } ``` {% 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" /%} {% partial file="session-replay/sr-ios-troubleshooting.md" /%}