Skip to content

WebView2 Monitoring

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

WebView2 Data Monitoring

Prerequisites

  • The application has completed Windows SDK integration.
  • The project has Microsoft Edge WebView2 installed and able to initialize properly.
  • The target control exposes CoreWebView2 and EnsureCoreWebView2Async().

Automatic Discovery

EnableWebView is true by default. After desktop automatic instrumentation is enabled, the SDK discovers WebView2 controls in the supported control tree:

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

For WebView2 controls that are dynamically created, have an independent lifecycle, or where you want to explicitly control when they are integrated, 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 repeatedly does not result in duplicate injection. When the control is no longer needed, you can explicitly detach it:

GuanceSdk.DetachWebView(webView);

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

Data Collected

Data Type Collected Data
View Initial navigation, full navigations, History API route changes, page title, and final URL
Action Page clicks and supported user interactions
Resource fetch, XMLHttpRequest, and Performance Resource entries
Error JavaScript errors and unhandled Promise rejections

The SDK injects an independent bridge token for each associated control, and 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 the Host View

WebView2 page data follows the host Windows Session and is associated with the current host View. Page navigation generates page View data but does not create an independent Windows SDK client.

If a window contains multiple WebView2 controls, associate each control separately and keep the control lifecycles stable.

Log and Trace Boundaries

  • The Windows host can write Log data using GuanceSdk.AddLog() and associate it according to the current host RUM context.
  • The WebView2 bridge currently does not automatically convert page console output into Windows Logs.
  • The 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 needs independent Log or Trace capabilities, use the Browser SDK configuration adopted by the page, and avoid duplicate collection of the same Resource.

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 custom page fields.

For detailed configuration, see Privacy and Permissions.

Experimental Session Replay

Windows Session Replay is disabled by default. The host must install the same version of Guance.Windows.SessionReplay and explicitly enable it for validation by setting GuanceConfig.SessionReplay.Enabled = true. The SDK injects FTWebViewJavascriptBridge, which is compatible with Android WebView; only when the host has enabled Replay and the component is actually available does getCapabilities() return records. The rrweb records produced by the page Browser collector are associated by the host with the Windows Session and WebView View, and then uploaded through the host Replay queue. When the component is missing, the regular RUM Bridge remains available.

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

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

const capabilities = JSON.parse(
  window.FTWebViewJavascriptBridge?.getCapabilities?.() || "[]",
);
if (window.DATAFLUX_RUM && capabilities.includes("records")) {
  window.DATAFLUX_RUM.startSessionReplayRecording();
}

Here, datakitOrigin is used only for Browser RUM initialization validation. It is fixed to http://127.0.0.1 as the Bridge validation placeholder value to avoid invalid Origins in local pages. The actual application ID, reporting URL, Session, sampling, and privacy policy are all provided by the host Windows SDK and must not be configured again on the page.

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

Limitations

  • Long Tasks inside the WebView2 renderer are outside the scope of current bridge collection; host UI thread jank is still collected by the Windows SDK.
  • Cross-origin iframes are constrained by browser same-origin 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 Entry Points

Verification

  1. Associate a control and complete one page navigation.
  2. Click a button in the page.
  3. Make a fetch or XMLHttpRequest request.
  4. Trigger a controllable 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 diagnostics such as WebView2 initialization failed, did not succeed, or mismatched control types.

Feedback

Is this page helpful?