콘텐츠로 이동

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, 또는 연결 시점을 명시적으로 제어하려는 경우 명시적 연결을 권장합니다.

명시적 연결

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

확장 메서드를 사용할 수도 있습니다.

webView.UseGuanceRumWebView();

동일한 컨트롤을 중복 연결해도 중복 주입되지 않습니다. 컨트롤이 더 이상 필요하지 않으면 직접 분리할 수 있습니다.

GuanceSdk.DetachWebView(webView);

컨트롤에서 Disposed 또는 Unloaded가 발생하면 SDK도 연결을 자동으로 정리합니다.

수집 항목

데이터 유형 수집 항목
View 초기 탐색, 전체 탐색, History API 라우트 변경, 페이지 제목 및 최종 URL
Action 페이지 클릭 및 지원되는 사용자 상호작용
Resource fetch, XMLHttpRequest 및 Performance Resource 항목
Error JavaScript Error 및 처리되지 않은 Promise rejection

SDK는 연결된 각 컨트롤에 독립적인 브리지 Token을 주입하고, 호스트 측에서 app_id, Session, View, SDK 식별 정보 등 예약 필드를 덮어씁니다. 페이지 스크립트는 브리지 메시지를 통해 호스트 연결 필드를 수정할 수 없습니다.

호스트 View와의 관계

WebView2 페이지 데이터는 호스트 Windows Session을 그대로 사용하며 현재 호스트 View에 연결됩니다. 페이지 탐색 시 페이지 View 데이터가 생성되지만 독립적인 Windows SDK 클라이언트는 생성되지 않습니다.

하나의 창에 여러 개의 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는 기본적으로 비활성화되어 있지만, WebView2는 호스트에서 GuanceConfig.SessionReplay.Enabled = true로 설정한 후 명시적으로 활성화하여 검증할 수 있습니다. SDK는 Android WebView와 호환되는 FTWebViewJavascriptBridge를 주입합니다. 네이티브 구성에서 Replay를 허용하면 getCapabilities()가 records를 반환하며, 페이지 Browser collector가 생성한 rrweb record는 호스트에 의해 Windows Session 및 WebView View에 연결된 후 네이티브 Replay 큐를 통해 업로드됩니다.

페이지에서 Browser RUM을 로드하고 window.DATAFLUX_RUM을 사용할 수 있게 된 후 최소 초기화를 실행해야 합니다. 먼저 init()을 호출한 다음 Session Replay를 시작하세요.

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    // Bridge 모드에서는 수신 주소를 여전히 검증하지만, RUM 데이터는
    // FTWebViewJavascriptBridge를 통해 전송되므로 해당 주소를 요청하지 않습니다.
    datakitOrigin: "http://127.0.0.1",
  });

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

여기서 datakitOrigin은 Browser RUM 초기화 검증에만 사용됩니다. http://127.0.0.1을 Bridge 검증용 플레이스홀더 값으로 고정 사용하여 로컬 페이지에서 잘못된 Origin이 생성되지 않도록 합니다. 실제 애플리케이션 ID, 전송 주소, Session, 샘플링 및 개인정보 보호 정책은 모두 호스트 Windows SDK에서 제공하므로 페이지에서 중복 구성하지 마세요.

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에 연결되었는지 확인합니다.

초기화에 실패하면 GuanceSdk.AddDiagnosticListener()를 사용하여 WebView2 initialization failed, did not succeed 또는 컨트롤 유형 불일치 등의 진단 정보를 확인하세요.

문서 평가

이 페이지가 도움이 되었나요?