Cocos Creator App Integration¶

Use the Cocos Creator SDK to collect RUM, Log, Trace, and Session Replay data from Android and iOS native games.

Reading Path¶

• First-time integration: Start with Quick Start.
• Installation and native builds: Continue with this document.
• Configuration reference: See SDK initialization, RUM configuration, Log configuration, Trace configuration, and Cocos Creator Session Replay (experimental).
• Manual collection: See RUM manual instrumentation and Logger log output.
• Collection scope and privacy: See App Data Collection and Data and Privacy.
• Troubleshooting: See Troubleshooting.

Supported Scope¶

Cocos Creator 3.0 through 3.6.2 can be integrated on a trial basis, but the stable native build extension API is available starting from 3.6.3.

The SDK calls the native SDK only in Android and iOS native builds. Browser previews and web builds do not report data.

SDK Versions and Dependency Requirements¶

The Cocos SDK version is determined by the actually installed npm package; the bundled Android/iOS native SDK versions are determined by the dependency configuration in that npm package. The Android Gradle Plugin must be integrated separately and must meet the minimum version requirement in the following table:

The base package @truewatchtech/cocos-sdk and the optional @truewatchtech/cocos-session-replay must use exactly the same version. The base package does not depend on Replay; the Session Replay native dependencies in the table are added only when Replay integration is enabled.

0.1.0-alpha.7 includes the Replay single-frame size policy and fixes for Creator 3 camera and touch collection. When upgrading, you must upgrade both packages, rerun the installer, and rebuild the native project. See Upgrade to alpha.7.

The Cocos build extension configures the matching Android/iOS native SDK dependencies; the Android Gradle Plugin must be integrated as described below. Native host Hybrid projects must also use the native SDK version that matches the installed npm package.

Prerequisites¶

• Install DataKit.
• Configure the RUM collector.
• Configure DataKit to be publicly accessible and install the IP geolocation database.

App Integration¶

1. Go to RUM > Create Application > Android/iOS.
2. Create apps for Cocos Creator Android and iOS separately.
3. Record the application IDs of both apps and fill them into androidAppId and iosAppId respectively.

4. Select the app integration method:

   • Public DataWay: receives data directly, no DataKit collector installation required.
   • Local deployment: after the prerequisites are met, the local DataKit receives data.

Installation¶

Creator 2 and Creator 3 share the same base npm package. To integrate only RUM, Log, and Trace, run the following commands in the Cocos project root directory:

npm install @truewatchtech/cocos-sdk
npx --no-install truewatch-cocos install --project .

When Session Replay is needed, install both packages and enable native integration:

npm install @truewatchtech/cocos-sdk @truewatchtech/cocos-session-replay
npx --no-install truewatch-cocos install --project . --replay

The base package and the Replay package must use exactly the same version, the import entry must use the same Cocos Creator major version, and the SDK must be composed with withSessionReplay() in code. See Session Replay initialization. Installing only the npm packages does not automatically enable native Replay integration.

Replay Install Options¶

The following options are used by the developer integrating the SDK during the project installation phase; they are not runtime initialization parameters:

To disable the integration, run:

npx --no-install truewatch-cocos install --project . --no-replay

After making changes, regenerate and compile the native project; if using CocoaPods, run pod install as well. Existing ReplayPrivacy.ts and .meta files are preserved so that scene or prefab references are not broken. Replay dependencies used by the native host itself remain managed by the host. Uninstalling the npm package or stopping JS frame capture alone does not remove the linked native libraries.

The installer automatically detects the Cocos Creator major version. If it cannot be identified from the project metadata, pass --creator 2 or --creator 3 explicitly.

The installer copies the build extension and native Bridge to the following directories:

• Creator 3: extensions/truewatch-cocos-sdk
• Creator 2: packages/truewatch-cocos-sdk

When --replay is enabled, the installer copies the ReplayPrivacy component script to assets/truewatch-cocos-sdk/ReplayPrivacy.ts to configure Session Replay node masking in scenes or prefabs. See Using the ReplayPrivacy Component.

After installation, reopen Cocos Creator, confirm the truewatch-cocos-sdk extension is enabled, and then regenerate the Android or iOS native project. Running the installation command again updates the same directory.

For TypeScript code, choose the import entry based on the Cocos Creator major version: use @truewatchtech/cocos-sdk/creator2 for Creator 2, and @truewatchtech/cocos-sdk/creator3 for Creator 3.

Native Project Build¶

Android¶

After generating the native project, the build extension automatically completes the following configuration:

• Adds Cocos Bridge and Android native SDK dependencies.
• Enables AndroidX.
• Raises the minimum compileSdkVersion and Build Tools version to 34.
• Raises the minimum minSdkVersion to 21.

The base integration adds ft-sdk and ft-native; only when --replay is enabled are the Replay Bridge, ft-session-replay, and its required AndroidX Fragment dependencies added.

If the project already uses higher versions, the extension preserves the original configuration. After completing the Cocos Creator native build, compile the app normally with Android Studio or the command line.

iOS¶

CocoaPods is used by default. Starting from 0.1.0-alpha.5, you can also choose Swift Package Manager through project configuration.

CocoaPods (Default)¶

The build extension adds FTCocosBridge to the Podfile of the generated project. Each time the iOS project is regenerated, go to the directory containing the Podfile and run:

pod install

Then compile the app using the generated .xcworkspace; do not continue using .xcodeproj. The base integration depends only on TrueWatchSDK/Agent. When --replay is enabled, the extension additionally adds the local FTCocosReplayBridge Pod, which depends on TrueWatchSDK/FTSessionReplay. Both share the same version of the native SDK.

Swift Package Manager (SPM)¶

Create or modify cocos-sdk.config.json in the Cocos project root directory (at the same level as assets):

{
  "ios": {
    "dependencyManager": "spm"
  }
}

This file controls how dependencies are installed during the native build; there is no need to modify the SDK initialization parameters in TypeScript. If not configured, cocoapods is used.

You can also save the same configuration when installing the extension:

npm install @truewatchtech/cocos-sdk
npx --no-install truewatch-cocos install --project . --ios-dependency-manager spm

After modifying the configuration, reopen Creator and generate the iOS native project. The build extension automatically links the local FTCocosBridge Swift Package and resolves the locked version of TrueWatchSDK. When --replay is enabled, it also links the local FTCocosReplayBridge Swift Package and resolves the same version of the native Replay library. The first resolution requires access to the dependency repositories. SPM integration requires iOS SDK 1.6.8-alpha.5 or later; the exact version is determined by the installed Cocos SDK npm package.

A new SPM project does not require pod install; directly open the generated .xcodeproj and compile. If the native host still uses CocoaPods to manage other dependencies, continue opening the host's .xcworkspace.

Switching from CocoaPods

• The extension removes the SDK Pod configuration block it automatically generated; if Pods are already installed, it automatically runs pod install to update the integration, so you still need CocoaPods available on the machine during migration.
• Manually declared FTCocosBridge, FTCocosReplayBridge, TrueWatchSDK, or other Pods that depend on the same native SDK need to be migrated first. The installer reports an error when a conflict is detected to avoid duplicate linking.
• The host's other Pod dependencies keep their original management method.
• To switch back to CocoaPods, change ios.dependencyManager to cocoapods, regenerate the project, and run pod install.

When Creator 3 triggers CMake regeneration during the Xcode build, the extension automatically restores SPM package references and link configuration. If you regenerate the project with CMake separately, rerun Creator's native build integration before opening Xcode.

Updating the SDK¶

After upgrading the npm package, run the installer again and regenerate the native project:

npm install @truewatchtech/cocos-sdk
npx --no-install truewatch-cocos install --project .

Projects using Replay need to upgrade both npm packages together:

npm install @truewatchtech/cocos-sdk @truewatchtech/cocos-session-replay
npx --no-install truewatch-cocos install --project . --replay

When upgrading from the all-in-one package version 0.1.0-alpha.5 or earlier, you also need to migrate the Replay imports and Camera calls. See Package Split Migration.

iOS projects using CocoaPods also need to rerun pod install. For projects using SPM, Xcode re-resolves the dependencies; when rerunning the installer without specifying --ios-dependency-manager, the existing project configuration is preserved.

Next Steps¶

After installation, follow Quick Start to initialize the SDK and verify the first data. For complete configuration and capability boundaries, enter the corresponding topics through the reading path at the top of this page.