Implement Session Replay (iOS)

Overview

This developer guide will assist you in configuring your Swift app for Session Replay using the Session Replay SDK (Swift). Learn more about viewing captured Replays in your project here.

Prerequisite

You are already a Mixpanel customer and have the latest version of the Mixpanel Swift SDK installed (minimum supported version is v4.3.1). If not, please follow this doc to install the SDK.

Installation

To capture Session Replays in your app, add the Session Replay SDK 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 Prerequisite.

Add the following code to your **SwiftUI and UIKit.

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

We recommend using the sampling method unless you need to customize when you capture replay data.

To enable Session Replay and set your sampling rate, create a SessionReplayConfig object and set the 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.

Start with a low sampling rate, then adjust according to your specific analytics needs.

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. This is optional, and can be used primarily to programmatically start and stop recording, or exclude something specific from recording.

Start Capturing Replay Data

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.

This will have no effect if replay data collection is already in progress.

Example Usage

// manually trigger a replay capture
MPSessionReplay.getInstance()?.startRecording()

Stop Capturing Replay Data

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

This will have no effect if there is no replay data collection in progress.

Example Usage

// manually end a replay capture
MPSessionReplay.getInstance()?.stopRecording()

Example Scenarios

Additional Configuration Options

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

Currently, there are only four config options:

autoMaskedViews Example Usage

// mask images only
MPSessionReplayConfig(recordSessionsPercent: 100.0, autoMaskedViews: [.Image])
 
// disable auto masking
MPSessionReplayConfig(recordSessionsPercent: 100.0, autoMaskedViews: [])
 
// mask image, text and WebViews
MPSessionReplayConfig(recordSessionsPercent: 100.0)

autoCapture Example Usage

// auto capture on both view controller lifecycle methods and touch events
MPSessionReplayConfig(recordSessionsPerecent: 100.0, autoCapture: .enabled)
 
// auto capture only on view controller lifecycle events
MPSessionReplayConfig(recordSessionsPerecent: 100.0, autoCapture: .viewControllerLifecycle)
 
// auto capture only on touch events
MPSessionReplayConfig(recordSessionsPerecent: 100.0, autoCapture: .touch)
 
// disable auto capture
// use this if you want to keep all functionality in the conflicting SDK
MPSessionReplayConfig(recordSessionsPerecent: 100.0, autoCapture: .disabled)

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. Taking screenshots on demand at critical moments will always be preferable.

Replay ID

When a replay capture begins, a Replay ID is generated by the SDK and is attached as an event property ($mp_replay_id) to events tracked by the SDK during the capture session. Events containing the same $mp_replay_id will appear in the same Replay.

If you are sending any events not coming from the SDK, add the $mp_replay_id event property to attribute the event to a specific Replay.

You can use the getReplayId() method to return the Replay ID for the current replay capture. 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'}

Server-side Stitching

Server-Side Stitching allows you to easily watch Replays for events that were not fired from the SDK.

It works by inferring the Replay that an event belong using the Distinct ID and time property attached to the event. This is especially useful if you have events coming in from multiple sources.

For example, let’s say a user with Distinct ID “ABC” has a Replay recorded from 1-2pm. Two hours later, an event was sent from your warehouse with a timestamp of 1:35pm with Distinct ID “ABC”. Server-side Stitching will infer that the event should belong in the same Replay.

To ensure Server-Side Stitching works, call identify() from the client-side using our SDK with the user’s $user_id. This guarantees that events generated from both the client-side and server-side share the same Distinct ID. Learn more about identifying users.

Debugging

When a Replay capture begins, a “Session Recording Checkpoint” event will appear in your project, tracked as $mp_session_record. You may use this event to verify whether you have implemented Session Replay correctly.

If you are using the recommended sampling method to capture your Replays but having trouble finding the Replays in your project, try calling .startRecording() manually and see if the $mp_session_record event appears. If it does appear but you are still struggling to locate your Replays, you may want to increase your sampling rate.

You can also check the Home page for your project to check for any recent Replays listed in the “Latest Replays” card.

If you are still struggling to implement, submit a request to our Support team for more assistance.

Logging

Developers can 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

Privacy

Mixpanel offers a privacy-first approach to Session Replay, including features such as data masking. Mixpanel’s Session Replay privacy controls were designed to assist customers in protecting end user privacy. Read more here.

User Data

The Mixpanel SDK will always mask all inputs. To protect end-user privacy, input text fields cannot be unmasked.

By default, all text, images, and WebViews are also masked.

You can unmask these element at your own discretion using the autoMaskedViews config option described above.

Mark Views as Sensitive

If your app is SwiftUI-based or UIKit-based, all UITextField and UILabel components are masked by default. UITextField cannot be unmasked, while UILabels can be unmasked

You can also mark any views as sensitive using mpReplaySensitive. Views marked as “sensitive” will be masked.

Example Usage

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

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

Example Usage

// Mark any view as safe
 
// SwiftUI
BackgroundImage()
    .mpReplaySensitive(false)
 
//UIKit
let bgImage = BackgroundImage()
bgImage.mpReplaySensitive = false

Retention

User replays are stored for 30 days after the time of ingestion. There is no way to view a replay older than 30 days old.

Legal (Beta Terms)

Our Session Replay Beta Service Addendum can be found here.

The alpha and beta of Mixpanel’s mobile session replay SDK will track certain events and send them to Mixpanel so that Mixpanel can understand and improve the alpha and beta mobile session replay feature experience. These events include starting and stopping a session, adding and removing sensitive classes, adding sensitive views and adding safe views. Nothing about your application will be included in this tracking; only your usage of the Mixpanel Session Replay SDK.

FAQ

How does Session Replay work in iOS?

Session Replay observes user interactions within your app, capturing UI hierarchy changes and storing them as images, which are then sent to Mixpanel. Mixpanel reconstructs these images, applying recorded events as an end-user completes them.

Within Mixpanel’s platform, you can view a reconstruction of your end-user’s screen as they navigate your app.

However, Session Replay is not a literal video recording of your end-user’s screen; end-user actions are not video-recorded.

Can I prevent Session Replay from recording sensitive content?

The Mixpanel SDK will always mask all inputs. By default, all text, images, and WebViews on a page.

Additionally, you can customize how you leverage our SDK to fully control (1) where to record and (2) whom to record. Consider the manual capture example scenarios, SDK configuration options, and manual view masking example provided above to customize the replay capture of your implementation.

How can I estimate how many Replays I will generate?

If you already use Mixpanel, the Session Start events are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.

When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.

How does Session Replay affect my app’s performance?

There is no impact on your app’s performance when there are no user interactions or nothing changes on the screen. When there are user interactions, expect approximately 1% to 3% more CPU usage and around 1MB more memory consumption. There is no impact on disk I/O because Session Replay does not write anything to your disk.

In our own testing, the overhead is unnoticeable, however this testing was not exhaustive and you may discover the recording overhead may negatively impact your mobile application performance depending on your application specifications.

If you experience any performance degradations after installing Session Replay, please reach out to our Support team.

How Does Session Replay affect my app’s bandwidth consumption?

The bandwidth impact of Session Replay depends on the setting of the wifiOnly parameter.

By default, wifiOnly is set to true, which means replay events are only flushed to the server when the device has a wifi connection. If there is no wifi, flushes are skipped, and the events remain in the in-memory queue until WiFi is restored. This ensures no additional cellular data is used, preventing users from incurring additional data charges.

When wifiOnly is set to false, replay events are flushed with any available network connection, including cellular. In this case, the amount of cellular data consumed depends on the intensity of user interactions and the typical session length of your app. Users may incur additional data charges if large amounts of data are transmitted over cellular connections.

How does Session Replay for mobile work if my app is offline?

Session Replay for mobile does not work in offline mode.

Does it work in SwiftUI/UIKit apps?

Yes.

Does it support Obj-C based app?

Yes, Objective-C and Swift are fully interoperable.