콘텐츠로 이동

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는 연결된 각 컨트롤에 독립적인 브리징 토큰을 주입하며, 호스트 측에서 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 초기화 확인 용도로만 사용됩니다. 로컬 페이지에서 유효하지 않은 Origin이 생성되는 것을 방지하기 위해 http://127.0.0.1을 Bridge 확인용 플레이스홀더 값으로 고정 사용합니다. 실제 애플리케이션 ID, 업로드 주소, Session, 샘플링 및 개인정보 정책은 모두 호스트 Windows SDK에서 제공되므로 페이지에서 중복해서 구성하지 마세요.

Replay의 샘플링 및 개인정보 정책은 호스트 구성에 의해 결정되며 페이지에서 자체적으로 재정의할 수 없습니다. 이 기능은 여전히 실험적이며 안정적인 호환성을 보장하지 않습니다. 연결 및 검증 방법은 RUM 구성 및 Electron 네이티브 Bridge를 참조하세요.

제한 사항

  • WebView2 renderer 내의 Long Task는 현재 브리지 수집 범위에 속하지 않습니다. 호스트 UI 스레드 지연은 여전히 Windows SDK에서 수집합니다.
  • 교차 출처 iframe은 브라우저 동일 출처 정책 및 스크립트 주입 경계의 제한을 받습니다.
  • WebView2 Session Replay는 실험적 기능입니다. 교차 출처 프레임, Canvas, 사용자 정의 렌더링 콘텐츠 및 플레이어 호환성은 대상 애플리케이션에서 개별적으로 검증해야 합니다.

일반적인 문제 해결 진입점

검증

  1. 컨트롤을 연결하고 페이지 탐색을 한 번 완료합니다.
  2. 페이지에서 버튼을 클릭합니다.
  3. fetch 또는 XMLHttpRequest를 한 번 실행합니다.
  4. 제어 가능한 JavaScript Error를 트리거합니다.
  5. 콘솔에서 페이지 View, Action, Resource 및 Error가 호스트 Session에 연결되었는지 확인합니다.

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

문서 평가

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