Mixpanel Session Replay SDKs: Swift

Getting started

The Session Replay SDK for Swift is an supplementary SDK that complements the main Swift SDK, enabling you to visually replay your users’ app interactions through the Session Replay feature. Please refer to our developer guide on implementing Session Replay for a detailed walkthrough.

If you have not installed the main Swift SDK yet, navigate to the Quickstart Guide.

The Library Source Code is documented in our GitHub repo.

Installing the Library

Add the Session Replay SDK for Swift using Swift Package Manager directly in Xcode:

1. In Xcode, go to File → Add Package Dependencies…
2. Paste the GitHub URL: https://github.com/mixpanel/mixpanel-ios-session-replay-package
3. Follow the prompts to select the latest version and add the package to your project.

Initialize

You should have the main Mixpanel Swift SDK installed (minimum version v4.3.1), if not, please refer to the Quickstart Guide.

SwiftUI

import Mixpanel
import MixpanelSessionReplay
 
struct SessionReplayDemoApp: App {
    @State private var isActive = true
    @Environment(\\.scenePhase) private var scenePhase
 
    var body: some Scene {
        WindowGroup {
            ...
        }
        .onChange(of: scenePhase) {
            if scenePhase == .active {
                let config = MPSessionReplayConfig(wifiOnly: false, recordSessionsPercent: 100.0)
                let sessionReplayInstance = MPSessionReplay.initialize(token: Mixpanel.mainInstance().apiToken, distinctId: Mixpanel.mainInstance().distinctId, config: config)
 
                sessionReplayInstance.loggingEnabled = true
                sessionReplayInstance.startRecording()
            }
        }
}

UIKit

import Foundation
import UIKit
 
import Mixpanel
import MixpanelSessionReplay
 
class AppDelegate: UIResponder, UIApplicationDelegate {
 
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        Mixpanel.initialize(token: token, trackAutomaticEvents: true)
 
        let config = MPSessionReplayConfig(
            wifiOnly: false,
            recordSessionsPercent: 100.0
        )
        let sesionReplayInstance = MPSessionReplay.initialize(
            token: Mixpanel.mainInstance().apiToken,
            distinctId: Mixpanel.mainInstance().distinctId,
            config: config
        )
        #if DEBUG
        Mixpanel.mainInstance().loggingEnabled = true
        MPSessionReplay.getInstance()?.loggingEnabled = true
				#endif
        return true
    }
 
    func applicationDidBecomeActive(_ application: UIApplication) {
        MPSessionReplay.getInstance()?.startRecording()
    }
 
}

Capturing Replays

You can capturing replay data using a sampling method (recommended), or customize when and where replays are captured manually using methods provided by the Session Replay Swift SDK.

Sampling

To enable Session Replay and set your sampling rate, use the SessionReplayConfig object and set recordSessionsPercent with a value between 0.0 and 100.0.

At 0.0 no sessions will be recorded, at 100.0 all sessions will be recorded.

Example Usage

// records 1% of all sessions
MPSessionReplayConfig(recordSessionsPercent: 1.0)

Manual Capture

To programatically start and stop replay capture, use the .startRecording() and .stopRecording() methods.

Start Recording

Call .startRecording() to force recording to begin, regardless of the recordSessionsPercent init option.

The recording automatically stops when the app goes to the background. Therefore, if you want to continuously record the replays, you will need to restart the replay once the app becomes active again.

Example Usage

// manually trigger a replay capture
MPSessionReplay.getInstance()?.startRecording()
// no effect if recording is already in progress

Stop Recording

Call .stopRecording() to stop any active replay data collection. The SDK automatically stops recording when the app goes to the background.

Example Usage

// manually end a replay capture
MPSessionReplay.getInstance()?.stopRecording()
// no effect if recording is not already in progress

Config Options

Upon initialization you can provide a SessionReplayConfig object to customize your replay capture behavior.

Currently, there are four config options:

Example Usage

// mask images only
// only send recordings on wifi
MPSessionReplayConfig(autoMaskedViews: [.Image], wifiOnly: true)

Manual Screenshot Capture

If you have partially or completely disabled automatic screen capture via the autoCapture config setting above, you can manually capture screenshots by calling .captureScreenshot():

Example Usage

// manually capture screenshots
MPSessionReplay.getInstance()?.captureScreenshot()
 
// manually capture screenshots triggered by a touch event
MPSessionReplay.getInstance()?.captureScreenshot(withTouchEvent: touchEvent)

If you choose to disable auto capture and do manual screen capturing instead, it will be up to you to determine when, where and how you call the .captureScreenshot() method in your application. The most naïve approach would be to call it on a Timer.

Example Usage

// trigger manual screenshot capture using Timer
let screenshotTimer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in
    MPSessionReplay.getInstance()?.captureScreenshot()
}

Keeping in mind that this is relatively inefficient and will result in capturing unnecessary/unchanged screenshots, it is also possible to miss important moments in between the timed screenshots.

Mark Views as Sensitive

Mark any views as sensitive by setting mpReplaySensitive to true. Views marked as “sensitive” will be masked.

Set mpReplaySensitive to false to mark any view as safe. Views marked as “safe” will not be masked.

Example Usage

// Mark any view as sensitive
 
// SwiftUI
Image("family photo")
	.mpReplaySensitive(true)
 
// UIKit
let ccView = CreditCardUIView()
ccView.mpReplaySensitive = true

All UITextField and UILabel components are masked by default. UITextField cannot be unmasked, while UILabels can be unmasked

Get Replay ID

Use the getReplayId() method to return the Replay ID for the current replay recording. The method will return an empty object if there is no active replay capture in progress.

Example Usage

// return the $mp_replay_id for the currently active capture
MPSessionReplay.getInstance()?.getReplayId()
// {$mp_replay_id: '19221397401184-063a51e0c3d58d-17525637-1d73c0-1919139740f185'}

Flushing

Use the flush() method to manually flush replay events in queue.

// trigger manual flushing for replay events
MPSessionReplay.getInstance()?.flush()

Debug Mode

Enable or disable logging with the loggingEnabled property of the MPSessionReplay object.

Example Usage

let token = Mixpanel.mainInstance().apiToken
let distinctId = Mixpanel.mainInstance().distinctId
let config = MPSessionReplayConfig(wifiOnly: false, recordSessionsPercent: 50.0)
let sessionReplayInstance = MPSessionReplay.initialize(token: token, distinctId: distinctId, config: config)
sessionReplayInstance.loggingEnabled = true // enable debug log

Replay Retention

User replays are stored for 30 days after the time of ingestion.

Release History

See all releases.