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, 또는 연동 시점을 명시적으로 제어하려는 경우에는 명시적 연결을 권장합니다.
명시적 연결¶
확장 메서드를 사용할 수도 있습니다.
동일한 컨트롤을 반복 연결해도 중복 주입되지 않습니다. 컨트롤이 더 이상 필요하지 않으면 직접 분리할 수 있습니다.
컨트롤에서 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
HttpClientTrace 구성은 호스트가 시작한 요청에만 적용되며 renderer 내부의fetch또는XMLHttpRequest에 Header를 주입하지 않습니다. - 페이지 측에서 독립적인 Log 또는 Trace 기능이 필요한 경우 페이지에서 사용하는 Browser SDK 구성을 사용하고 동일한 Resource를 중복 수집하지 않도록 해야 합니다.
개인정보 보호 경계¶
- URL 쿼리 매개변수는 호스트 Resource와 동일한 마스킹 구성을 사용합니다.
- 페이지 메시지의 URL 필드는 RUM 큐에 들어가기 전에 다시 처리됩니다.
- 인증 Header, Cookie, Token 유형 매개변수는 기본적으로 마스킹됩니다.
- 페이지 사용자 정의 필드에 비밀번호, Token, 파일 절대 경로 또는 사용자 입력 원문을 전달하지 마세요.
자세한 구성은 개인정보 및 권한 설명을 참조하세요.
실험적 Session Replay¶
Windows Session Replay는 기본적으로 비활성화되어 있습니다. 호스트는 동일한 버전의 Guance.Windows.SessionReplay를 설치하고 GuanceConfig.SessionReplay.Enabled = true를 설정한 뒤 명시적으로 활성화하여 검증해야 합니다. SDK는 Android WebView와 호환되는 FTWebViewJavascriptBridge를 주입합니다. 호스트가 Replay를 활성화하고 구성 요소가 실제로 사용 가능한 경우에만 getCapabilities()가 records를 반환합니다. 페이지 Browser collector가 생성한 rrweb record는 호스트가 Windows Session 및 WebView View에 연결한 다음 호스트 Replay 큐를 통해 업로드합니다. 구성 요소가 없을 때에도 일반 RUM Bridge는 계속 사용할 수 있습니다.
페이지에서 Browser RUM을 로드하고 window.DATAFLUX_RUM을 사용할 수 있게 된 후 최소 초기화를 수행해야 합니다. 먼저 init()을 호출한 다음 Session Replay를 시작합니다.
window.DATAFLUX_RUM &&
window.DATAFLUX_RUM.init({
// Bridge 모드에서는 수신 주소를 계속 검증하지만 RUM 데이터는
// FTWebViewJavascriptBridge를 통해 전송되므로 해당 주소를 요청하지 않습니다.
datakitOrigin: "http://127.0.0.1",
});
const capabilities = JSON.parse(
window.FTWebViewJavascriptBridge?.getCapabilities?.() || "[]",
);
if (window.DATAFLUX_RUM && capabilities.includes("records")) {
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은 브라우저 동일 출처(same-origin) 정책 및 스크립트 주입 경계의 제한을 받습니다.
- WebView2 Session Replay는 실험적 기능입니다. 크로스 도메인 Frame, Canvas, 사용자 정의 렌더링 콘텐츠 및 플레이어 호환성은 대상 애플리케이션에서 별도로 검증해야 합니다.
일반적인 문제 해결 방법¶
검증¶
- 컨트롤을 연결하고 페이지 내비게이션을 한 번 완료합니다.
- 페이지에서 버튼을 클릭합니다.
fetch또는XMLHttpRequest를 한 번 실행합니다.- 제어 가능한 JavaScript Error를 하나 발생시킵니다.
- 콘솔에서 페이지 View, Action, Resource, Error가 호스트 Session에 연결되었는지 확인합니다.
초기화에 실패하면 GuanceSdk.AddDiagnosticListener()를 사용하여 WebView2 initialization failed, did not succeed 또는 컨트롤 유형 불일치 등의 진단을 확인합니다.