Android Session Replay¶

Prerequisites¶

• Make sure 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 later.
• ft-session-replay and ft-session-replay-material must use the same version number.
• ft-sdk 1.7.2 and later no longer strictly depend on ft-session-replay; you only need to add ft-session-replay and related extension dependencies when Session Replay is enabled.

• It is recommended to use the official stable release version shown in the badge at the top of this document, and to avoid pre-release versions such as alpha and beta.

• If you want early access to advanced capabilities, keep up with the latest features, or track unreleased changes, you can follow the Android SDK repository and related changelogs on GitHub: GuanceCloud/datakit-android

Configuration¶

// Add the SDK dependency
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
// Add this if Session Replay is enabled
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay:[session_replay_version]'
// Add material component support for Session Replay
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay-material:[session_replay_version]'
// Add Compose component support for Session Replay
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-session-replay-compose:[session_replay_version]'

Flutter RUM Context Compatibility¶

ft-session-replay 0.1.5 and later is compatible with the RUM context fields used when uploading Flutter Session Replay. When Flutter pages or Flutter SDK collection pipelines exist in a native Android project, upgrading to ft-session-replay:0.1.5 or later correctly maps Flutter Replay data to the corresponding Replay Segment without additional configuration.

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

Code Sample¶

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

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

Privacy Overrides¶

Supported in ft-session-replay 0.1.1-alpha01 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:

• Support overriding the image masking level
• Support overriding the text and input masking level and the touch masking level
• Support fully hiding specific views

Notes:

• To ensure override settings are correctly recognized, apply them as early as possible in the view lifecycle. This prevents Session Replay from processing a view before the configured override is applied.
• Privacy overrides affect the view and its child views. 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 child views.
• Privacy override priority: child view > parent view > global settings

Image Override¶

Supported in ft-sdk >= 1.7.0-alpha40 and ft-session-replay >= 0.1.3-alpha14.

To override image privacy, use PrivacyOverrideExtensions.setSessionReplayImagePrivacy(View,ImagePrivacy) on the view instance and set it to a value in the ImagePrivacy enum. To remove an existing override rule, set the property to null.

// Mark the specified view with an image privacy override
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, ImagePrivacy.MASK_ALL);
// Remove the image privacy override from the view
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, null);

// Mark the specified view with an image privacy override
PrivacyOverrideExtensions.setSessionReplayImagePrivacy(view, ImagePrivacy.MASK_ALL)
// Remove the image privacy override from 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 and set it to a value in the TextAndInputPrivacy enum. To remove an existing override rule, set the property to null.

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

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

Touch Override¶

To override touch privacy, use PrivacyOverrideExtensions.setSessionReplayTouchPrivacy(View,TouchPrivacy) on the view instance and set it to a value in the TouchPrivacy enum. To remove an existing override rule, set the property to null.

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

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

Hidden Element Override¶

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

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

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

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

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

Webview Session Replay¶

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

WebView Session Replay requires integrating the Web Monitoring SDK into the page accessed by the WebView and enabling Session Replay in the WebView.

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

Tencent Webivew X5 Support¶

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

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

Jetpack Compose Support¶

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

Android Session Replay now supports collecting and replaying Jetpack Compose UIs. When using Compose pages, you need to add the Compose extension dependency and add ComposeExtensionSupport to FTSessionReplayConfig.

Add Dependency¶

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

Initialize Configuration¶

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

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

Compose Privacy Overrides¶

Compose pages support overriding Session Replay privacy settings 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, so pixel-perfect restoration is not guaranteed.
• Currently, replay is supported for common text, input fields, images, buttons, switches, sliders, radio buttons, checkboxes, Tab, and container components.
• Brush backgrounds are not supported yet. For example, backgrounds such as linear gradients or radial gradients will not be restored with their original gradient effect. It is recommended to use solid-color backgrounds for key demonstration areas.

Code and Configuration Reference¶

• Android Demo Gradle Configuration
• Android Demo Code Sample