Session Replay for Mobile RUM

Session Replay allows you to monitor user activity within mobile applications by recording interactions such as clicks, scrolls, and navigation. It captures these interactions as dynamic, video-like journeys, along with detailed session metadata. This provides teams with clear insight into the user experience, especially when issues arise. You can watch the session replay to:

  • Optimize the user experience.

  • Debug the errors for application crashes.

  • Diagnose the reasons for application slowness.

Points to Consider

In the Beta stage, each account can record up to 20,000 Session Replays per month. After the Beta ends, contact your Account Manager to buy the full feature.

Storage is set to 8 days by default, and it cannot be extended during the Beta stage. After the Beta ends, you can purchase the extended storage SKU to add more storage.

Prerequisites

Ensure that the following conditions are met to use Session Replay:

  • Controller >= 25.7

  • EUM Server >= 25.7

  • iOS Agent >= 25.9

  • Android Agent >= 25.9

Log in to the administration console and add the following property to use Session Replay:

  1. Go to Account Settings.

  2. Click Add Property and add session.replay.enabled. Set the value of this property to true.

Configure the iOS Agent to Report Session Replay

  1. To report Session Replay for your mobile application, you must configure the iOS Agent as follows:
    Objective C
    #import <ADEumInstrumentation/ADEumInstrumentation.h>
#import "AppDelegate.h"
  
    // ...
    -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey:<#EUM_APP_KEY#>];
        //The default SaaS EUM Server and Screenshot Service are in the Americas,
        // so you can omit the following settings if you are in the Americas.
        config.collectorURL = @"https://<your_region>-col.eum-appdynamics.com";
        config.screenshotURL = @"https://<your_region>-image.eum-appdynamics.com";
        config.sessionReplayURL = @"http(s)://<domain-name>:7001";
        [ADEumInstrumentation initWithConfiguration: config];
        // other tasks
        return YES;
     }
    Swift
    #import <ADEumInstrumentation/ADEumInstrumentation.h>
#import "AppDelegate.h"
  
    // ...
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let config = ADEumAgentConfiguration(appKey: <#EUM_APP_KEY#>)
        config.collectorURL = "https://<your_region>.eum-appdynamics.com"
        config.screenshotURL = "https://<your_region>-image.eum-appdynamics.com"
        config.sessionReplayURL = "http(s)://<domain-name>:7001"
        ADEumInstrumentation.initWith(config)
        // other tasks
        return true
    }
// ...
  2. To report Session Replay for your mobile application, you must configure the iOS Agent as follows:
    Objective C
    #import <ADEumInstrumentation/ADEumInstrumentation.h>
#import "AppDelegate.h"
  
    // ...
    -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        ADEumAgentConfiguration *config = [[ADEumAgentConfiguration alloc] initWithAppKey:<#EUM_APP_KEY#>];
        //The default SaaS EUM Server and Screenshot Service are in the Americas,
        // so you can omit the following settings if you are in the Americas.
        config.collectorURL = @"https://<your_region>-col.eum-appdynamics.com";
        config.screenshotURL = @"https://<your_region>-image.eum-appdynamics.com";
        config.sessionReplayURL = @"http(s)://<domain-name>:7001";
        [ADEumInstrumentation initWithConfiguration: config];
        // other tasks
        return YES;
     }
    Swift
    #import <ADEumInstrumentation/ADEumInstrumentation.h>
#import "AppDelegate.h"
  
    // ...
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let config = ADEumAgentConfiguration(appKey: <#EUM_APP_KEY#>)
        config.collectorURL = "https://<your_region>.eum-appdynamics.com"
        config.screenshotURL = "https://<your_region>-image.eum-appdynamics.com"
        config.sessionReplayURL = "http(s)://<domain-name>:7001"
        ADEumInstrumentation.initWith(config)
        // other tasks
        return true
    }
// ...
To protect user privacy during session recordings, configure Session Replay to mask sensitive data by enabling options that obscure all text and input fields by default. For more information, see Handle Sensitive Data.

Configure the Android Agent to Report Session Replay

To report Session Replay for your mobile application, you must configure the Android Agent as follows:
  1. Initialise the agent by the following methods:

    • .withSessionReplayEnabled(true)

    • .withBlobServiceURL(configHelper.getSessionReplayUrl())

    • (Optional) Default configuration: RenderingMode.NATIVE_MODE.withSessionReplayRenderingMode(RenderingMode.WIREFRAME_MODE)

    import com.appdynamics.eumagent.runtime.Instrumentation;
...
@Override public void onCreate(Bundle savedInstanceState) {
  Instrumentation.start(AgentConfiguration.builder()
    .withAppKey("<EUM_APP_KEY>")
    .withContext(getApplicationContext())
    // The default SaaS EUM Server and Screenshot Service are in the Americas,
    // so you can omit the following settings if you are in the Americas.
    .withSessionReplayEnabled(true)
    .withBlobServiceURL(configHelper.getSessionReplayUrl()) 
    .build());
  ...
}
  2. In your app module-level build.gradle file, add session replay SDK. 
    
...
...
repositories {
        maven {
            url = "https://sdk.smartlook.com/android/release"
        }
    }
...
...
dependencies {
        implementation 'com.cisco.android:sr-instrumentation-session-recording-core:1.0.12' 
}
To protect user privacy during session recordings, configure Session Replay to mask sensitive data by enabling options that obscure all text and input fields by default. For more information, see Handle Sensitive DataHandle Sensitive Data.

Enable Session Replay

An administrator can only enable Session Replay. To enable Session Replay for the selected mobile application, perform the following options:
  1. Log in to the Controller UI.
  2. Open the mobile application in which you are interested.
  3. On the left navigation menu, select Configuration.
  4. Click Mobile App Group Configuration.
  5. Under the Session Replay tab, select Enable Session Replay.
    Note: Xcode's Main Thread Checker

    When starting an iOS app in the debug mode, it may stop for few seconds. After enabling the session replay, it will start and display a warning. This issue is caused by Xcode's Main Thread Checker diagnostics.

    Main Thread Checker: UI API called on a background thread: -[UIView drawViewHierarchyInRect:afterScreenUpdates:]

    The warning is harmless, and is caused by iOS Agent's capturing screen on the background. The alternative (capturing the screenshot on the main thread) may cause glitches of the app UI – so implementing it this way and having this warning is a necessary trade-off to enable seamless recording functionality.

    This warning also might be accompanied by a short freeze of the app during debugging. This freeze does not happen in production builds, and is caused by the Main Thread Checker Xcode diagnostic option.

    This option can be switched off in the respective run scheme diagnostic options, see "Detect Improper UI Updates on Background Threads" section of the "Diagnosing Memory, Thread, and Crash Issues Early."

View Session Replay

The Session Replay combines multiple recordings with user interactions. Perform the following steps to view the Session Replay:
  1. Go to User Experience > Mobile Apps . A play icon is displayed in Session Replay if the recording is available. Expand the Session Replay tab.
  2. Select the application for which you have enabled the Session Replay.
  3. Select Sessions.
    A play icon is displayed in Session Replay if the recording is available.
  4. Expand the Session Replay tab.
Session Replay highlights active segments of the sessions. A blank screen appears if there are no recordings or user activity.
You can perform the following actions while viewing the session replay:

  • Adjust the playback speed.

  • Switch between Video and Wireframe modes. In Wireframe mode, the session replay displays only the UI layout and masks the text.