Skip to content

iOS Session Replay

Prerequisites

SDK 1.6.8 and later requires iOS 15 or later. When upgrading from an earlier version, see 1.6.8 upgrade requirements. * Ensure that you have set up and initialized TrueWatchSDKRUM configuration and enabled View monitoring collection. * iOS Session Replay version support: SDK.Version >= 1.6.0. * When upgrading from an earlier version to SDK 1.6.6 or later, the Session Replay product name changes to TrueWatchSessionReplay. See Migration Guide. * We recommend using the stable official release version shown by the badge at the top of this document. Pre-release versions such as alpha and beta are no longer recommended.

  • If you want to integrate advanced capabilities early, follow the latest features, or track unreleased changes, you can follow the iOS SDK repository and its changelog on GitHub: TrueWatchTech/datakit-ios

Configuration

Depending on your package manager, link the TrueWatchSessionReplay feature component in the TrueWatchSDK library to your project:

CocoaPods

pod 'TrueWatchSDK', 'last_version'
pod 'TrueWatchSDK/SessionReplay', 'last_version' # New

Swift Package Manager

dependencies: [
.package(url: "https://github.com/TrueWatchTech/datakit-ios.git",
from: "last_version")
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "TrueWatchSDK", package: "TrueWatchSDK"),
            .product(name: "TrueWatchSessionReplay", package: "TrueWatchSDK"), // New
        ]),
]

Carthage/Framework

Supported in SDK 1.6.2 and later

When using Carthage or manually integrating the Framework, in addition to the base SDK, add the TrueWatchSessionReplay Session Replay component to the Frameworks of the main project target.

TrueWatchSessionReplay is the Session Replay feature component. It depends on the base capabilities of TrueWatchSDK and cannot be used alone.

Objective-C Entry

The Objective-C import path depends on the integration method:

Integration Method Recommended Entry
CocoaPods #import <TrueWatchSDK/TrueWatchSessionReplay.h>
Swift Package Manager @import TrueWatchSessionReplay;
Carthage / Framework #import <TrueWatchSessionReplay/TrueWatchSessionReplay.h>
The following Objective-C examples use the Swift Package Manager syntax. For CocoaPods or Carthage / Framework integration, replace the entry line according to the table above.

Code Invocation

@import TrueWatchSessionReplay;
FTSessionReplayConfig *srConfig = [[FTSessionReplayConfig alloc]init];
   srConfig.touchPrivacy = FTTouchPrivacyLevelShow;
   srConfig.textAndInputPrivacy = FTTextAndInputPrivacyLevelMaskSensitiveInputs;
   srConfig.imagePrivacy = FTImagePrivacyLevelMaskNonBundledOnly;
   // To capture SwiftUI pages, enable this in SDK 1.6.5 and later
   srConfig.enableSwiftUI = YES;
   // To enable Session Replay heatmap correlation, enable this in SDK 1.6.6 and later
   srConfig.enableHeatmap = YES;
   srConfig.sessionReplaySamplingRate = 100; // Supported in SDK 1.6.8 and later
   [[FTRumSessionReplay sharedInstance] startWithSessionReplayConfig:srConfig];
   let srConfig = FTSessionReplayConfig.init()
   srConfig.touchPrivacy = .show
   srConfig.textAndInputPrivacy = .maskSensitiveInputs
   srConfig.imagePrivacy = .maskNonBundledOnly
   // To capture SwiftUI pages, enable this in SDK 1.6.5 and later
   srConfig.enableSwiftUI = true
   // To enable Session Replay heatmap correlation, enable this in SDK 1.6.6 and later
   srConfig.enableHeatmap = true
   srConfig.sessionReplaySamplingRate = 100 // Supported in SDK 1.6.8 and later
   FTRumSessionReplay.shared().start(with: srConfig)
Property Type Required Description
sessionReplaySamplingRate float No Session Replay percentage sampling rate, range [0,100], supports decimals (0.1 means 0.1%, 1 means 1%), defaults to 100 (full sampling). Replay sampling is performed on top of RUM session sampling. The legacy remote field uses a [0,1] ratio; see Remote Sampling Configuration. Supported in SDK 1.6.8 and later.
sampleRate int No Deprecated as of SDK 1.6.8, retained for compatibility. Integer percentage sampling rate, range [0,100], defaults to 100. It is recommended to use sessionReplaySamplingRate instead.
sessionReplayOnErrorSamplingRate float No Replay error supplementary sampling percentage, range [0,100], supports decimals, defaults to 0; used for sessions that do not hit normal Replay sampling. Supported in SDK 1.6.8 and later.
sessionReplayOnErrorSampleRate int No Deprecated as of SDK 1.6.8, retained for compatibility. Integer percentage error supplementary sampling configuration, range [0,100], defaults to 0. It is recommended to use sessionReplayOnErrorSamplingRate instead.
privacy FTSRPrivacy No Sets the privacy level for content masking in Session Replay. Defaults to FTSRPrivacyMask.
Masking behavior: text is replaced with * or #.
FTSRPrivacyAllow: Records text and input content except sensitive input controls, shows user touches, and records all images.
FTSRPrivacyMaskUserInput: Masks input elements and hides user touches; records only SF Symbols and images loaded via [UIImage imageNamed:] / UIImage(named:) and bundled with the app.
FTSRPrivacyMask: Masks all text, input, touches, and images.
Will be deprecated but remains compatible. Prefer touchPrivacy, textAndInputPrivacy, and imagePrivacy for fine-grained masking privacy level settings.
touchPrivacy FTTouchPrivacyLevel No Available privacy levels for touch masking in Session Replay. Defaults to FTTouchPrivacyLevelHide.
FTTouchPrivacyLevelShow: Shows all user touches
FTTouchPrivacyLevelHide: Masks all user touches
Overrides the privacy configuration when set
Supported in SDK 1.6.1 and later
textAndInputPrivacy FTTextAndInputPrivacyLevel No Available privacy levels for text and input masking in Session Replay. Defaults to FTTextAndInputPrivacyLevelMaskAll
FTTextAndInputPrivacyLevelMaskSensitiveInputs: Shows all text except sensitive inputs, such as password inputs
FTTextAndInputPrivacyLevelMaskAllInputs: Masks all input fields, such as UITextField, UISwitch, UISlider, etc.
FTTextAndInputPrivacyLevelMaskAll: Masks all text and input
Overrides the privacy configuration when set
Supported in SDK 1.6.1 and later
imagePrivacy FTImagePrivacyLevel No Available privacy levels for image masking in Session Replay. Defaults to FTImagePrivacyLevelMaskAll.
FTImagePrivacyLevelMaskNonBundledOnly: Records only SF Symbols and images loaded via [UIImage imageNamed:] / UIImage(named:) and bundled with the app; images downloaded from the network or generated at runtime are masked.
FTImagePrivacyLevelMaskAll: Masks all images.
FTImagePrivacyLevelMaskNone: Records all images, including images downloaded from the network or generated at runtime. Use only after confirming the images do not contain sensitive content.
Overrides the privacy configuration when set
Supported in SDK 1.6.2 and later
enableSwiftUI BOOL No Enables Session Replay collection for SwiftUI pages. Defaults to NO. Supported in SDK 1.6.5 and later
enableHeatmap BOOL No Enables Session Replay heatmap correlation. Defaults to NO. This is an experimental feature. Supported in SDK 1.6.6 and later
enableLinkRUMKeys NSArray No When enabled, associates the corresponding fields in the RUM Context with Session Replay data according to the configured keys. Can be used to route Session Replay data
Supported in SDK 1.6.2 and later

Note: enableHeatmap is only used to correlate automatically collected UIKit Actions. Some UIKit Actions may not support Heatmap. SwiftUI Actions are not currently automatically collected, so they cannot be correlated with the heatmap via enableHeatmap.

Privacy Overrides

Supported in SDK 1.6.1 and later

In addition to configuring global masking levels through FTSessionReplayConfig, the SDK also supports overriding these settings at the view level.

View-level privacy overrides:

  • Supports overriding text and input masking levels, touch masking levels, and image masking levels (supported in SDK 1.6.2 and later)
  • Supports completely hiding specific views

Notes:

  • To ensure overrides are correctly recognized, apply them as early as possible in the view lifecycle. This prevents Session Replay from processing a view before the configured overrides are applied.
  • Privacy overrides affect a view and its subviews. This means that even if an override is applied to a view where it may not take effect immediately (for example, applying an image override to a text input), the override still applies to all subviews.
  • Privacy override priority: subview > parent view > global settings

Text and Input Overrides

To override text and input privacy, use sessionReplayPrivacyOverrides.textAndInputPrivacy on a view instance to set it to a value in the FTTextAndInputPrivacyLevelOverride enum. To remove an existing override rule, set the property to FTTextAndInputPrivacyLevelOverrideNone.

@import TrueWatchSessionReplay;
// Set a text and input override for the specified view
   myView.sessionReplayPrivacyOverrides.textAndInputPrivacy = FTTextAndInputPrivacyLevelOverrideMaskAll;
   // Remove the text and input override setting from the view
   myView.sessionReplayPrivacyOverrides.textAndInputPrivacy = FTTextAndInputPrivacyLevelOverrideNone;
   // Set a text and input override for the specified view
   myView.sessionReplayPrivacyOverrides.textAndInputPrivacy = .maskAll
   // Remove the text and input override setting from the view
   myView.sessionReplayPrivacyOverrides.textAndInputPrivacy = .none

Touch Overrides

To override touch privacy, use sessionReplayPrivacyOverrides.touchPrivacy on a view instance to set it to a value in the FTTouchPrivacyLevelOverride enum. To remove an existing override rule, set the property to FTTouchPrivacyLevelOverrideNone.

@import TrueWatchSessionReplay;
// Set a touch override for the specified view
   myView.sessionReplayPrivacyOverrides.touchPrivacy = FTTouchPrivacyLevelOverrideShow;
   // Remove the touch override setting from the view
   myView.sessionReplayPrivacyOverrides.touchPrivacy = FTTouchPrivacyLevelOverrideNone;
   // Set a touch override for the specified view
   myView.sessionReplayPrivacyOverrides.touchPrivacy = .show;
   // Remove the touch override setting from the view
   myView.sessionReplayPrivacyOverrides.touchPrivacy = .none;

Image Overrides

Supported in SDK 1.6.2 and later

To override image privacy, use sessionReplayPrivacyOverrides.imagePrivacy on a view instance to set it to a value in the FTImagePrivacyLevelOverride enum. To remove an existing override rule, set the property to FTImagePrivacyLevelOverrideNone.

Available image override levels:

  • FTImagePrivacyLevelOverrideMaskNonBundledOnly: Records only SF Symbols and images loaded via [UIImage imageNamed:] / UIImage(named:) and bundled with the app; images downloaded from the network or generated at runtime are masked.
  • FTImagePrivacyLevelOverrideMaskAll: Masks all images.
  • FTImagePrivacyLevelOverrideMaskNone: Records all images, including images downloaded from the network or generated at runtime. Use only after confirming the images do not contain sensitive content.
@import TrueWatchSessionReplay;
// Set an image override for the specified view
   myImageView.sessionReplayPrivacyOverrides.imagePrivacy = FTImagePrivacyLevelOverrideMaskNonBundledOnly;
   // Remove the image override setting from the view
   myImageView.sessionReplayPrivacyOverrides.imagePrivacy = FTImagePrivacyLevelOverrideNone;
   // Set an image override for the specified view
   myImageView.sessionReplayPrivacyOverrides.imagePrivacy = .maskNonBundledOnly
   // Remove the image override setting from the view
   myImageView.sessionReplayPrivacyOverrides.imagePrivacy = .none

Hidden Element Overrides

For sensitive elements that need to be completely hidden, use sessionReplayPrivacyOverrides.hide to configure them.

When an element is set to hidden, it is replaced with a placeholder marked "Hidden" in the replay, and its subviews are not recorded.

Note: Marking a view as hidden does not prevent touch interactions from being recorded on that element. To hide touch interactions, in addition to marking the element as hidden, use Touch Overrides.

@import TrueWatchSessionReplay;
// Mark a hidden element override for the specified view
   myView.sessionReplayPrivacyOverrides.hide = YES;
   // Remove the hidden element override setting from the view
   myView.sessionReplayPrivacyOverrides.hide = NO;
   // Mark a hidden element override for the specified view
   myView.sessionReplayPrivacyOverrides.hide = true;
   // Remove the hidden element override setting from the view
   myView.sessionReplayPrivacyOverrides.hide = false;

Webview Session Replay

Supported in SDK 1.6.2 and later

First complete the Session Replay initialization on this page and WebView page initialization, then enable recording in the page:

// In addition to the webview RUM settings
window.DATAFLUX_RUM.startSessionReplayRecording();

Code and Configuration Reference