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¶
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 touchesFTTouchPrivacyLevelHide: Masks all user touchesOverrides the privacy configuration when setSupported in SDK 1.6.1 and later |
| textAndInputPrivacy | FTTextAndInputPrivacyLevel | No | Available privacy levels for text and input masking in Session Replay. Defaults to FTTextAndInputPrivacyLevelMaskAllFTTextAndInputPrivacyLevelMaskSensitiveInputs: Shows all text except sensitive inputs, such as password inputsFTTextAndInputPrivacyLevelMaskAllInputs: Masks all input fields, such as UITextField, UISwitch, UISlider, etc.FTTextAndInputPrivacyLevelMaskAll: Masks all text and inputOverrides the privacy configuration when setSupported 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 setSupported 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:
enableHeatmapis 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 viaenableHeatmap.
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;
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.
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;
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.
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: