Configure Session Replay on crashes for iOS
This page describes how to enable and customize Session Replay on crashes for your iOS apps.
Ensure that your system meets the following requirements:
Dynatrace version 1.208+
OneAgent version 1.207+
Real User Monitoring enabled for your application
Active Dynatrace Digital Experience Monitoring license
The web UI URL has a trusted certificate
Starting with OneAgent for iOS version 8.281, Dynatrace stopped supporting iOS 11 and Xcode 14. We only support iOS 12+ and Xcode 15+.
Also, be aware that Apple app submission guidelines will restrict support to applications built with a minimum of Xcode 15 and iOS 17 SDK starting April 2024.
Session Replay on crashes is not available for tvOS and iPadOS.
Session Replay is not available for Cordova, React Native, Flutter, or Xamarin.
For a hybrid app, Session Replay on crashes is supported only for the native part of the app. Session Replay is not supported for the browser part of a hybrid app.
We recommend that you not use other crash reporting tools together with Dynatrace Session Replay.
- Session Replay can capture only certain events. However, if you need to track a specific view or event that is not supported by default, you can capture a custom event.
- You can play back the user sessions recorded with Session Replay only in certain browsers.
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.
- Go to Mobile.
Select the mobile application that you want to configure.
- Select More (…) > Edit in the upper-right corner of the tile with your application name.
- From the application settings, select General > Enablement and cost control.
- Turn on Enable Session Replay on crashes.
- From the application settings, select General > Data privacy.
- Turn on Enable user opt-in mode.
- From the application settings, select Instrumentation wizard, and then select Android or iOS.
Follow the steps 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
Complete all the steps of the Enable Session Replay instruction above.
DTXSwiftUIEnableSessionReplayInstrumentationconfiguration key to
truein your project's
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:
Lists inside extensions
Lists with static content
- Lists where the feeding object does not conform to the
Mask sensitive data
Data masking levels
Session Replay on crashes comes with three predefined masking levels:
- Safest—all the editable text fields, images, labels, web views, and switches are masked.
- Safe—all the editable text fields are masked.
- Custom—by default, masks the same elements as Safest, but you can decide which application components or views should be masked. See Configure custom masking for details.
To see what data Session Replay masks and what parts of the screen are captured, use the Session Replay screenshot debugger.
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.
DynatraceSessionReplayframework to the class.
Set the required masking level and apply the masking configuration.
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.
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
You can enable or disable masking of the selected views based on their
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.
With OneAgent for iOS version 8.239, we deprecated the following methods for capturing custom events:
Use the following new methods for capturing custom events:
OneAgent for iOS version 8.239+
Capture a custom event with a screenshot of the specific view.
Specific screen region
OneAgent for iOS version 8.239+
Capture a custom event with a screenshot of the specific screen region.
OneAgent for iOS version 8.239+
Capture a custom event with a screenshot of the full screen.
You can use this method instead of the deprecated
OneAgent for iOS version 8.237 and earlier
nameis the custom event name shown in the timeline during the user session replay.
withViewis an optional value referring to the UIView from which OneAgent takes the image. By default, OneAgent takes the application window.
takeScreenshotis an optional boolean value used to define if a custom event has a screenshot or not.
Alternatively, you can take a screenshot of the view. In this case, a custom event named "Custom Screenshot" is shown in the timeline during the user session replay.
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.
OneAgent for iOS version 8.239+
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.
After you enable 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.
To enable the Session Replay screenshot debugger
In Xcode, select Edit Scheme from the Scheme menu to change your application scheme.
From your application scheme settings, select the Run action, and then switch to the Arguments tab.
Under Environment Variables, add one or both of the following keys:
DTXDebugMasking. This key shows screenshots taken by Session Replay, including masked content and UI controls. For each captured screenshot, you see a brief flash.
DTXDebugFrameHighlight. This key highlights the captured part of the screen with a red frame so that you can know exactly what part of the screen is captured.
Frequently asked questions
1.0 DEM unit per user session captured with Session Replay.
We've set hard limits of 300 KB per session and 10 MB for all sessions. Anything exceeding these limits gets trimmed down to the limits as mentioned above.
When recording a user session, Dynatrace may consume up to 10 MB of the user's mobile device storage. However, Dynatrace won't send a session that's more than 300 KB.
No. Session volume depends on a variety of factors, including the application size, session duration, and users' interactivity with the application.
No. To record sessions, Session Replay on crashes takes screenshots of the mobile app screen and its parts.
The data is sent one time. This is performed in several requests according to the data collected.
If you've changed the transmission mode to Wi-Fi, the images are sent only when the users of your app are connected to Wi-Fi.
Currently, there is no time limit for storing images; only the 10 MB hard limit mentioned above is applied. However, in emergency stop situations, everything is deleted.
The impact is very low, and overhead is mainly seen during runtime. In general, it's related to the complexity of the application, for instance, to how many views are displayed at a time.
It is difficult to answer this question precisely as the final size of the Session Replay framework depends on several factors.
Multiple architectures are included in a fat-framework binary:
ARM slices are used by physical iOS devices, while
x86-64 parts are used by Simulator and removed from your app during the build and archive process. Moreover, when users download your app from App Store, they receive only the architecture that their device requires.
We also have bitcode, which is an unoptimized intermediate code representation. It is included for ARM architectures but does not affect the final size of your application. Apple uses bitcode for potential recompilation and re-optimization of your app binary after you've submitted your mobile application to App Store.
Due to all these factors, the best way to estimate the Session Replay framework size is to compile your app without this framework and generate an IPA file; then do the same but with the framework included and compare the sizes of these two IPA files. The difference is the Session Replay framework size.
For our test application, the Session Replay framework size is around 500 kB compressed.
Data is sent only when the user reopens the app. However, if the user does not open the app within 10 minutes, the data is deleted.