콘텐츠로 이동

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 자동 주입을 위해서는 다음 설정을 완료해야 합니다:

  1. 생성된 Android 네이티브 프로젝트에서 Android Plugin 연동에 따라 Maven 저장소와 플러그인 종속성을 추가하고, Android Gradle Plugin(AGP) 버전에 따라 ft-plugin 또는 ft-plugin-legacy를 선택합니다.
  2. 앱 메인 모듈의 build.gradle(일반적으로 app/build.gradle)에서 플러그인을 적용하고, FTExt에 사용자 정의 WebView 클래스 인식을 추가합니다. 예를 들어 org.cocos2dx.lib.Cocos2dxWebView를 사용하는 프로젝트의 설정은 다음과 같습니다:

    apply plugin: 'ft-plugin'
    
    FTExt {
        knownWebViewClasses = ['org.cocos2dx.lib.Cocos2dxWebView']
    }
    

    프로젝트에 이미 플러그인이 적용되어 있다면 apply plugin을 중복 추가할 필요가 없습니다. knownWebViewClasses를 기존 FTExt에 병합하고 다른 설정은 유지하며, 기존 클래스 목록이 있으면 위 클래스 이름을 추가합니다. 프로젝트에서 다른 사용자 정의 WebView 클래스를 사용하는 경우 실제 사용하는 전체 클래스 이름을 입력해야 합니다.

  3. 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 데이터가 수신되는지 확인합니다.

문서 평가

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