WebView2¶

Windows RUM SDK 可以关联 WPF、WinForms 和 WinUI 3 中的 Microsoft Edge WebView2 控件，将页面内的 View、Action、Resource 和 Error 关联到宿主 Windows Session 和 View。

前置条件¶

• 应用已完成 Windows SDK 接入；
• 项目已安装并能正常初始化 Microsoft Edge WebView2；
• 目标控件公开 CoreWebView2 和 EnsureCoreWebView2Async()。

自动发现¶

EnableWebView 默认为 true。开启桌面自动采集后，SDK 会在支持的控件树中发现 WebView2：

RumSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
    EnableWebView = true
});

对于动态创建、生命周期独立或希望明确控制接入时机的 WebView2，建议显式关联。

显式关联¶

await webView.EnsureCoreWebView2Async();
RumSdk.AttachWebView(webView);

也可以使用扩展方法：

webView.UseGuanceRumWebView();

同一个控件重复关联不会重复注入。控件不再使用时可以主动分离：

RumSdk.DetachWebView(webView);

控件触发 Disposed 或 Unloaded 时，SDK 也会自动清理关联。

采集内容¶

SDK 为每个关联控件注入独立桥接 Token，并由宿主侧覆盖 app_id、Session、View 和 SDK 身份等保留字段。页面脚本不能通过桥接消息修改宿主关联字段。

与宿主 View 的关系¶

WebView2 页面数据沿用宿主 Windows Session，并关联到当前宿主 View。页面导航会生成页面 View 数据，但不会创建独立的 Windows SDK 客户端。

如果一个窗口包含多个 WebView2，请分别关联每个控件，并保持控件生命周期稳定。

Log 与 Trace 边界¶

• Windows 宿主可以使用 RumSdk.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 默认关闭，但 WebView2 可以在宿主 RumConfig.SessionReplay.Enabled = true 后显式开启验证。SDK 注入与 Android WebView 兼容的 FTWebViewJavascriptBridge；当原生配置允许 Replay 时，getCapabilities() 返回 records，页面 Browser collector 产生的 rrweb record 由宿主关联到 Windows Session 和 WebView View，再通过原生 Replay 队列上传。

Replay 的采样和隐私策略由宿主配置决定，页面不能自行覆盖。该能力仍为实验性，不属于稳定兼容承诺；接入与验证方式参考 RUM 配置 和 Electron 原生 Bridge。

限制¶

• WebView2 renderer 内的 Long Task 不属于当前桥接采集范围；宿主 UI 线程卡顿仍由 Windows SDK 采集。
• 跨域 iframe 受浏览器同源和脚本注入边界限制。
• WebView2 Session Replay 为实验性能力；跨域 Frame、Canvas、自定义渲染内容和播放器兼容性需要在目标应用中单独验证。

验证¶

1. 关联控件并完成一次页面导航。
2. 在页面中点击一个按钮。
3. 发起一次 fetch 或 XMLHttpRequest。
4. 触发一个可控的 JavaScript Error。
5. 在控制台确认页面 View、Action、Resource 和 Error 与宿主 Session 关联。

初始化失败时，使用 RumSdk.AddDiagnosticListener() 检查 WebView2 initialization failed、did not succeed 或控件类型不匹配等诊断。