WebView 데이터 모니터링¶
이 문서는 Cocos Creator Android/iOS 네이티브 빌드에서 WebView 컴포넌트를 통해 로드되는 Web 페이지에 적용됩니다. Web Mobile / Web Desktop 빌드는 Web 연동을 참고하세요.
App 측 설정¶
먼저 SDK 초기화와 RUM 설정을 완료하고, WebView 페이지를 로드하기 전에 RUM을 초기화합니다.
독립 실행 모드에서는 기존 guanceSdk.start() 설정에 WebView 파라미터를 지정하며, 앱 생명주기 동안 한 번만 초기화합니다:
guanceSdk.start({
sdk: {
datakitUrl: 'https://your-datakit.example.com',
allowWebViewHost: ['example.com'],
},
rum: {
androidAppId: 'android-rum-app-id',
iosAppId: 'ios-rum-app-id',
enableTraceWebView: true,
},
// WebView 페이지 로그를 수집해야 할 때 설정합니다.
logger: {
enableWebViewLog: true,
},
});
rum.enableTraceWebView는 WebView RUM을 제어하며 기본값은true입니다.false로 설정하면 WebView RUM만 비활성화되고, 이미 활성화된 WebView 로그에는 영향을 주지 않습니다.sdk.allowWebViewHost는 WebView RUM과 로그의 Bridge host 범위를 함께 제어합니다.null은 모든 host를 허용하고, 빈 배열[]은 모든 host를 금지합니다. 설정하지 않으면 네이티브 SDK의 기본 동작을 유지합니다. 설정 위치와 매칭 규칙은 WebView host 설정을 참고하세요.logger.enableWebViewLog는 WebView 로그를 제어하며 기본값은false입니다. 페이지에서 Browser Logs SDK도 초기화해야 하며, 자세한 내용은 WebView 로그를 참고하세요.
이 파라미터는 Android/iOS 네이티브 빌드의 WebView에 적용되며, Web Mobile / Web Desktop의 Browser SDK 설정으로 매핑되지 않습니다. Cocos SDK를 업데이트한 후에는 설치 프로그램을 다시 실행하고 네이티브 프로젝트를 빌드하여 TypeScript 타입, Bridge 및 관련 네이티브 종속성을 일치시켜야 합니다.
네이티브 호스트 Hybrid 시나리오에서는 호스트가 SDK, RUM, Log 초기화를 수행하고 Cocos는 attach()로 연동하므로, 위의 start() 예시로 중복 초기화하지 않습니다. 호스트 측 설정은 Android WebView 모니터링과 iOS WebView 데이터 모니터링을, Cocos 연동 방식은 네이티브와 Cocos 혼합 개발을 참고하세요.
Android Plugin 설정¶
Cocos 빌드 확장은 ft-plugin을 자동으로 적용하지 않으므로, WebView Bridge 자동 주입을 위해서는 다음 설정을 완료해야 합니다:
- 생성된 Android 네이티브 프로젝트에서 Android Plugin 연동에 따라 Maven 저장소와 플러그인 종속성을 추가하고, Android Gradle Plugin(AGP) 버전에 따라
ft-plugin또는ft-plugin-legacy를 선택합니다. -
앱 메인 모듈의
build.gradle(일반적으로app/build.gradle)에서 플러그인을 적용하고,FTExt에 사용자 정의 WebView 클래스 인식을 추가합니다. 예를 들어org.cocos2dx.lib.Cocos2dxWebView를 사용하는 프로젝트의 설정은 다음과 같습니다:프로젝트에 이미 플러그인이 적용되어 있다면
apply plugin을 중복 추가할 필요가 없습니다.knownWebViewClasses를 기존FTExt에 병합하고 다른 설정은 유지하며, 기존 클래스 목록이 있으면 위 클래스 이름을 추가합니다. 프로젝트에서 다른 사용자 정의 WebView 클래스를 사용하는 경우 실제 사용하는 전체 클래스 이름을 입력해야 합니다. -
Gradle 컴파일, 패키징 및 앱 설치를 다시 실행하여 계측 설정이 적용되도록 합니다. Cocos Creator가 Android 네이티브 프로젝트를 다시 생성한 후에는 Plugin과
knownWebViewClasses설정이 그대로 유지되는지 확인합니다.
사용자 정의 WebView 인식
ft-plugin이 연동되었다고 해서 Cocos 사용자 정의 WebView가 인식되는 것은 아닙니다. ft-plugin 1.3.9와 org.cocos2dx.lib.Cocos2dxWebView를 사용하는 경우 위 클래스 인식 설정을 추가해야 합니다. 데이터가 수신되지 않으면 사용자 정의 WebView 자동 수집 문제 해결에 따라 플러그인 로그를 확인할 수 있습니다.
Web 페이지 초기화¶
App 측 설정을 완료한 후 WebView에서 로드되는 페이지 내에 Web RUM SDK를 연동하고 초기화합니다. 자세한 내용은 페이지 초기화를 참고하세요. 이미 Web SDK 초기화 설정이 있는 경우 기존 설정을 재사용하고 초기화는 한 번만 유지합니다.
WebView 데이터 검증에 따라 수집 여부를 확인합니다. App에서 페이지를 열고 방문, 클릭 또는 네트워크 요청을 트리거한 뒤, 해당 Android/iOS App 애플리케이션에서 WebView RUM 데이터가 수신되는지 확인합니다.