Session Replay iOS Middleware

This article covers Session Replay installation through the iOS SDK middleware. If your app already uses the (maintenance) Amplitude SDK, use this option.

If your app already uses the (latest) iOS Swift SDK, choose the Session Replay iOS SDK Plugin.

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.

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.
3. You can provide a device ID to the SDK.

Supported iOS versions

Session Replay supports a minimum target version of iOS 13.

Quickstart

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

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

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

Configure your application code:

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:

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 middleware follows the Amplitude-iOS SDK's optOut setting and doesn't support user opt-outs on its own.

// Set optOut on the Amplitude SDK
amplitude.optOut = true
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* 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
amplitude.setServerZone(.EU)
amplitude.addEventMiddleware(AmplitudeiOSSessionReplayMiddleware(/* 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.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).

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

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.

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:

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

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)

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