Configure Session Replay on crashes for iOS

This page describes how to enable and customize Session Replay on crashes for your iOS apps.

Session Replay on crashes gives you additional context for crash analysis in the form of video-like screen recordings that replay the user actions immediately preceding a detected crash.

Prerequisites

Ensure that your system meets the following requirements:

Known limitations

See Technical restrictions for Session Replay for web applications for more information.

Enable Session Replay

If you haven't done so already, complete all steps described in the instrumentation wizard.

Enable Session Replay for SwiftUI apps

OneAgent for iOS version 8.249+

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

To enable 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 on crashes 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.

Configure custom masking

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

Enable or disable masking rules

You can enable or disable 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

[conf addWithRule:MaskingRuleMaskAllImages error:nil];      // Adds one rule
[conf removeWithRule:MaskingRuleMaskAllSwitches error:nil]; // Removes one rule
[conf addAllRulesAndReturnError:nil];                       // Adds all rules
[conf removeAllRulesAndReturnError:nil];                    // Removes all rules

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

Mask views using accessibilityIdentifier

You can enable or disable 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"])

[conf addMaskedViewWithViewIds:@[@"masked_view_id"] error:nil];
[conf removeMaskedViewWithViewIds:@[@"masked_view_id"] error:nil];
[conf addNonMaskedViewWithViewIds:@[@"nonMasked_view_id"] error:nil];
[conf removeNonMaskedViewWithViewIds:@[@"nonMasked_view_id"] error:nil];

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.

Enable Session Replay logs

You can enable Session Replay logs the same way as for OneAgent. See OneAgent for iOS 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)
}

try? AgentManager.trackCustomEvent(name: "my_event_name", view: nil)

Specific view

OneAgent for iOS version 8.239+

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

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

[AgentManager trackCustomEventWithName:@"my_view_name" view:myView error:&error];

Specific screen region

OneAgent for iOS version 8.239+

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

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

[AgentManager trackCustomEventWithName:@"my_view_name" frame:myView.frame error:&error];

Full screen

OneAgent for iOS version 8.239+

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

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

[AgentManager trackCustomEventWithName:@"my_view_name" view:nil error:nil];

AgentManager.trackCustomEvent(name: my_name, withView: my_view, takeScreenshot: true)

[AgentManager trackCustomEventWithName: my_name withView: my_view takeScreenshot:YES];

AgentManager.takeScreenshot()

[AgentManager takeScreenshot];

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

[AgentManager setTransmissionMode: TransmissionModeWifi]; // TransmissionModeData by default

Screenshot debugger

To enable the Session Replay screenshot debugger

Troubleshooting

Frequently asked questions