Skip to content

HarmonyOS Session Replay (Experimental)

HarmonyOS Session Replay reconstructs pages by recording ArkUI page structure, visual changes, and user operations, and correlates them with RUM Sessions, Views, and Errors. ArkWeb pages also require the Browser SDK integration. This capability is provided by the standalone ft_session_replay package.

The current version is an Alpha pre-release, 0.1.0-alpha04; features and APIs are still subject to change.

Prerequisites

  • Make sure you have set up and initialized the SDK RUM configuration and enabled View monitoring collection.
  • HarmonyOS Session Replay requires ft_sdk 0.1.18-alpha04 or later, and requires installing ft_session_replay separately.
  • Automatic collection requires integrating @cloudcare/hvigor-ohos-plugin with Session Replay support, and initializing Replay after RUM initialization is complete.
  • The app must use HarmonyOS API 12 or later and enable normalized OHMUrl. The plugin is currently validated in Node.js 18+, Hvigor 6.23.5, and HarmonyOS SDK 6.0.2 (API 22).
  • For local deployment, enable replay reception as described in Mobile Session Replay collector configuration; the public DataWay requires no additional configuration.

Configuration

Import the SDK

In the app module that requires automatic collection, install the core package and the Replay package:

ohpm install @truewatchtech/ft_sdk
ohpm install @truewatchtech/ft_session_replay

When using local HAR files, declare scoped dependencies on ft_sdk.har and ft_session_replay.har in the module's oh-package.json5, and in the project root use overrides to point the core package that Replay depends on to the same local HAR. The configuration is the same as local integration of extension packages.

Import the Hvigor Plugin

Add the build plugin in the project-level hvigor/hvigor-config.json5:

{
  "dependencies": {
    "@cloudcare/hvigor-ohos-plugin": "latest"
  }
}

Register it in the app HAP's hvigorfile.ts:

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin';

export default {
  system: hapTasks,
  plugins: [ftConsoleLogPlugin()]
};

Each source module that requires automatic collection must declare the core package and the Replay package in the dependencies of its own oh-package.json5. Declaring them only in the root directory, in other modules, or in devDependencies does not enable instrumentation for that module. The plugin automatically handles the supported @Entry page root nodes, visibility, touch, Router transitions, and the association between ArkUI Web components and controllers, and preserves existing callbacks.

Code Invocation

In UIAbility.onCreate, initialize the core SDK, RUM, and Replay in sequence. Pass the app-private filesDir to Replay to persist the cache.

import { UIAbility } from '@kit.AbilityKit';
import {
  FTSDK, FTSDKConfig, FTRUMConfig
} from '@truewatchtech/ft_sdk/Index';
import {
  FTSessionReplay, FTSessionReplayConfig,
  TouchPrivacy, ImagePrivacy, TextAndInputPrivacy
} from '@truewatchtech/ft_session_replay/Index';

export default class EntryAbility extends UIAbility {
  onCreate(): void {
    FTSDK.install(FTSDKConfig.builder('YOUR_DATAKIT_URL'), this.context);
    FTSDK.installRUMConfig(new FTRUMConfig()
      .setRumAppId('YOUR_RUM_APP_ID')
      .setSessionSamplingRate(100)
      .setEnableTraceUserView(true));

    const replayConfig = new FTSessionReplayConfig()
      .setSampleRate(10)
      .setTouchPrivacy(TouchPrivacy.SHOW) // Show touch positions.
      .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY) // Mask large images.
      .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS) // Mask sensitive inputs such as passwords.
      .setDelayInit(true);
    const replay = FTSessionReplay.getInstance();
    replay.init(replayConfig, this.context.filesDir);

    // Start recording.
    replay.start();
  }
}

The example uses setDelayInit(true) and calls start() after init() to start recording; if not set, init() starts automatically by default.

After integrating the Hvigor plugin, touch events and Router page transitions are collected automatically; for custom Navigation transitions, see ArkUI Support.

To stop recording, call replay.disable(); to resume, call replay.start(). After stopping, accepted frames continue to be saved, and automatic upload continues to process pending data; RUM collection is not affected, and existing Replay cache is not cleared.

You can call await replay.flush() to request upload immediately. Data is stored in the app's private directory, and the Replay package does not additionally encrypt these files.

Method Type Required Description
setSampleRate number No Sets the Session Replay sampling rate. Value range [0,100]; 0 means no collection, 100 means full collection; default is 100. Decimal values are supported.
setSessionReplayOnErrorSampleRate number No Sets the error recording sampling rate, which applies to Sessions that did not hit regular recording; the data from the 1 minute before the error is retained locally, and enters the upload queue after a related RUM Error is received. Value range [0,100], default is 0, decimal values are supported.
setTextAndInputPrivacy TextAndInputPrivacy No Sets the text and input masking level. MASK_SENSITIVE_INPUTS retains normal text and masks sensitive inputs; MASK_ALL_INPUTS masks all inputs; MASK_ALL masks text and inputs. Default is MASK_ALL.
setCaptureVisiblePassword boolean No Whether to allow collecting passwords that the user actively displays. Default is false; still masked under MASK_ALL_INPUTS and MASK_ALL.
setImagePrivacy ImagePrivacy No Sets the image masking level. MASK_ALL masks all images; MASK_LARGE_ONLY masks large images; MASK_NONE does not mask images. Default is MASK_ALL.
setTouchPrivacy TouchPrivacy No Sets the touch masking level. SHOW records touch positions, HIDE hides touch positions. Default is HIDE.
enableLinkRUMKeys Array<string> No Links the specified RUM context fields to Session Replay data. Default is an empty array. Can be used to route replay data.
setDelayInit boolean No Whether to delay starting recording. Default is false; when set to true, you must call start() to start recording.

Replay sampling is configured independently of RUM sampling and is not overridden by the core SDK's remote sampling configuration.

After replay frames are saved successfully, the associated native View, Action, Resource, LongTask, and Error can carry session_has_replay=true; Session aggregated data uses has_replay to indicate whether the current session is associated with replay data. The replay flag is set automatically by the SDK based on actual recording results; merely completing Replay initialization does not mean that usable replay data exists.

Privacy Configuration

The SDK supports configuring global masking levels through FTSessionReplayConfig, including:

  • Image masking level
  • Text and input masking level
  • Touch masking level

Notes:

  • The following configurations should be set before init() and apply to global Session Replay collection.
  • RUM's DataModifier and LineDataModifier are used to mask telemetry fields; replay images use the privacy configuration in this section.

The replayConfig and enums in the following examples follow the definitions in Code Invocation.

Image Masking

Use setImagePrivacy(ImagePrivacy) to set the image masking level.

// Mask large images.
replayConfig.setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY);

Text and Input Masking

Use setTextAndInputPrivacy(TextAndInputPrivacy) to set the text and input masking level.

// Retain normal text and mask sensitive inputs such as passwords.
replayConfig.setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS);

To allow collecting actively displayed passwords, the page must bind showPassword to a state synchronized with onSecurityStateChange; enabling only setCaptureVisiblePassword(true) does not override the text privacy policy.

Touch Masking

Use setTouchPrivacy(TouchPrivacy) to set whether touch positions are masked.

// Record touch positions.
replayConfig.setTouchPrivacy(TouchPrivacy.SHOW);

Webview Session Replay

ArkWeb must meet all of the following conditions:

  1. Native RUM has setEnableTraceWebView(true) enabled, and FTWebViewHandler is integrated as described in WebView Data Monitoring.
  2. Native Replay has been initialized and started, and the Web component is associated with the controller through the Hvigor plugin.
  3. The web page integrates the Browser SDK that supports the native Replay Bridge, and calls startSessionReplayRecording() in the web page.

Tip: We recommend starting native Replay and binding FTWebViewHandler before loading the web page's Browser SDK. Web page replay is controlled by native Replay sampling, and the privacy level is provided by the native Bridge by default; it can also be set through the web page's defaultPrivacyLevel.

ArkUI Support

The supported collection content includes page structure, text, layout, scrolling, supported animations and native controls, overlays, images, and drawing components.

Image Support Scope

The Image and ImageAnimator image components are supported. Regular Image images are collected through system component snapshots, which requires the image to be loaded, the component to be visible, and the content to be readable; Base64 images can be read directly from the encoded data.

Image Source Typical Usage Support Notes
App resource image Image($r('app.media.icon')) Automatically collects the image content displayed by the component.
Local file image Image loads a local path or file:// address accessible to the app Collected automatically after the image is loaded and displayed.
Network image Image loads an HTTP(S) image URL Collects the content that the component has loaded; if loading fails or the image is not yet displayed, there is no corresponding image content.
In-memory image Image uses PixelMap Automatically collects the in-memory image displayed by the component.
Drawable resource Image uses DrawableDescriptor Collected automatically after the resource is successfully rendered to the image component.
Base64 embedded image data:image/...;base64,... Supports reading the image encoded data; see below for format and size limits.

For images that cannot be obtained automatically, you can provide the encoded data manually via registerImageAsset(...) by image component ID or image source string.

Base64 embedded images and manually supplemented assets support PNG (image/png), JPEG (image/jpeg), GIF (image/gif), WebP (image/webp), and SVG (image/svg+xml). A single piece of image encoded data must not exceed 2 MiB; Base64 images are measured by their decoded size.

Drawing Component Support

The following components support capturing content through component snapshots:

Category Supported Components
QR code QRCode
Canvas Canvas
Shape drawing Shape, Rect, Circle, Ellipse, Line, Polygon, Polyline, Path

Collection Limits

Scope Limit
Images and drawing components Image masking configuration defaults to ImagePrivacy.MASK_ALL, which masks the content. Drawing components are also masked under TextAndInputPrivacy.MASK_ALL.
Component snapshots For API 12–14, a stable .id(...) must be set for image or drawing components. Captured content may be scaled and is not guaranteed to retain the original resolution.
Animated images ImageAnimator records animation changes as sampled frames and does not guarantee frame-by-frame reproduction; animated images in a regular Image are also not guaranteed to be fully synchronized with the original animation.
Native animations and visual effects Playback of native animations, blur materials, text layout, and system default transitions may differ from the original.
Rich text RichText collects only text, paragraphs, and basic styles; it does not collect scripts, HTML images, or complex web layouts within it.
PatternLock May require additional forwarding or explicit content provision; installing the plugin alone does not guarantee complete recording.
Navigation transitions Requires API 15+. Custom transitions require additional forwarding; you can use updateNavigationTransition(...) and finishNavigationTransition(...) to forward progress and the finish state.

Advanced Configuration

Manual Page Integration

import { FTSessionReplay } from '@truewatchtech/ft_session_replay/Index';

@Entry
@Component
struct ReplayPage {
  private replay: FTSessionReplay = FTSessionReplay.getInstance();

  private registerReplayRoot(): void {
    this.replay.registerRoot(this.getUIContext(), 'replay-page-root', vp2px(1));
  }

  onPageShow(): void {
    this.registerReplayRoot();
  }

  onPageHide(): void {
    this.replay.unregisterRoot();
  }

  build() {
    Column() {
      Text('Session Replay');
    }
    .id('replay-page-root')
    .onAreaChange(() => this.registerReplayRoot())
    .onTouch((event: TouchEvent) => this.replay.recordTouchEvent(event))
  }
}

Note: For ArkUI pages whose root node is not registered automatically by the plugin, you can integrate them manually as shown in the example above. If Replay starts after the page is displayed, you must call registerRoot(...) again to register the current page. If a child component intercepts touch events, forward them through recordTouchEvent(event); to show touch positions, enable TouchPrivacy.SHOW.

Code and Configuration References