Enable Session Replay on crashes

Only for iOS apps

This page describes how to enable and customize Session Replay (SR) 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 user actions immediately preceding a detected crash.


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
  • Only for Dynatrace Managed Secondary disk configured to store user session data

Known limitations and issues

Technical limitations

  • Swift 5+ is supported.
  • iOS 9+ is supported.
  • SwiftUI is not supported.
  • Session Replay for iOS is not available for Cordova, React Native, tvOS, and iPadOS.
  • 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 more information.

Enable SR on crashes for iOS apps

Follow the steps below to enable Session Replay on crashes for your iOS applications.

Step 1. Follow the instrumentation wizard

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

  1. In the Dynatrace menu, go to Mobile.
  2. Select the application you want to configure.
  3. Select Browse () > Edit.
  4. From the mobile app settings, go to Instrumentation wizard.
  5. Select iOS. Follow the steps described in the instrumentation wizard.

Step 3. Enable SR for mobile

  1. From the mobile app settings, go to General.
  2. Turn on Enable Session Replay.

Step 3. Enable SR on crashes

  1. From your mobile app settings, go to Instrumentation settings.
  2. Turn on Include Session Replay on crashes.

Analyze crashes

After you enable Session Replay on crashes, you can start analyzing any crashes that occur in your app. You can either do this from your mobile application overview page or by accessing the User sessions page.

  1. In the Dynatrace menu, go to Mobile.
  2. Select your mobile app to access its overview page.
  3. In the infographic, select the Crashes tile.
    Under the tile, you should see the graph that shows the total number of crashes by version during the selected timeframe.
  4. Select Analyze crashes. The Crash analysis page opens.
    On this page, all crashes caused by the same exception are organized into a Crash group.
  5. In the Crash groups list, select a crash group you're interested in.
  6. On the crash group details page, use the Next/previous crash occurrence arrows to browse through all the crash occurrences. Choose the crash occurrence you're interested in, and go to the Session information tab to replay what happened on the user's screen immediately before your application crashed.

The last event of the session is the crash, which is represented by a red dot in the timeline. Use the Session Replay controls to analyze the crash in detail.

Mobile user session with Session Replay

Mask sensitive data

Session Replay for mobile comes with three predefined masking levels:

  • Safest—all the editable texts fields, images, labels, web views, and switches are masked.
  • Safe—all the editable texts fields are masked.
  • Custom—by default, masks the same elements as Safest, but you can decide exactly which app components or views should be masked.

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.

  1. Import the DynatraceSessionReplay framework to the class.

    import DynatraceSessionReplay
  2. Set the required masking level.

    let maskingConfiguration = MaskingConfiguration(maskingLevelType: .safe) // .safest or .custom

Configure custom masking

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

Enable or disable masking rules

You can enable or disable rules globally or for the selected components, such as texts 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 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"])

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 Logging for iOS for more information.

Capture custom events

Session Replay records only certain events. However, you can track an event that is not supported by default.

AgentManager.trackCustomEvent(name: my_name, withView: my_view, takeScreenshot: true)
  • name is the custom event name shown in the timeline during the user session replay.
  • withView is an optional value referring to the UIView from which OneAgent takes the image. By default, OneAgent takes the application window.
  • takeScreenshot is 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.

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


Ensure that your system meets the Session Replay requirements.

User sessions are not recorded at all

  • If you're using the Simulator in Xcode to test Session Replay, go to Edit Scheme… > Run | Debug, and clear the Debug executable checkbox for your Xcode scheme.

  • Verify that you completed the steps described in the iOS instrumentation wizard:

    • You added Session Replay as a dependency to your Podfile.
    • You included all mandatory application identification keys to the Info.plist file.
    • You enabled the user opt-in mode and added a privacy notice.
  • Ensure that you can import the Dynatrace libraries:

    import Dynatrace
    import DynatraceSessionReplay
  • In the running application console logs, find the following:

    • Line stating the OneAgent version, for example, Dynatrace OneAgent (iOS) 8.207.1.XXXX
    • Line on the Session Replay version, for example, Dynatrace Mobile Session Replay Agent (iOS) 1.207

User sessions are recorded, but Session Replay is not available

  • Verify that Session Replay is enabled. From the mobile app settings, go to General to check that.
  • Verify that Session Replay on crashes and user opt-in mode are enabled. From the mobile app settings, go to Instrumentation settings to check that.
  • In the running application console logs, check for the following:
    • Line confirming that Session Replay is enabled:

      FINEST  Communications [DTXReplayAgentChannel.m:146-771-1] posted MRA notification: DTXServerConfigurationChangedNotification, userInfo:{
      replayConfig =             {      // Session Replay config
         capture = 1;                  // 1 means Session Replay is enabled; 0 means Session Replay is disabled
    • Line on a new session, for example, [DYNATRACE]: ℹ️ Info -> New sessionId:0003, visitorId:123456789101112, visitStore:1 and serverId:4 from DT agent <NSThread: 0x6000013fe800>{number = 1, name = main}

Frequently asked questions