コンテンツにスキップ

HarmonyOS セッションリプレイ(実験的)

HarmonyOS セッションリプレイは、ArkUI のページ構造、視覚的な変化、ユーザー操作を記録してページを再構築し、RUM の Session、View、Error を関連付けます。ArkWeb ページでは、さらに Browser SDK を導入する必要があります。この機能は独立した ft_session_replay パッケージによって提供されます。

現在は Alpha プレリリースバージョン 0.1.0-alpha04 であり、機能と API は変更される可能性があります。

前提条件

  • SDK の RUM 設定のセットアップと初期化を完了し、View のモニタリング収集を有効にしてください。
  • HarmonyOS セッションリプレイには ft_sdk 0.1.18-alpha04 以降が必要で、さらに ft_session_replay をインストールする必要があります。
  • 自動収集には、セッションリプレイをサポートする @cloudcare/hvigor-ohos-plugin を導入する必要があり、RUM の初期化完了後に Replay を初期化します。
  • アプリケーションは HarmonyOS API 12 以降を使用し、正規化 OHMUrl を有効にする必要があります。プラグインの現在の検証環境は Node.js 18+、Hvigor 6.23.5、HarmonyOS SDK 6.0.2(API 22)です。
  • ローカルデプロイメントを使用する場合は、モバイルセッションリプレイコレクター設定に従ってリプレイ受信を有効にする必要があります。パブリック DataWay では追加設定は不要です。

設定

SDK の導入

自動収集が必要なアプリケーションモジュールに、コアパッケージと Replay パッケージをインストールします。

ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_session_replay

ローカル HAR を使用する場合、モジュールの oh-package.json5 で ft_sdk.har、ft_session_replay.har のスコープ付き依存関係を宣言し、プロジェクトルートで overrides を使用して Replay が依存するコアパッケージを同じローカル HAR に指定します。設定方法は拡張パッケージのローカル導入と同じです。

Hvigor プラグインの導入

プロジェクトレベルの hvigor/hvigor-config.json5 にビルドプラグインを追加します。

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

アプリケーション HAP の hvigorfile.ts で登録します。

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

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

自動収集が必要な各ソースモジュールは、自身の oh-package.json5 の dependencies でコアパッケージと Replay パッケージを宣言する必要があります。ルートディレクトリ、他のモジュール、または devDependencies でのみ宣言しても、そのモジュールのインストルメンテーションは有効になりません。プラグインは、サポート対象の @Entry ページルートノード、可視性、タッチ、Router トランジション、および ArkUI Web コントロールと controller の関連付けを自動的に処理し、既存のコールバックを保持します。

コード呼び出し

UIAbility.onCreate で、コア SDK、RUM、Replay を順に初期化します。アプリ固有の filesDir を Replay に渡してキャッシュを永続化します。

import { UIAbility } from '@kit.AbilityKit';
import {
  FTSDK, FTSDKConfig, FTRUMConfig
} from '@guancecloud/ft_sdk/Index';
import {
  FTSessionReplay, FTSessionReplayConfig,
  TouchPrivacy, ImagePrivacy, TextAndInputPrivacy
} from '@guancecloud/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) // タッチ位置を表示します。
      .setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY) // 大きな画像をマスクします。
      .setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS) // パスワードなどの機密入力をマスクします。
      .setDelayInit(true);
    const replay = FTSessionReplay.getInstance();
    replay.init(replayConfig, this.context.filesDir);

    // 記録を開始します。
    replay.start();
  }
}

この例では setDelayInit(true) を使用し、init() の後に start() を呼び出して記録を開始します。設定しない場合、init() はデフォルトで自動的に開始します。

Hvigor プラグインを導入すると、タッチイベントと Router ページトランジションが自動収集されます。カスタム Navigation トランジションについては ArkUI サポート を参照してください。

記録を停止する必要がある場合は replay.disable() を呼び出し、再開する場合は replay.start() を呼び出します。停止後も、受け入れ済みのフレームは引き続き保存され、自動アップロードはアップロード待ちデータの処理を継続します。RUM の収集には影響せず、既存の Replay キャッシュもクリアしません。

await replay.flush() を呼び出すと、即座にアップロードを要求できます。データはアプリのプライベートディレクトリに保存され、Replay パッケージはこれらのファイルを追加で暗号化しません。

メソッド名 型 必須 意味
setSampleRate number いいえ セッションリプレイのサンプリングレートを設定します。値の範囲は [0,100] で、0 は収集なし、100 は全収集を示します。デフォルト値は 100 で、小数をサポートします
setSessionReplayOnErrorSampleRate number いいえ エラー記録のサンプリングレートを設定します。通常の記録に該当しなかった Session に適用されます。エラー発生前 1 分間のデータをローカルに保持し、関連する RUM Error を受信するとアップロードキューに入ります。値の範囲は [0,100]、デフォルト値は 0 で、小数をサポートします
setTextAndInputPrivacy TextAndInputPrivacy いいえ テキストと入力のマスクレベルを設定します。MASK_SENSITIVE_INPUTS は通常のテキストを保持し、機密入力をマスクします。MASK_ALL_INPUTS はすべての入力をマスクします。MASK_ALL はテキストと入力をマスクします。デフォルトは MASK_ALL
setCaptureVisiblePassword boolean いいえ ユーザーが明示的に表示したパスワードの収集を許可するかどうか。デフォルトは false です。MASK_ALL_INPUTS、MASK_ALL では引き続きマスクされます
setImagePrivacy ImagePrivacy いいえ 画像のマスクレベルを設定します。MASK_ALL はすべての画像をマスクします。MASK_LARGE_ONLY は大きな画像をマスクします。MASK_NONE は画像をマスクしません。デフォルトは MASK_ALL
setTouchPrivacy TouchPrivacy いいえ タッチのマスクレベルを設定します。SHOW はタッチ位置を記録し、HIDE はタッチ位置を隠します。デフォルトは HIDE
enableLinkRUMKeys Array<string> いいえ 指定した RUM コンテキストフィールドをセッションリプレイデータに関連付けます。デフォルトは空の配列で、リプレイデータの振り分けに使用できます
setDelayInit boolean いいえ 記録の開始を遅延するかどうか。デフォルトは false です。true に設定した場合、start() を呼び出して記録を開始する必要があります

セッションリプレイのサンプリングは RUM のサンプリングとは独立して設定され、コア SDK のリモートサンプリング設定によって上書きされません。

リプレイフレームの保存に成功すると、関連付けられたネイティブ View、Action、Resource、LongTask、Error に session_has_replay=true を付与できます。Session の集約データでは has_replay を使用して、現在のセッションにリプレイデータが関連付けられているかどうかを示します。リプレイマーカーは SDK が実際の記録結果に基づいて自動的に設定します。Replay の初期化が完了しただけでは、利用可能なリプレイデータが存在することを意味しません。

プライバシー設定

SDK では、FTSessionReplayConfig を使用してグローバルなマスクレベルを設定できます。設定項目は次のとおりです。

  • 画像マスクレベル
  • テキストと入力のマスクレベル
  • タッチのマスクレベル

注意:

  • 以下の設定は init() の前に設定する必要があり、セッションリプレイのグローバル収集に適用されます。
  • RUM の DataModifier、LineDataModifier はテレメトリフィールドのマスキングに使用されます。リプレイ画面では本節のプライバシー設定を使用します。

以下の例の replayConfig と列挙型は、コード呼び出しの定義をそのまま使用します。

画像マスク

setImagePrivacy(ImagePrivacy) を使用して画像のマスクレベルを設定します。

// 大きな画像をマスクします。
replayConfig.setImagePrivacy(ImagePrivacy.MASK_LARGE_ONLY);

テキストと入力のマスク

setTextAndInputPrivacy(TextAndInputPrivacy) を使用してテキストと入力のマスクレベルを設定します。

// 通常のテキストを保持し、パスワードなどの機密入力をマスクします。
replayConfig.setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS);

ユーザーが明示的に表示したパスワードの収集を許可する場合、ページは showPassword を onSecurityStateChange と同期する状態にバインドする必要があります。setCaptureVisiblePassword(true) を有効にするだけでは、テキストプライバシーポリシーは上書きされません。

タッチのマスク

setTouchPrivacy(TouchPrivacy) を使用して、タッチ位置をマスクするかどうかを設定します。

// タッチ位置を記録します。
replayConfig.setTouchPrivacy(TouchPrivacy.SHOW);

Webview セッションリプレイ

ArkWeb では、次の条件をすべて満たす必要があります。

  1. ネイティブ RUM で setEnableTraceWebView(true) を有効にし、WebView データモニタリングに従って FTWebViewHandler を導入します。
  2. ネイティブ Replay が初期化および開始済みで、Hvigor プラグインを介して Web コンポーネントと controller が関連付けられていること。
  3. Web ページに、ネイティブ Replay Bridge をサポートする Browser SDK を導入し、Web ページ内で startSessionReplayRecording() を呼び出します。

ヒント:先にネイティブ Replay を開始して FTWebViewHandler をバインドし、その後で Web ページの Browser SDK を読み込むことを推奨します。Web ページのリプレイはネイティブ Replay のサンプリング制御を受け、プライバシーレベルはデフォルトでネイティブ Bridge から提供されます。Web ページの defaultPrivacyLevel で設定することもできます。

ArkUI サポート

サポートされる収集内容には、ページ構造、テキスト、レイアウト、スクロール、サポート対象のアニメーションとネイティブコントロール、オーバーレイ、画像、描画コンポーネントが含まれます。

画像サポート範囲

Image および ImageAnimator の画像コンポーネントをサポートします。通常の Image 画像はシステムコンポーネントのスナップショットによって収集され、画像が読み込まれ、コンポーネントが表示され、画面を読み取れる状態である必要があります。Base64 画像はエンコードされたデータを直接読み取れます。

画像ソース 一般的な使用方法 サポート説明
アプリリソース画像 Image($r('app.media.icon')) コンポーネントに表示される画像画面を自動収集します。
ローカルファイル画像 Image でアプリがアクセス可能なローカルパスまたは file:// アドレスを読み込みます 画像が読み込まれて表示された後に自動収集できます。
ネットワーク画像 Image で HTTP(S) 画像アドレスを読み込みます コンポーネントに読み込み済みの画面を収集します。読み込みに失敗した場合やまだ表示されていない場合、対応する画像コンテンツはありません。
メモリ内画像 Image で PixelMap を使用します コンポーネントに表示されるメモリ内画像を自動収集します。
Drawable リソース Image で DrawableDescriptor を使用します リソースが画像コンポーネントに正常にレンダリングされた後に自動収集できます。
Base64 埋め込み画像 data:image/...;base64,... 画像のエンコードデータの読み取りをサポートします。形式とサイズの制限については後述します。

自動取得できない画像は、registerImageAsset(...) を使用して、画像コンポーネント ID または画像ソース文字列ごとにエンコードデータを手動で提供できます。

Base64 埋め込み画像および手動で補完したリソースは、PNG(image/png)、JPEG(image/jpeg)、GIF(image/gif)、WebP(image/webp)、SVG(image/svg+xml)をサポートします。1 件の画像エンコードデータは 2 MiB を超えることはできません。Base64 画像はデコード後のサイズで計算します。

描画コンポーネントのサポート

次のコンポーネントは、コンポーネントスナップショットによる画面収集をサポートします。

カテゴリ サポート対象コンポーネント
QR コード QRCode
キャンバス Canvas
図形描画 Shape、Rect、Circle、Ellipse、Line、Polygon、Polyline、Path

収集制限

適用範囲 制限説明
画像および描画コンポーネント 画像マスク設定はデフォルトで ImagePrivacy.MASK_ALL を使用し、画面内容をマスクします。描画コンポーネントも TextAndInputPrivacy.MASK_ALL の下では画面内容がマスクされます。
コンポーネントスナップショット API 12~14 では、画像または描画コンポーネントに安定した .id(...) を設定する必要があります。収集される画面はスケーリングされる可能性があり、元の解像度が保持されることは保証されません。
アニメーション画像 ImageAnimator はサンプリング画面でアニメーションの変化を記録し、フレーム単位での復元は保証されません。通常の Image 内のアニメーション画像も、元のアニメーションと完全に同期することは保証されません。
ネイティブアニメーションと視覚効果 ネイティブアニメーション、ぼかしマテリアル、テキストレイアウト、およびシステムデフォルトのトランジションの再生効果は、元の画面と異なる場合があります。
リッチテキスト RichText はテキスト、段落、基本スタイルのみを収集し、その中のスクリプト、HTML 画像、複雑な Web レイアウトは収集しません。
PatternLock 追加の転送または明示的なコンテンツ提供が必要な場合があり、プラグインのインストールだけでは完全な記録を保証できません。
Navigation トランジション API 15+ が必要です。カスタムトランジションには追加の転送が必要で、updateNavigationTransition(...) と finishNavigationTransition(...) を使用して進行状況と終了状態を転送できます。

詳細設定

ページの手動導入

import { FTSessionReplay } from '@guancecloud/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))
  }
}

注意:プラグインによってルートノードが自動登録されていない ArkUI ページは、上記の例に従って手動で導入できます。ページの表示後に Replay を開始する場合は、現在のページを登録するために registerRoot(...) を再度呼び出す必要があります。子コンポーネントがタッチイベントをインターセプトする場合は、recordTouchEvent(event) を介して転送する必要があります。タッチ位置を表示する場合は、TouchPrivacy.SHOW を有効にしてください。

コードと設定リファレンス

フィードバック

このページは役に立ちましたか?