Skip to content

WebView Data Monitoring

This document applies to web pages loaded through the WebView component in Cocos Creator Android/iOS native builds. For Web Mobile / Web Desktop builds, refer to Web Integration.

App-Side Configuration

First complete SDK Initialization and RUM Configuration, and initialize RUM before loading the WebView page.

In standalone mode, set the WebView parameters in the existing truewatchSdk.start() configuration. Initialize only once during the application lifecycle:

truewatchSdk.start({
  sdk: {
    datakitUrl: 'https://your-datakit.example.com',
    allowWebViewHost: ['example.com'],
  },
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    enableTraceWebView: true,
  },
  // Configure this when WebView page logs need to be collected.
  logger: {
    enableWebViewLog: true,
  },
});
  • rum.enableTraceWebView controls WebView RUM and defaults to true. Setting it to false disables only WebView RUM and does not affect WebView logs that are already enabled.
  • sdk.allowWebViewHost controls the Bridge host scope for both WebView RUM and logs. null allows all hosts, and an empty array [] blocks all hosts; when not set, the native SDK default behavior is retained. For the configuration location and matching rules, see WebView Host Configuration.
  • logger.enableWebViewLog controls WebView logs and defaults to false. The page must also initialize the Browser Logs SDK. For details, see WebView Logs.

These parameters apply to WebView in Android/iOS native builds and are not mapped to Browser SDK configurations for Web Mobile / Web Desktop. After updating the Cocos SDK, rerun the installer and build the native project to keep TypeScript types, the Bridge, and the accompanying native dependencies consistent.

In Hybrid scenarios with a native host, the host initializes the SDK, RUM, and Log, and Cocos integrates through attach() without using the start() example above to initialize again. For host-side configuration, see Android WebView Monitoring and iOS WebView Data Monitoring. For the Cocos integration method, see Native and Cocos Hybrid Development.

Android Plugin Configuration

The Cocos build extension does not automatically apply ft-plugin. Automatic WebView Bridge injection requires the following configuration:

  1. In the generated Android native project, add the Maven repository and plugin dependency as described in Android Plugin Integration, and choose ft-plugin or ft-plugin-legacy based on the Android Gradle Plugin (AGP) version.
  2. Apply the plugin in the app main module's build.gradle (usually app/build.gradle), and add custom WebView class recognition in FTExt. For example, a project using org.cocos2dx.lib.Cocos2dxWebView is configured as follows:

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

    If the plugin is already applied in the project, there is no need to add apply plugin again. Merge knownWebViewClasses into the existing FTExt and retain other configurations; if a class list already exists, append the above class name. If the project uses other custom WebView classes, enter the fully qualified class names actually used.

  3. Run Gradle compilation and packaging and install the app again so that the instrumentation configuration takes effect. After Cocos Creator regenerates the Android native project, verify that the Plugin and knownWebViewClasses configurations are still retained.

Custom WebView Recognition

Integrating ft-plugin does not mean that the Cocos custom WebView has been recognized. When using ft-plugin 1.3.9 and org.cocos2dx.lib.Cocos2dxWebView, you need to add the above class recognition configuration. If no data is received, check the plugin logs as described in Custom WebView Auto-Collection Troubleshooting.

Initialize the Web Page

After completing the App-side configuration, integrate and initialize the Web RUM SDK in the page loaded by the WebView. For details, see Page Initialization. If a Web SDK initialization configuration already exists, reuse the existing configuration and perform initialization only once.

Verify reporting according to WebView Data Verification: open the page in the App, trigger a page view, click, or network request, and confirm in the corresponding Android/iOS App application that WebView RUM data is received.