Android SESSION REPLAY¶

Prerequisites¶

• Ensure you have set up and initialized the FTSdk RUM configuration and enabled View monitoring collection.
• Android Session Replay requires ft-sdk:1.7.0 or higher.
• ft-session-replay and ft-session-replay-material must use the same version number.
• Starting from ft-sdk version 1.7.2, there is no longer a strong dependency on ft-session-replay. You only need to add the ft-session-replay and related extension dependencies when you need to enable Session Replay.
• It is recommended to prioritize using the stable release version displayed by the badges at the top of the document. Using pre-release versions like alpha or beta is no longer recommended.
• If you wish to access cutting-edge capabilities early, stay updated on the latest features, or follow changes not yet officially released, you can visit the GitHub repository for the Android SDK and its changelog: GuanceCloud/datakit-android

Configuration¶

// Add SDK dependency
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
// Required to enable session replay functionality
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay:[session_replay_version]'
// Required to support Material components for session replay
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay-material:[session_replay_version]'
// Required to support Compose components for session replay
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay-compose:[session_replay_version]'

Flutter RUM Context Compatibility¶

Versions of ft-session-replay 0.1.5 and above are compatible with the RUM context fields used by Flutter Session Replay for data upload. When Flutter pages or Flutter SDK collection traces exist within a native Android project, upgrading to ft-session-replay:0.1.5 or higher allows Flutter Replay data to be correctly mapped to the corresponding Replay Segment without additional configuration.

In hybrid scenarios, it is still recommended to complete RUM initialization before initializing Session Replay to ensure that context such as app_id, session_id, and view_id is established.

Code Sample¶

FTSdk.initSessionReplayConfig(new FTSessionReplayConfig().setSampleRate(1f)
                .setTouchPrivacy(TouchPrivacy.SHOW)
                .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY)
                .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS)
                .addExtensionSupport(new MaterialExtensionSupport()), context);

FTSdk.initSessionReplayConfig(FTSessionReplayConfig().setSampleRate(1f)
                .setTouchPrivacy(TouchPrivacy.SHOW)
                .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY)
                .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS)
                .addExtensionSupport(MaterialExtensionSupport()), context)

Privacy Override¶

Supported in ft-session-replay 0.1.1-alpha01 and above.

In addition to supporting global masking levels configured via FTSessionReplayConfig, the SDK also supports overriding these settings at the view level.

View-level privacy override:

• Supports overriding image masking level.
• Supports overriding text and input masking level and touch masking level.
• Supports setting specific views to be completely hidden.

Note:

• To ensure correct identification of override settings, they should be applied as early as possible in the view lifecycle. This prevents cases where Session Replay processes the view before the applied override takes effect.
• Privacy overrides affect the view and its child views. This means that even if an override is applied to a view where it might not take effect immediately (e.g., applying an image override to a text input), the override will still apply to all child views.
• Privacy override priority: Child view > Parent view > Global setting

Image Override¶

Requires ft-sdk >= 1.7.0-alpha40, ft-session-replay >= 0.1.3-alpha14.

To override image privacy, use PrivacyOverrideExtensions.setSessionReplayImagePrivacy(View,ImagePrivacy) on the view instance, setting it to one of the values in the ImagePrivacy enum. To remove an existing override rule, simply set this property to null.

// Mark image privacy override for a specified view
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, ImagePrivacy.MASK_ALL);
// Remove image privacy override settings for the view
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, null);

// Mark image privacy override for a specified view
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, ImagePrivacy.MASK_ALL)
// Remove image privacy override settings for the view
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, null)

Text and Input Override¶

To override text and input privacy, use PrivacyOverrideExtensions.setSessionReplayTextAndInputPrivacy(View,TextAndInputPrivacy) on the view instance, setting it to one of the values in the TextAndInputPrivacy enum. To remove an existing override rule, simply set this property to null.

// Mark hidden element override for a specified view
PrivacyOverrideExtensions.setSessionReplayTextAndInputPrivacy(view, TextAndInputPrivacy.MASK_ALL);
// Remove hidden element override settings for the view
PrivacyOverrideExtensions.setSessionReplayTextAndInputPrivacy(view, null);

// Mark hidden element override for a specified view
PrivacyOverrideExtensions.setSessionReplayTextAndInputPrivacy(view, TextAndInputPrivacy.MASK_ALL)
// Remove hidden element override settings for the view
PrivacyOverrideExtensions.setSessionReplayTextAndInputPrivacy(view, null)

Touch Override¶

To override touch privacy, use PrivacyOverrideExtensions.setSessionReplayTouchPrivacy(View,TouchPrivacy) on the view instance, setting it to one of the values in the TouchPrivacy enum. To remove an existing override rule, simply set this property to null.

// Mark hidden element override for a specified view
PrivacyOverrideExtensions.setSessionReplayTouchPrivacy(view, TouchPrivacy.HIDE);
// Remove hidden element override settings for the view
PrivacyOverrideExtensions.setSessionReplayTouchPrivacy(view, null);

// Mark hidden element override for a specified view
PrivacyOverrideExtensions.setSessionReplayTouchPrivacy(view, TouchPrivacy.HIDE)
// Remove hidden element override settings for the view
PrivacyOverrideExtensions.setSessionReplayTouchPrivacy(view, null)

Hidden Element Override¶

For sensitive elements that need to be completely hidden, use PrivacyOverrideExtensions.setSessionReplayHidden(View,Boolean) to set them.

When an element is set to hidden, it will be replaced by a placeholder marked as "Hidden" in the replay, and its child views will not be recorded.

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

// Mark hidden element override for a specified view
PrivacyOverrideExtensions.setSessionReplayHidden(view, true)
// Remove hidden element override settings for the view
PrivacyOverrideExtensions.setSessionReplayHidden(view, false)

// Mark hidden element override for a specified view
PrivacyOverrideExtensions.setSessionReplayHidden(view, true)
// Remove hidden element override settings for the view
PrivacyOverrideExtensions.setSessionReplayHidden(view, false)

Webview Session Replay¶

Supported in ft-session-replay 0.1.3-alpha11, ft-sdk 1.7.0-alpha36 and above.

For WebView Session Replay, you need to integrate the Web Monitoring SDK into the pages accessed by the WebView, and enable Session Replay within the Webview.

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

Tencent Webivew X5 Support¶

FTSdk.initSessionReplayConfig(new FTSessionReplayConfig()
    //...
    // Additionally set CustomExtensionSupport
    .addExtensionSupport(new CustomExtensionSupport()
            .addMapper(new MapperTypeWrapper<>(com.tencent.smtt.sdk.WebView.class,
                    new WebViewXWireframeMapper())))
)

FTSdk.initSessionReplayConfig(FTSessionReplayConfig()
    //...
    // Additionally set CustomExtensionSupport
    .addExtensionSupport(
        CustomExtensionSupport()
            .addMapper(
                MapperTypeWrapper(
                    com.tencent.smtt.sdk.WebView::class.java,
                    WebViewXWireframeMapper()
                )
            )
    )
)

Jetpack Compose Support¶

ft-session-replay-compose must use the same version number as ft-session-replay.

Android Session Replay now supports collection and replay of Jetpack Compose interfaces. When using Compose pages, you need to additionally introduce the Compose extension dependency and add ComposeExtensionSupport to the FTSessionReplayConfig.

Add Dependency¶

implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay-compose:[session_replay_version]'

Initialization Configuration¶

FTSdk.initSessionReplayConfig(new FTSessionReplayConfig().setSampleRate(1f)
                .setTouchPrivacy(TouchPrivacy.SHOW)
                .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY)
                .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS)
                .addExtensionSupport(new ComposeExtensionSupport())
                .addExtensionSupport(new MaterialExtensionSupport()), context);

FTSdk.initSessionReplayConfig(FTSessionReplayConfig().setSampleRate(1f)
                .setTouchPrivacy(TouchPrivacy.SHOW)
                .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY)
                .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS)
                .addExtensionSupport(ComposeExtensionSupport())
                .addExtensionSupport(MaterialExtensionSupport()), context)

Compose Privacy Override¶

Compose pages support overriding Session Replay privacy configurations via Modifier:

• sessionReplayHide(Boolean): Hides the specified Compose node.
• sessionReplayImagePrivacy(ImagePrivacy): Overrides the image privacy level.
• sessionReplayTextAndInputPrivacy(TextAndInputPrivacy): Overrides the text and input privacy level.
• sessionReplayTouchPrivacy(TouchPrivacy): Overrides the touch privacy level.

Current Limitations¶

• Compose replay relies on semantic nodes and component mapping, pixel-perfect restoration is not guaranteed.
• Currently supports replay of common components like text, input fields, images, buttons, switches, sliders, radio buttons, checkboxes, tabs, and container components.
• Brush backgrounds are not yet supported. For example, linear gradients, radial gradients, etc., will not be restored with their original gradient effects. It is recommended to use solid color backgrounds for key demonstration areas.

Code and Configuration Reference¶

• Android Demo Gradle Configuration
• Android Demo Code Sample