WebView2 Monitoring¶

The Windows RUM SDK can associate Microsoft Edge WebView2 controls in WPF, WinForms, and WinUI 3, and correlate page-level View, Action, Resource, and Error data with the host Windows Session and View.

WebView2 Data Monitoring¶

Prerequisites¶

• The app has completed Windows SDK integration.
• The project has Microsoft Edge WebView2 installed and can initialize it successfully.
• The target control exposes CoreWebView2 and EnsureCoreWebView2Async().

Automatic Discovery¶

EnableWebView defaults to true. With desktop automatic instrumentation enabled, the SDK discovers WebView2 controls in the supported control tree:

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

For WebView2 controls that are created dynamically, have an independent lifecycle, or require explicit control over when to start instrumentation, explicit association is recommended.

Explicit Association¶

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

You can also use the extension method:

webView.UseGuanceRumWebView();

Associating the same control again does not cause duplicate injection. When the control is no longer used, you can detach it proactively:

GuanceSdk.DetachWebView(webView);

When the control fires the Disposed or Unloaded events, the SDK also cleans up the association automatically.

Collected Data¶

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

Relationship with the Host View¶

WebView2 page data inherits the host Windows Session and is associated with the current host View. Page navigations generate page View data but do not create an independent Windows SDK client.

If a window contains multiple WebView2 controls, associate each control separately and maintain a stable control lifecycle.

Log and Trace Boundaries¶

• The Windows host can use GuanceSdk.AddLog() to write logs and have them correlated according to the current host RUM context.
• The WebView2 bridge does not currently convert page console output into Windows logs automatically.
• The Windows HttpClient trace configuration applies only to requests initiated by the host and does not inject headers into fetch or XMLHttpRequest inside the renderer.
• If page-side log or trace capabilities are needed, use the Browser SDK configuration used on that page and avoid collecting the same Resource twice.

Privacy Boundaries¶

• URL query parameters use the same redaction 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 redacted 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. However, you can explicitly enable WebView2 Session Replay for validation after setting GuanceConfig.SessionReplay.Enabled = true on the host. The SDK injects an FTWebViewJavascriptBridge compatible with Android WebView. When the native configuration allows Replay, getCapabilities() returns records; the rrweb records produced by the Browser collector on the page are associated with the Windows Session and WebView View by the host, then uploaded through the native Replay queue.

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

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    // Bridge mode still validates the intake address, but RUM data is sent
    // through FTWebViewJavascriptBridge and this address is not requested.
    datakitOrigin: "http://127.0.0.1",
  });

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

datakitOrigin here is used only for Browser RUM initialization validation. Always use http://127.0.0.1 as the bridge validation placeholder to avoid local pages producing an invalid Origin. The actual app ID, report endpoint, Session, sampling, and privacy policy are all provided by the host Windows SDK. Do not configure them again on the page.

Replay sampling and privacy policy are determined by the host configuration and cannot be overridden by the page. This capability is still experimental and is not part of a stable compatibility commitment. For integration and validation, see RUM Configuration and Electron Native Bridge.

Limitations¶

• Long Tasks in the WebView2 renderer are outside the collection scope of the current bridge. Host UI thread stalls are still collected by the Windows SDK.
• Cross-origin iframes are subject to browser same-origin policy and script injection boundaries.
• WebView2 Session Replay is an experimental capability. Compatibility with cross-origin frames, Canvas, custom-rendered content, and players must be validated separately in the target application.

Common Troubleshooting¶

Verification¶

1. Attach the control and complete one page navigation.
2. Click a button on the page.
3. Make a fetch or XMLHttpRequest call.
4. Trigger a controlled JavaScript Error.
5. In the console, confirm that the 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 mismatch.