WebView2 モニタリング¶
Windows RUM SDK は、WPF、WinForms、WinUI 3 の Microsoft Edge WebView2 コントロールに関連付けることで、ページ内の View、Action、Resource、Error をホストの Windows Session と View に関連付けることができます。
WebView2 データモニタリング¶
前提条件¶
- アプリが Windows SDK 統合 を完了していること。
- プロジェクトに Microsoft Edge WebView2 がインストールされ、正常に初期化できること。
- 対象コントロールが
CoreWebView2とEnsureCoreWebView2Async()を公開していること。
自動検出¶
EnableWebView はデフォルトで true です。デスクトップ自動収集を有効にすると、SDK はサポート対象のコントロールツリーから WebView2 を検出します:
GuanceSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
EnableWebView = true
});
動的に作成される、ライフサイクルが独立している、または連携タイミングを明示的に制御したい WebView2 では、明示的な関連付けを推奨します。
明示的な関連付け¶
拡張メソッドを使用することもできます:
同じコントロールを繰り返し関連付けても、重複して注入されることはありません。コントロールが不要になった場合は、明示的に切り離すことができます:
コントロールで Disposed または Unloaded が発生した場合、SDK は関連付けも自動的にクリーンアップします。
収集内容¶
| データ種別 | 収集内容 |
|---|---|
| View | 初期ナビゲーション、フルナビゲーション、History API のルート変更、ページタイトルと最終 URL |
| Action | ページクリックとサポート対象のユーザー操作 |
| Resource | fetch、XMLHttpRequest および Performance Resource エントリ |
| Error | JavaScript Error と未処理の Promise rejection |
SDK は、関連付けられた各コントロールに独立したブリッジトークンを注入し、ホスト側で app_id、Session、View、SDK 識別情報などの予約フィールドを上書きします。ページスクリプトはブリッジメッセージを介してホスト関連フィールドを変更することはできません。
ホスト View との関係¶
WebView2 のページデータはホストの Windows Session を引き継ぎ、現在のホスト View に関連付けられます。ページナビゲーションはページ View データを生成しますが、独立した Windows SDK クライアントは作成されません。
1 つのウィンドウに複数の WebView2 が含まれる場合は、各コントロールを個別に関連付け、コントロールのライフサイクルを安定に保ってください。
Log と Trace の境界¶
- Windows ホストは
GuanceSdk.AddLog()を使用して Log を書き込み、現在のホスト RUM コンテキストに基づいて関連付けを完了できます。 - WebView2 ブリッジは現在、ページの
console出力を Windows Log に自動変換しません。 - Windows
HttpClientの Trace 設定はホストが開始したリクエストにのみ適用され、renderer 内のfetchやXMLHttpRequestに Header を注入しません。 - ページ側で独立した Log または Trace 機能が必要な場合は、ページで採用している Browser SDK の設定を使用し、同じ Resource を重複して収集しないようにしてください。
プライバシー境界¶
- URL のクエリパラメータには、ホストの Resource と同じマスキング設定が適用されます。
- ページメッセージ内の URL フィールドは、RUM キューに入る前に再度処理されます。
- 認証 Header、Cookie、Token 類のパラメータはデフォルトでマスキングされます。
- パスワード、Token、ファイルの絶対パス、ユーザー入力の原文をページのカスタムフィールドで送信しないでください。
詳細な設定については、プライバシーと権限の説明 を参照してください。
実験的 Session Replay¶
Windows Session Replay はデフォルトでオフです。ホストは同じバージョンの Guance.Windows.SessionReplay をインストールし、GuanceConfig.SessionReplay.Enabled = true を設定した上で、明示的に有効化して検証する必要があります。SDK は Android WebView と互換性のある FTWebViewJavascriptBridge を注入します。ホストが Replay を有効にし、かつコンポーネントが実際に利用可能な場合のみ、getCapabilities() は records を返します。ページの Browser collector が生成した rrweb record は、ホストによって Windows Session と WebView View に関連付けられ、ホストの Replay キューを介してアップロードされます。コンポーネントがない場合でも、通常の RUM Bridge は引き続き使用できます。
ページで Browser RUM を読み込み、window.DATAFLUX_RUM が利用可能になった後に最小限の初期化を実行する必要があります。最初に init() を呼び出し、その後 Session Replay を開始します:
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
// Bridge モードでも受信アドレスの検証は行われますが、RUM データは
// FTWebViewJavascriptBridge を介して送信されるため、このアドレスへのリクエストは発生しません。
datakitOrigin: "http://127.0.0.1",
});
const capabilities = JSON.parse(
window.FTWebViewJavascriptBridge?.getCapabilities?.() || "[]",
);
if (window.DATAFLUX_RUM && capabilities.includes("records")) {
window.DATAFLUX_RUM.startSessionReplayRecording();
}
ここでの datakitOrigin は Browser RUM の初期化検証にのみ使用されます。ローカルページで無効な Origin が生成されないよう、Bridge 検証用のプレースホルダ値として http://127.0.0.1 を固定で使用します。実際のアプリ ID、送信先アドレス、Session、サンプリング、プライバシーポリシーはすべてホストの Windows SDK が提供するため、ページで重複して設定しないでください。
Replay のサンプリングとプライバシーポリシーはホストの設定によって決まり、ページ側で上書きすることはできません。この機能は依然として実験的であり、安定した互換性の保証には含まれません。導入方法と検証方法については、RUM 設定 と Electron ネイティブ Bridge を参照してください。
制限¶
- WebView2 renderer 内の Long Task は、現在のブリッジの収集対象外です。ホスト UI スレッドのブロッキングは引き続き Windows SDK が収集します。
- クロスオリジン iframe は、ブラウザの同一オリジンポリシーとスクリプト注入の境界によって制限されます。
- WebView2 Session Replay は実験的な機能です。クロスオリジン Frame、Canvas、カスタムレンダリングコンテンツ、プレイヤーとの互換性は、対象アプリケーションで個別に検証する必要があります。
よくあるトラブルシューティングの入口¶
検証¶
- コントロールを関連付け、ページナビゲーションを 1 回完了します。
- ページ内のボタンをクリックします。
fetchまたはXMLHttpRequestを 1 回実行します。- 再現可能な JavaScript Error を発生させます。
- コンソールで、ページの View、Action、Resource、Error がホスト Session に関連付けられていることを確認します。
初期化に失敗した場合は、GuanceSdk.AddDiagnosticListener() を使用して、WebView2 initialization failed、did not succeed、コントロールタイプの不一致などの診断情報を確認してください。