iOS Session Replay

Session Replay records what a user saw and did in your iOS application, so you can watch a bug happen instead of reconstructing it from a stack trace. Replays are linked to the RUM session they belong to, so you can move from an error straight to the recording.

Session Replay ships as its own product, AtatusSessionReplay, and runs on top of RUM.

How it records

The SDK does not record the screen as video. It walks the view hierarchy and captures the shape of each view: its frame, background, border, corner radius, opacity, and the type-specific details such as label text, switch position, or image content. Those become wireframes that the player reassembles into a replay.

Two consequences follow from that design:

• Masking happens on the device, before anything is written to disk. Text you mask never leaves the device at all.
• Snapshots are taken when the screen changes, at most ten times a second, and not at all while the screen is static.

Prerequisites

• RUM is set up and tracking views. See iOS Monitoring Setup.
• iOS 15.0 or later.
• The AtatusSessionReplay product is added to your target.

Setup

1. Add the product

With Swift Package Manager, add the AtatusSessionReplay product to your target. With CocoaPods, declare the pod:

pod 'AtatusSessionReplay', '~> 1.0'

2. Enable Session Replay

Enable it after RUM, in the same place you initialize the SDK:

import AtatusCore
import AtatusRUM
import AtatusSessionReplay

Atatus.initialize(
    with: Atatus.Configuration(
        licenseKey: "<LICENSE_KEY>",
        env: "<ENV_NAME>",
        service: "<APP_NAME>"
    ),
    trackingConsent: .granted
)

RUM.enable(
    with: RUM.Configuration(
        uiKitViewsPredicate: DefaultUIKitRUMViewsPredicate(),
        uiKitActionsPredicate: DefaultUIKitRUMActionsPredicate()
    )
)

SessionReplay.enable(
    with: SessionReplay.Configuration(replaySampleRate: 20)
)

The defaults mask all text, all images, and all touches, so a replay recorded with no privacy configuration shows layout and interaction without revealing content. Relax that deliberately, and per view rather than globally.

Configuration

Sampling

The replay rate applies to sessions RUM has already sampled, and the two multiply. With a RUM sessionSampleRate of 80 and a replaySampleRate of 20, one in five recorded sessions has a replay, which is 16 percent of all sessions:

RUM.enable(with: RUM.Configuration(sessionSampleRate: 80))
SessionReplay.enable(with: SessionReplay.Configuration(replaySampleRate: 20))

The decision is made once per session and derived from the session ID, so sessions with a replay are always a subset of the sessions RUM kept. A session either has a complete replay or none.

Start and stop recording yourself

To hold recording back until a point you choose, for example until the user opts in, enable the product without starting it:

SessionReplay.enable(
    with: SessionReplay.Configuration(
        replaySampleRate: 100,
        startRecordingImmediately: false
    )
)

// Later, when the user opts in
SessionReplay.startRecording()

// And to stop again
SessionReplay.stopRecording()

Stopping is not the same as withdrawing consent. It stops new records, and anything already recorded still uploads. To delete collected data, set consent to .notGranted or call Atatus.clearAllData().

Mask sensitive content

Text and input

textAndInputPrivacyLevel divides text into four kinds and treats each differently:

Static text is masked character by character, so "Jane Doe" becomes "xxxx xxx". Word lengths and spacing survive, which keeps the layout faithful, so treat the length of a string as something that does leave the device.

Sensitive fields are always ***, at every level and with no way to reveal them. A field counts as sensitive when it is a secure text entry field, or when its textContentType is a password, one-time code, email address, telephone number, credit card number, postal address, or postal code.

At .maskAll and .maskAllInputs, the state of a control is masked too: a switch loses its on and off position, a slider loses its value, a stepper and a date picker lose their selection, and a segmented control loses the selected segment.

Images

imagePrivacyLevel decides which images are recorded:

.maskNonBundledOnly is the useful middle ground: your interface keeps its icons while user content, such as a profile photo or a document preview, stays masked.

Touches

touchPrivacyLevel is .hide by default, which records no touch coordinates at all. Set .show to draw touch indicators in the replay:

SessionReplay.enable(
    with: SessionReplay.Configuration(
        replaySampleRate: 100,
        touchPrivacyLevel: .show
    )
)

Override privacy for one view

Global levels are the floor, not the ceiling. Any UIKit view can carry its own levels, which its subviews inherit:

import AtatusSessionReplay

// Reveal a label that is not sensitive, although the global level masks all text
priceLabel.atatus.sessionReplayPrivacyOverrides.textAndInputPrivacy = .maskSensitiveInputs

// Record one specific image
logoImageView.atatus.sessionReplayPrivacyOverrides.imagePrivacy = .maskNone

// Record touches on this subtree only
checkoutView.atatus.sessionReplayPrivacyOverrides.touchPrivacy = .show

// Replace a view and everything inside it with an opaque block
creditCardFormView.atatus.sessionReplayPrivacyOverrides.hide = true

A child's value wins over its parent's, except hide, which cannot be undone by a child. A hidden view is recorded as a solid placeholder, so the replay keeps the space it occupied without any of its content.

SwiftUI

SwiftUI recording is experimental and off by default. With the flag off, a SwiftUI screen is recorded as a single placeholder, which makes replays of a SwiftUI application close to useless. Turn it on to record the view tree:

SessionReplay.enable(
    with: SessionReplay.Configuration(
        replaySampleRate: 20,
        featureFlags: [.swiftui: true]
    )
)

To mask part of a SwiftUI hierarchy, wrap it in SessionReplayPrivacyView, which needs iOS 16 or later:

import SwiftUI
import AtatusSessionReplay

struct ProfileView: View {
    let user: User

    var body: some View {
        VStack(spacing: 8) {
            Text("User Profile")

            SessionReplayPrivacyView(
                textAndInputPrivacy: .maskAll,
                imagePrivacy: .maskAll
            ) {
                HStack {
                    AsyncImage(url: user.imageURL)
                        .frame(width: 50, height: 50)
                    Text(user.name)
                }
            }
        }
    }
}

There is no view modifier equivalent, so the wrapper is the only way to scope privacy in SwiftUI. It is inert when Session Replay is not enabled, so it is safe to leave in place.

Web views and system screens

A WKWebView is recorded as a reserved area that the web content fills in from the page side. Install the browser agent in the page and enable WebView tracking natively:

import AtatusWebViewTracking

WebViewTracking.enable(webView: webView, hosts: ["example.com"])

Without an instrumented page, the web view appears as an empty area in the replay. See WebView Tracking.

Some screens are never recorded because they belong to the system rather than your application. A Safari view controller appears as a placeholder labelled Safari, and the share sheet as one labelled Activity. Alerts are recorded normally.

Offline behavior

Records are compressed and written to disk, then uploaded when the network is reachable and the device is not low on battery or in Low Power Mode. Replay data is held for up to five hours, which is shorter than the retention for other events, so a device offline for longer than that loses the oldest part of the recording. Everything else uploads when connectivity returns.

Objective-C

Session Replay is available to Objective-C with AT-prefixed types:

@import AtatusSessionReplay;

ATSessionReplayConfiguration *configuration =
    [[ATSessionReplayConfiguration alloc] initWithReplaySampleRate:20
                                          textAndInputPrivacyLevel:ATTextAndInputPrivacyLevelMaskAll
                                                 imagePrivacyLevel:ATImagePrivacyLevelMaskAll
                                                 touchPrivacyLevel:ATTouchPrivacyLevelHide];
[ATSessionReplay enableWith:configuration];

myLabel.atSessionReplayPrivacyOverrides.textAndInputPrivacy =
    ATTextAndInputPrivacyLevelOverrideMaskAll;
cardFormView.atSessionReplayPrivacyOverrides.hide = @YES;

startRecordingImmediately and customEndpoint are properties rather than initializer parameters in Objective-C, and SessionReplayPrivacyView has no Objective-C equivalent because it is SwiftUI only.

Next steps

• Review what RUM collects in Configuration Options.
• Link web content to the native session with WebView Tracking.
• Jump from an error to its replay with Error Tracking.