WebView2 Monitoring¶

The Windows RUM SDK can associate the Microsoft Edge WebView2 control within WPF, WinForms, and WinUI 3 applications, linking View, Action, Resource, and Error data from the page to the host Windows Session and View.

WebView2 Data Collection¶

Prerequisites¶

• The application has completed Windows SDK integration.
• The project has Microsoft Edge WebView2 installed and initialized normally.
• The target control exposes CoreWebView2 and EnsureCoreWebView2Async().

Auto-Discovery¶

EnableWebView defaults to true. When desktop automatic instrumentation is enabled, the SDK discovers WebView2 controls within the supported control tree:

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

For dynamically created WebView2 controls, those with independent lifecycles, or cases where you want explicit control over the instrumentation timing, explicit attachment is recommended.

Explicit Attachment¶

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

Alternatively, you can use the extension method:

webView.UseGuanceRumWebView();

Re-attaching the same control does not cause duplicate injection. When the control is no longer needed, you can detach it explicitly:

GuanceSdk.DetachWebView(webView);

When the control triggers Disposed or Unloaded, the SDK automatically cleans up the association.

Collected Data¶

The SDK injects a unique bridge token for each attached control. The host side overrides reserved fields such as app_id, Session, View, and SDK identity. Page scripts cannot modify host-associated fields through bridge messages.

Relationship with Host View¶

WebView2 page data inherits the host Windows Session and is associated with the current host View. Page navigation generates page View data but does not create a separate Windows SDK client.

If a window contains multiple WebView2 controls, attach each control separately and maintain stable control lifetimes.

Log and Trace Boundaries¶

• The Windows host can write logs using GuanceSdk.AddLog() and associate them with the host RUM context.
• The WebView2 bridge does not automatically convert page console output into Windows Logs.
• Windows HttpClient Trace configuration only applies to requests initiated by the host; it does not inject headers into fetch or XMLHttpRequest within the renderer.
• If the page requires independent Log or Trace capabilities, configure the Browser SDK used by the page and avoid duplicate collection of the same Resource.

Privacy Boundaries¶

• URL query parameters use the same sanitization configuration as host Resources.
• URL fields in page messages are processed again before entering the RUM queue.
• Authentication headers, cookies, and token-like parameters are sanitized by default.
• Do not pass passwords, tokens, absolute file paths, or raw user input through page custom fields.

For detailed configuration, see Privacy and Permissions.

Experimental Session Replay¶

Windows Session Replay is disabled by default. WebView2 can be explicitly enabled for validation after the host sets GuanceConfig.SessionReplay.Enabled = true. The SDK injects a FTWebViewJavascriptBridge compatible with Android WebView. When the native configuration allows Replay, getCapabilities() returns records, and rrweb records generated by the page Browser collector are associated with the Windows Session and WebView View by the host, then uploaded via the native Replay queue.

The page must load the Browser RUM and perform minimal initialization after window.DATAFLUX_RUM is available. Call init() first, then start Session Replay:

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    // Bridge mode still validates the datakit origin, but RUM data is sent
    // via FTWebViewJavascriptBridge, not to this address.
    datakitOrigin: "http://127.0.0.1",
  });

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.startSessionReplayRecording();

The datakitOrigin here is only used for Browser RUM initialization validation. Use http://127.0.0.1 as a fixed Bridge validation placeholder to avoid invalid origins for local pages. The actual application ID, upload address, Session, sampling, and privacy policies are all provided by the host Windows SDK; do not repeat these configurations in the page.

Replay sampling and privacy policies are determined by the host configuration; the page cannot override them. This capability is still experimental and is not part of the stable compatibility guarantee. For integration and validation, refer to RUM Configuration and Electron Native Bridge.

Limitations¶

• Long Tasks within the WebView2 renderer are not currently collected by the bridge; host UI thread stalls are still collected by the Windows SDK.
• Cross-origin iframes are subject to browser same-origin and script injection boundaries.
• WebView2 Session Replay is experimental; compatibility with cross-origin frames, Canvas, custom rendering content, and media players must be validated in the target application.

Common Troubleshooting Entry Points¶

Verification¶

1. Attach the control and complete a page navigation.
2. Click a button on the page.
3. Make a fetch or XMLHttpRequest.
4. Trigger a controllable JavaScript Error.
5. Confirm in the console that page View, Action, Resource, and Error are associated with the host Session.

If initialization fails, use GuanceSdk.AddDiagnosticListener() to check for diagnostics such as WebView2 initialization failed, did not succeed, or control type mismatches.