HarmonyOS セッションリプレイ(実験的)¶
HarmonyOS セッションリプレイは、ArkUI のページ構造、視覚的な変化、ユーザー操作を記録してページを再構築し、RUM の Session、View、Error を関連付けます。ArkWeb ページでは、さらに Browser SDK を導入する必要があります。この機能は独立した ft_session_replay パッケージによって提供されます。
現在は Alpha プレリリースバージョン 0.1.0-alpha04 であり、機能と API は変更される可能性があります。
前提条件¶
- SDK の RUM 設定のセットアップと初期化を完了し、View のモニタリング収集を有効にしてください。
- HarmonyOS セッションリプレイには
ft_sdk0.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 パッケージをインストールします。
ローカル HAR を使用する場合、モジュールの oh-package.json5 で ft_sdk.har、ft_session_replay.har のスコープ付き依存関係を宣言し、プロジェクトルートで overrides を使用して Replay が依存するコアパッケージを同じローカル HAR に指定します。設定方法は拡張パッケージのローカル導入と同じです。
Hvigor プラグインの導入¶
プロジェクトレベルの hvigor/hvigor-config.json5 にビルドプラグインを追加します。
アプリケーション 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 のリモートサンプリング設定によって上書きされません。
RUM との関連付け¶
リプレイフレームの保存に成功すると、関連付けられたネイティブ View、Action、Resource、LongTask、Error に session_has_replay=true を付与できます。Session の集約データでは has_replay を使用して、現在のセッションにリプレイデータが関連付けられているかどうかを示します。リプレイマーカーは SDK が実際の記録結果に基づいて自動的に設定します。Replay の初期化が完了しただけでは、利用可能なリプレイデータが存在することを意味しません。
プライバシー設定¶
SDK では、FTSessionReplayConfig を使用してグローバルなマスクレベルを設定できます。設定項目は次のとおりです。
- 画像マスクレベル
- テキストと入力のマスクレベル
- タッチのマスクレベル
注意:
- 以下の設定は
init()の前に設定する必要があり、セッションリプレイのグローバル収集に適用されます。 - RUM の
DataModifier、LineDataModifierはテレメトリフィールドのマスキングに使用されます。リプレイ画面では本節のプライバシー設定を使用します。
以下の例の replayConfig と列挙型は、コード呼び出しの定義をそのまま使用します。
画像マスク¶
setImagePrivacy(ImagePrivacy) を使用して画像のマスクレベルを設定します。
テキストと入力のマスク¶
setTextAndInputPrivacy(TextAndInputPrivacy) を使用してテキストと入力のマスクレベルを設定します。
// 通常のテキストを保持し、パスワードなどの機密入力をマスクします。
replayConfig.setTextAndInputPrivacy(TextAndInputPrivacy.MASK_SENSITIVE_INPUTS);
ユーザーが明示的に表示したパスワードの収集を許可する場合、ページは showPassword を onSecurityStateChange と同期する状態にバインドする必要があります。setCaptureVisiblePassword(true) を有効にするだけでは、テキストプライバシーポリシーは上書きされません。
タッチのマスク¶
setTouchPrivacy(TouchPrivacy) を使用して、タッチ位置をマスクするかどうかを設定します。
Webview セッションリプレイ¶
ArkWeb では、次の条件をすべて満たす必要があります。
- ネイティブ RUM で
setEnableTraceWebView(true)を有効にし、WebView データモニタリングに従ってFTWebViewHandlerを導入します。 - ネイティブ Replay が初期化および開始済みで、Hvigor プラグインを介して Web コンポーネントと controller が関連付けられていること。
- 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を有効にしてください。