Configure Session Replay for iOS

• Latest Dynatrace
• How-to guide
• 8-min read
• Published May 21, 2026
• Preview

Preview

This page describes how to activate and customize Session Replay for your iOS apps.

Use Session Replay

Session Replay on iOS allows you to capture your customers' interactions with your mobile app and replay each tap, swipe, and screen rotation in a movie-like experience.

Use Session Replay on crashes

You can also use it to get more context for crash analysis in the form of video-like screen recordings that replay the user actions preceding a detected crash.

Prerequisites

Make sure that your system meets the following requirements:

Known limitations and issues

Session Replay is a video-like reconstruction of the user interactions with mobile applications that use captured events and data. Because of this approach, replayed sessions can differ from the actual user experience.

Activate Session Replay on iOS and adjust number of recorded sessions

If you haven't done so already, complete all steps described in the initial setup for iOS frontends.

Activate Session Replay for SwiftUI apps

OneAgent for iOS version 8.249+

If you've already instrumented your SwiftUI app, you can additionally activate Session Replay for such a mobile app.

To activate Session Replay for your instrumented SwiftUI app

Supported SwiftUI containers

We support Session Replay for the following SwiftUI containers:

Known limitations for SwiftUI apps

Dynatrace doesn't instrument the following SwiftUI containers:

Mask sensitive data

Data masking levels

Session Replay comes with three predefined masking levels:

Change masking level

By default, OneAgent applies the Safest masking level. To change it to the Safe or Custom level, use the API to configure OneAgent. If you've opted for the Custom level, see Configure custom masking for details on how to set which application components or views should be masked.

Example 1: Change masking level to Safe

Use the following code to set the masking level to Safe.

let maskingConfiguration = MaskingConfiguration(maskingLevelType: .safe)
try? AgentManager.setMaskingConfiguration(maskingConfiguration)

Configure custom masking

If you set the data masking level to Custom, you can use additional API methods to decide which application components or views should be masked. You can:

Activate or deactivate masking rules

You can activate or deactivate rules globally or for the selected components, such as text fields, images, labels, web views, and switches.

try? maskingConfiguration.add(rule: .maskAllImages) // Adds one rule
try? maskingConfiguration.remove(rule: .maskAllSwitches) // Removes one rule
try? maskingConfiguration.addAllRules() // Adds all rules
try? maskingConfiguration.removeAllRules() // Removes all rules

If you remove all masking rules, Session Replay won't mask anything. If you activate all masking rules, it's equivalent to the Safest masking level.

Mask views using accessibilityIdentifier

You can activate or deactivate masking of the selected views based on their accessibilityIdentifier.

try? maskingConfiguration.addMaskedView(viewIds: ["masked_view_id"])
try? maskingConfiguration.removeMaskedView(viewIds: ["masked_view_id"])
try? maskingConfiguration.addNonMaskedView(viewIds: ["nonMasked_view_id"])
try? maskingConfiguration.removeNonMaskedView(viewIds: ["nonMasked_view_id"])

Mask views using a masking tag

You can also mask a view by adding the data-dtrum-mask masking tag to the view's accessibilityIdentifier. A view with this masking tag is always masked.

Activate Session Replay logs

You can activate Session Replay logs the same way as for OneAgent. See Debug logging for more information.

Capture custom events

Session Replay records only certain events. You can additionally capture custom events that are not supported by default. You can capture a custom event with an included screenshot of a specific view, specific screen region, or full screen.

All methods for capturing custom events can throw a TrackCustomEventError.notInMainThread error if you try to capture a custom event from a thread that is not the main thread. We suggest that you include a do-catch clause until everything works properly; then you can replace the clause with a simpler version that, even in case of an error, just doesn't capture the custom event.

do {
try AgentManager.trackCustomEvent(name: "my_event_name", view: nil)
} catch {
print(error)
}

Specific view

Capture a custom event with a screenshot of the specific view.

try? AgentManager.trackCustomEvent(name: "my_view_name", view: myView)

Specific screen region

Capture a custom event with a screenshot of the specific screen region.

try? AgentManager.trackCustomEvent(name: "my_view_name", frame: anyFrame)

Full screen

Capture a custom event with a screenshot of the full screen.

try? AgentManager.trackCustomEvent(name: "my_view_name")

Change transmission mode to Wi-Fi for images

By default, all data—information on captured events and images—is sent over any connection. However, you can opt to transfer images only when the users are connected to Wi-Fi to save their mobile data.

AgentManager.setTransmissionMode(.wifi) // .data by default

Use the screenshot debugger

The Session Replay screenshot debugger allows you to see when the screenshots are taken, which parts of the screen are captured, and what data—text fields, images, labels, web views, and toggles—is masked.

You can use the Session Replay screenshot debugger when running your mobile app in the simulator, so you don't have to wait until the session is closed and uploaded to Dynatrace.

Screenshot debugger

After you activate the Session Replay screenshot debugger, you can see the corresponding keys in your project. Note that these keys are not sent to the app code for release or archive compilations, so they are never included in the production code. These keys are used only for debug runs.

Screenshot debugger

To activate the Session Replay screenshot debugger:

Troubleshooting