Mobile Session Replay

Why spend hours trying to reproduce elusive mobile app bugs when you can see exactly what your users experienced? Mobile Session Replay eliminates the guesswork in troubleshooting by providing a video replay of what the end user saw on their phone or tablet, synchronized with all the telemetry data from that session. This means you can quickly assess the real impact of errors on your users, identify performance bottlenecks and UX friction points, and resolve issues faster without relying on bug reports or local reproduction.

Requirements and compatibility

Before setting up Mobile Session Replay, ensure your app meets these requirements.

Technical prerequisites

To use Mobile Session Replay, you need:

• A New Relic account with mobile monitoring enabled
• An active mobile application configured in New Relic
• Network connectivity from your mobile app to New Relic's data ingestion endpoints

Performance considerations

Before enabling Mobile Session Replay, consider the following impact on your app and users:

• App performance: Session Replay captures and transmits viewport data, which may impact app performance on older devices
• Data consumption: Replay data transmission will consume user data, especially when images are captured
• Storage requirements: Captured data requires adequate storage capacity on user devices between transmission cycles
• Network optimization: All data is compressed client-side before transmission to minimize network usage
• Sampling strategy: Consider your sampling rates carefully to balance data collection needs with performance impact

Supported UI frameworks

Session Replay is currently supported for select UI frameworks for iOS, Android, and React Native apps. We are actively working on supporting more UI and hybrid frameworks.

Currently supported:

• iOS UIKit
• iOS SwiftUI
• Android XML layouts
• Android Jetpack Compose
• React Native Views

Planned support:

• WebViews
• Flutter
• Cordova
• Capacitor
• MAUI

Minimum agent versions

Below are the first agent versions that supported basic Session Replay capture:

• iOS agent v7.5.10 released Sept 15, 2024
• Android agent v7.6.8 released July 29, 2024
• React Native agent v1.5.10 released Sept 15, 2024

How mobile session replay works

Understanding how Mobile Session Replay works helps you make informed decisions about privacy settings and troubleshooting.

When a user launches your app, the Mobile agent makes a call to New Relic servers to check whether Session Replay is enabled, and if so, what the sampling rates and privacy settings are. The agent resolves the sampling decision and starts capturing replay data.

Unlike Browser Session Replay, mobile apps don't have a DOM that can be captured and recreated. Instead, the Mobile agent monitors the view lifecycle and transforms the viewport into HTML. Your masking settings are applied to the HTML reproduction of the viewport which is then serialized to JSON and stored client-side until data transmission is triggered every 1 minute, when the payload is gzipped and sent to New Relic.

If the application crashes or hangs unexpectedly, the data that was collected between the last successful transmission cycle and the unexpected app exit is stored client-side until the next app launch, when the Mobile agent will attempt to restore and upload the orphaned data. Due to how iOS and Android handle unexpected exits, we can't always recover all data after unexpected app exits.

When a replay is viewed in the New Relic UI, the JSON is fetched from NRDB and deserialized back to a stream of HTML updates which constitutes the "video" being played back in your web browser.

Due to the transformation from native platform view frameworks into HTML, Mobile Session Replays are generally accurate but not pixel perfect. We will continually be working to improve the accuracy of replays.

Set up mobile session replay

Enabling Session Replay, sampling rates, and most privacy settings are managed server-side on the Application Settings page in New Relic so updates are not dependent on the deployment and adoption of a new app version. Only some types of masking overrides need to be managed in your code.

Privacy and masking

Choose the masking strategy that best fits your privacy requirements.

Masking strategies

Mobile Session Replay offers two masking strategies to balance privacy protection with replay utility. Your choice determines how sensitive data is handled in session recordings.

Default masking strategy

The default masking strategy provides maximum privacy protection by masking all text and images without exception. Choose this strategy when:

• Your app handles highly sensitive data (healthcare, financial services, etc.)
• Regulatory compliance requires strict data protection
• You want zero risk of capturing private information

What gets masked:

• All text is replaced with asterisks (e.g., "hello" becomes "*")
• All images are replaced with placeholder blocks of the same dimensions
• User taps and swipes are still captured (unless you hide them)

This ensures that even if you accidentally add unmasking code, the default strategy will always mask everything.

Important limitations with default masking strategy:

• Masking modes are not configurable
• Inline masking overrides (like nr-unmask tags) are ignored
• Server-side masking rules have no effect

Custom masking strategy

The custom masking strategy gives you fine-grained control over what gets masked and what remains visible. Use this strategy when:

• Your app has a mix of public and sensitive content
• You need to see specific UI elements to diagnose issues effectively
• You want to selectively unmask non-sensitive areas

A custom strategy consists of:

1. Masking modes: Baseline rules for different content types (text, images, interactions)
2. Override rules: Exceptions to mask or unmask specific components

To switch to custom masking:

In the New Relic web interface:

1. Go to Mobile > [your entity] > Settings > Application > Session Replay
2. In the Masking strategy section, select Custom
3. Configure your masking modes (see next section)
4. Optionally, add override rules for specific components

Masking modes

When using the custom masking strategy, masking modes establish the baseline privacy behavior for your session replays. These modes apply globally across your app unless overridden by specific rules for individual components.

To configure masking modes:

In the New Relic web interface:

1. Go to Mobile > [your entity] > Settings > Application > Session Replay
2. Ensure Custom masking strategy is selected
3. In the Masking modes section, toggle each mode on or off based on your needs
4. Changes take effect immediately for all new session recordings

The four masking modes control different types of content:

Mask user input text

Controls whether text entered by users into input fields is visible in replays.

When enabled (recommended):

• All characters typed by users are replaced with asterisks
• Example: User types "john.doe@email.com" → appears as "***" in replay
• Protects usernames, email addresses, search queries, form data, and other user-entered content

When disabled:

• User-entered text appears exactly as typed in the replay
• Use only when input fields contain non-sensitive information
• Helpful for debugging form validation issues or search functionality

Default setting: Enabled in the custom masking strategy.

When you might disable this mode:

• Public search bars where queries aren't personally identifiable
• Non-sensitive filters or category selections
• Debugging autocomplete or input validation issues

Mask application text

Controls whether text displayed by your application (labels, buttons, headers, content) is visible in replays.

When enabled:

• All static and dynamic text rendered by your app is replaced with asterisks
• Example: "First Name:" label becomes "***" in replay
• Protects any text that might contain or reveal sensitive information

When disabled:

• All application text appears exactly as users see it
• Labels, buttons, headings, and content are fully readable
• Makes replays much easier to understand and navigate
• Essential for identifying which screens or features users interacted with

Default setting: Enabled in the custom masking strategy.

Recommendation for most apps: Disable this mode unless displaying highly sensitive information. Visible UI text is crucial for:

• Understanding user navigation paths
• Identifying which buttons or features users clicked
• Seeing error messages that appeared
• Diagnosing layout or localization issues
• Correlating replays with specific app features

Keep this mode enabled when:

• Healthcare apps displaying patient information
• Financial apps showing account details or transactions
• Apps with user-generated content that might be sensitive
• Compliance requirements mandate masking all displayed text

Mask images

Controls whether images in your application are captured and displayed in replays.

When enabled (recommended):

• All images are replaced with placeholder blocks of the same size
• Placeholders preserve layout structure so you can see image positions
• No image data is transmitted to New Relic
• Protects user-uploaded photos, profile pictures, and potentially sensitive imagery

When disabled:

• Images are captured, compressed, base64 encoded, and included in the replay payload
• Images appear in replays, though at lower quality than users saw
• Significantly increases data transmission and storage costs
• Helps diagnose issues with image loading, rendering, or layout

Default setting: Enabled in the custom masking strategy.

When you might disable this mode:

• Diagnosing image loading failures or rendering issues
• Investigating layout problems related to image dimensions
• Understanding user interactions with image galleries or media content
• Your app only displays public, non-sensitive images (icons, logos, illustrations)

Keep this mode enabled when:

• User profile pictures or uploaded photos
• Documents or screenshots captured within the app
• Medical imaging or healthcare-related imagery
• Any user-generated visual content

Hide user taps and swipes

Controls whether user touch interactions are visualized in replays.

When disabled (recommended):

• User taps appear as gray circles on the replay
• Swipe gestures appear as red lines showing the motion path
• Essential for understanding which UI elements users interacted with
• Helps identify usability issues, missed taps, or confusing interactions

When enabled:

• No tap or swipe visualizations appear in the replay
• Users appear to navigate through your app without any visible interaction
• Use when touch patterns could reveal sensitive information

Default setting: Disabled in the custom masking strategy (taps and swipes are visible).

When you might hide interactions: Masking text is generally sufficient, but hiding taps/swipes may be necessary when:

• Your app has an integrated PIN pad or numeric keypad where tap patterns reveal security codes
• Swipe patterns are used for authentication (pattern locks, gesture passwords)
• Touch interactions on specific screens could infer sensitive choices (medical symptom selection, financial decisions)

Recommendation for most apps: Keep interactions visible to:

• See exactly where users tapped, including missed or unresponsive areas
• Understand navigation patterns and user flow through your app
• Identify usability problems with small touch targets or unclear buttons
• Diagnose gesture-based features (swipe to delete, pull to refresh, etc.)

Advanced masking configuration

Use masking overrides when you want specific parts of your application to have different masking settings than your specified masking modes. For example, if the majority of your application doesn't have sensitive data, you can set your modes to unmask and specify overrides to only mask the parts of your application that contain sensitive data.

Masking override methods

We offer three ways to create masking override rules:

Inline attributes

Inline masking overrides are applied in your code by tagging the component you want masked or unmasked. You'll need to deploy a new version of your app and have users adopt it for updates to apply, so they are best used when you want the oversight of your change control process to manage masking changes.

// Mask a composable
Text(
    text = "Sensitive information",
    modifier = Modifier.nrMask()
)

// Unmask a composable
Text(
    text = "Public information",
    modifier = Modifier.nrUnmask()
)

<EditText
    android:id="@+id/editTextEmail"
    android:layout_width="390dp"
    android:inputType="text"
    android:tag="nr-mask"
    android:importantForAutofill="no" />

<EditText
    android:id="@+id/editTextEmail"
    android:layout_width="390dp"
    android:inputType="text"
    android:tag="nr-unmask"
    android:importantForAutofill="no" />

<View>
  <NewRelic.Mask>
    <Text>Sensitive information</Text>
  </NewRelic.Mask>
</View>

<View>
  <NewRelic.Unmask>
    <Text>Non-sensitive information</Text>
  </NewRelic.Unmask>
</View>

Local API methods

Local API method masking overrides are also applied in your code within the New Relic agent configuration. They are useful when the targeted views already have unique identifiers and you want to manage them in a centralized list instead of tagging each view individually throughout your code.

// In your application initialization
NewRelic.addSessionReplayMaskViewTag("sensitive-data")
NewRelic.addSessionReplayUnmaskViewTag("public-data")

// In your composables
Text(
    text = "Sensitive information",
    modifier = Modifier.testTag("sensitive-data")
)

Text(
    text = "Public information",
    modifier = Modifier.testTag("public-data")
)

NewRelic.addSessionReplayMaskViewTag("login");
NewRelic.addSessionReplayUnmaskViewTag("editTextEmail");
NewRelic.addSessionReplayUnmaskViewClass("android.widget.Button");
NewRelic.addSessionReplayMaskViewClass("android.widget.TextView");
NewRelic.addSessionReplayMaskViewClass("com.yourpackagename.CustomView");

Server-side rules

Server-side masking rules allow you to retroactively patch masking mistakes in app versions that have already been released. They take immediate effect on all new session starts without requiring an app update.

Rules consist of three components:

• Type: Determines whether matching components should be masked or unmasked
• Identifier: Specifies how you want to target elements (e.g., by class, tag, etc.)
• Value: The value of the selected identifier the rule will apply to

For example, a rule to Mask class android.widget.EditText would mask all user-editable text fields in an Android app.

To create a new rule:

In the New Relic web interface:

1. Go to Mobile > [your entity] > Settings > Application > Session Replay.
2. Scroll to Override rules and click Add new override rule.
3. Select the rule type (Mask or Unmask).
4. Choose the identifier you want to use to target components.
5. Input the value of the identifier you want the rule to apply to.
6. Click Add rule.

The new rule is added to the Override Rules table and will be enforced on all new sessions.

To delete or edit a rule:

In the New Relic web interface:

1. Navigate to Mobile > [your entity] > Settings > Application > Session Replay.
2. Locate the rule you want to modify in the Override Rules table.
3. Click the ... menu, then select Delete or Edit.

Masking rule priority

When several masking rules apply to one view or element, the following priority order determines which rule is applied:

1. Strategy supersedes everything

   If your masking strategy is Default, modes and overrides are not enforced.

   Example: If you have added inline nr-unmask attribute overrides in your code but the Default masking strategy is selected in settings, everything will still be masked.

2. Overrides supersede modes

   Modes determine the standard behavior when an override isn't present, so if an override is present, it will always take precedence over the mode.

   Example: If Mask application text mode is enabled and you add an inline nr-unmask attribute override to a view in your code, that view will be unmasked but every other view will be masked.

3. Masking overrides supersede unmasking overrides

   If a single view has both masking and unmasking overrides, it will always be masked.

   Example: If a view has an inline nr-unmask attribute override and an nr-mask server-side rule, the view will be masked.

View and analyze session replays

Once you start collecting session replays, they can be used to improve your digital experiences by identifying common patterns and areas where users experience friction. They're also helpful for quickly diagnosing and resolving issues by reviewing the steps users took before encountering errors or unexpected behavior.

View replays on the Session Replay page

The Session Replay page provides a list of all replays that were collected over your selected time period. By default, we filter the list to replays that lasted at least 5 seconds. The table provides helpful data points like error counts, and the filters allow you to narrow the list to sessions that will help solve your problem.

For example, you can add a countryCode filter to see replays from a specific region to validate localization is working as expected, or a deviceModel filter to see replays from a specific model of phone that may have compatibility issues.

To access the Session replay page:

In the New Relic web interface:

1. Go to one.newrelic.com > All Capabilities > Mobile.
2. Select your mobile app.
3. In the left-hand menu, scroll down and click Session replay.
4. Click on a row to view the replay.

View replays with errors and performance issues

Currently, you can view replays from the main Session Replay page. Integration with the Crashes, Request errors, Handled exceptions, and ANRs experiences is coming later in the preview period.

Manage permissions and access

Mobile session replay has its own set of permissions so you can narrowly tailor who can view replays and update its settings. Users with any standard role can view replays, but only All product admins can modify Session Replay settings. Custom roles can be created for more control over user permissions.

Permission overview

User permissions are managed in the User Management UI which can be found in Administration > Access management > Roles.

In order to view or modify Session Replay settings on the Application Settings page, users need both Session Replay and the Application Settings permissions.