Session Replay iOS Plugin

This article covers how to install Session Replay using the iOS plugin. If your app already uses the Amplitude iOS Swift SDK or legacy Amplitude iOS SDK, use this option.

If you use Segment through their Analytics-Swift SDK and Amplitude (Actions) destination, choose the Segment Plugin.

If you use a provider other than Amplitude for in-product analytics, choose the standalone implementation.

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.

Before you begin

The method you use depends on the version of the Amplitude iOS SDK you use.

Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

Quickstart

Add the latest version of the plugin to your project dependencies.

dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.12.8")
]

.product(name: "AmplitudeSwiftSessionReplayPlugin", package: "AmplitudeSessionReplay")

pod 'AmplitudeSessionReplay', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'
pod 'AmplitudeSwiftSessionReplayPlugin', :git => 'https://github.com/amplitude/AmplitudeSessionReplay-iOS.git', :tag => 'v0.12.8'

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))

Configuration

Pass the following option when you initialize the Session Replay plugin:

Custom session IDs

Session Replay for iOS version 0.11.2 and later supports string session IDs, for example UUIDs, through the customSessionId property. Use a custom session ID if your project defines sessions with a custom event property instead of the Amplitude session_id.

When you set customSessionId, the value takes precedence over the session ID that the plugin syncs from the Amplitude SDK. Set the property to nil to resume using the Amplitude session ID.

// Keep a reference to the plugin to set the custom session ID
let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin(sampleRate: 1.0)
sessionReplayPlugin.customSessionId = "ef197fc7-a46f-4e6c-a77f-8d90c17065c0"
amplitude.add(plugin: sessionReplayPlugin)

// Whenever your custom session changes
sessionReplayPlugin.customSessionId = NEW_CUSTOM_SESSION_ID

For Session Replay to match custom sessions reliably, custom session IDs must follow these constraints:

• The value can't contain /. Session Replay uses / as a delimiter in the session replay ID, which has the format <deviceId>/<sessionId>.
• The value can only contain the characters a-z A-Z 0-9 _ - . | @ : =.
• The value must match the session-defining property you send on events to Amplitude. For more information, refer to Session matching.

Change masking at runtime

Set privacyConfig on the plugin to change the automatic masking level while the app runs. Set it before or after you add the plugin to Amplitude.

sessionReplayPlugin.privacyConfig = PrivacyConfig(maskLevel: .conservative)

If Remote Config supplies a masking level, it takes precedence. The plugin retains the local privacyConfig value and applies it when Remote Config doesn't supply a masking level or when you disable Remote Config.

Remote configuration

Enable remote configuration to set Sample Rate and Masking Level in Amplitude.

Block on-screen data

Session Replay supports three ways to block sensitive on-screen data. Masking setting for WebViews is in the Web view support section.

Mask level

Session Replay for iOS supports three levels of masking, configurable with the maskLevel option.

Use this option in the Session Replay configuration.

Privacy methods for UIKit

Session Replay provides an extension on UIView to manage privacy. Import the Session Replay library to access it.

import AmplitudeSessionReplay

Privacy Modifiers for SwiftUI

Session Replay provides an extension on View to manage privacy. Import the Session Replay Library to access it.

import AmplitudeSessionReplay

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.

// 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 */))

EU data residency

Session Replay is available to Amplitude Customers who use the EU data center. Set the serverZone configuration option to EU during initialization. For example:

// 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 */))

Sampling rate

By default, Session Replay captures 0% of sessions for replay. Use your SDK's sampleRate configuration option to set the proportion of sessions to capture.

For manual and dynamic sampling, quota planning, and quota accounting, go to Configure Session Replay sampling.

// 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).

// 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.

// 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.

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:

// 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 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:

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)
}

Web view support (Beta)

By default, Session Replay blocks web views in a capture. To enable capture of all WebView components, set captureWebViews to true in the Session Replay configuration.

To mask specific WebView components, use the privacy methods described in Block on-screen data.

// UIKit
webView.amp_isBlocked = false

Map View Support (Alpha)

Session Replay supports capturing map views in iOS applications. To enable map view capture, unmask the map view in your implementation.

// UIKit
mapView.amp_isBlocked = false

// SwiftUI
Map().amp_setBlocked(false)

Log Recording

Session Replay supports recording logs in iOS applications. Configure the limits with recordLogOptions when you initialize the integration, then send log messages through recordLog(level:message:date:).

import AmplitudeSessionReplay

let sessionReplay = SessionReplay(
    apiKey: API_KEY,
    recordLogOptions: .init(logCountThreshold: 2000, maxMessageLength: 4000)
)

sessionReplay.recordLog(level: .error, message: "This is an error log")

If you have implemented a log system, you can make single-point modifications to integrate log recording functionality. See the following examples for more information.

CocoaLumberjack

If you use CocoaLumberjack, you can integrate it with a custom logger provider.

class AmplitudeLogRecordLogger: DDAbstractLogger {

    private weak var plugin: SessionReplayPlugin?

    init(_ plugin: SessionReplayPlugin) {
        self.plugin = plugin
    }

    override func log(message logMessage: DDLogMessage) {
        let recordLevel: RecordLogLevel
        switch logMessage.flag {
        case .error:
            recordLevel = .error
        case .warning:
            recordLevel = .warn
        case .info:
            recordLevel = .log
        default:
            return
        }
        plugin?.recordLog(level: recordLevel,
                          message: logMessage.message,
                          date: logMessage.timestamp)
    }
}

let sessionReplayPlugin = AmplitudeSwiftSessionReplayPlugin()
amplitude.add(plugin: sessionReplayPlugin)

DDLog.add(AmplitudeLogRecordLogger(sessionReplayPlugin))

React Native

If you use console log or react-native-logs with consoleTransport, you can integrate it with RCTAddLogFunction.

RCTAddLogFunction { level, source, fileName, lineNumber, message in
  let recordLevel: RecordLogLevel
  switch level {
  case .error:
    recordLevel = .error
  case .warning:
    recordLevel = .warn
  case .info:
    recordLevel = .log
  case .fatal:
    recordLevel = .error
  case .trace:
    recordLevel = .init("trace")
  default:
    return
  }
  self.sessionReplayPlugin.recordLog(level: recordLevel, message: message)
}

Data retention, deletion, and privacy

Review consent guidance when you implement capture.

Retention period

For native and Flutter SDK retention guidance and the effective date of changes, go to the Session Replay data lifecycle reference.

DSAR API

For replay metadata returned by the DSAR API, go to Session Replay DSAR metadata.

Data deletion

For user and project deletion behavior, go to Session Replay data deletion.

Bot filter

For bot filtering and property-filter restrictions, go to Session Replay bot filtering.

Session Replay storage

If a user opts out tracking in your app, use the optOut configuration option to disable replay collection for that user.

Session Replay temporarily stores replay data data on the file system before it is uploaded. At every initialization, the least recent replays are trimmed to bring the total disk usage down to a maximum size.

Known limitations

Keep the following limitations in mind as you implement Session Replay:

• Session Replay doesn't stitch together replays from a single user across multiple projects. For example:

  • You instrument multiple apps as separate Amplitude projects with Session Replay enabled in each.
  • A known user begins on one app, and then switch to another.
  • Amplitude captures both sessions.
  • The replay for each session is available for view in the corresponding host project.

• The User Sessions chart doesn't show session replays if your organization uses a custom session definition.

• Session Replay cannot capture the following iOS views:

  • Out-of-process iOS views, such as SFSafariViewController
  • AVPlayerLayer backed views