Cocos Creator App Integration¶

Collect RUM, Log, Trace, and Session Replay data from native Android and iOS games through the Cocos Creator SDK.

Reading Path¶

First-time integration: Start with Quick Start.
Installation and native build: Continue reading this article.
Parameter 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¶

npm Package	Import Entry	Cocos Creator Version	Node.js	Native Platforms
`@truewatchtech/cocos-sdk`	`@truewatchtech/cocos-sdk/creator2`	2.4.5–2.4.15	14+	Android API 21+, iOS 12+
`@truewatchtech/cocos-sdk`	`@truewatchtech/cocos-sdk/creator3`	3.6.3–3.8.x	16+	Android API 21+, iOS 12+

Creator 3.0–3.6.2 can be attempted, but the stable native build extension API is available starting from 3.6.3.

The SDK invokes the Native SDK only in Android and iOS native builds. Browser preview and Web builds do not report data.

Current SDK Version Set¶

This set of Cocos integration documents consistently uses the following version set:

Component	Version
Cocos SDK	`0.1.0-alpha.4`
Android Agent (`ft-sdk`)	`1.7.6-alpha02`
Android Session Replay (`ft-session-replay`)	`0.1.9-alpha03`
Android Gradle Plugin (`ft-plugin`)	`1.3.8`
iOS Agent and Session Replay (`TrueWatchSDK/Agent`, `FTSessionReplay`)	`1.6.8-alpha.2`

The Cocos build extension configures the corresponding Android/iOS native SDK dependencies; the Android Gradle Plugin must be integrated as described below. Native host hybrid projects also use this version set.

Prerequisites¶

Note

If the RUM Headless service is enabled, the prerequisites are already configured, and you can integrate the app directly.

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

App Integration¶

Go to RUM > Create App > Android/iOS.
Create separate apps for Cocos Creator Android and iOS.
Record the application IDs of the two apps, and fill them into androidAppId and iosAppId respectively.
Select the app integration method:
- Public DataWay: receives data directly without installing the DataKit Collector.
- Local deployment: after the prerequisites are met, the local DataKit receives the data.

Installation¶

Creator 2 and Creator 3 use the same @truewatchtech/cocos-sdk package. For the current integration, use the provided local .tgz package. Run the following in the Cocos project root directory, and replace the path with the actual package path:

npm install /path/to/truewatchtech-cocos-sdk-0.1.0-alpha.4.tgz
npx --no-install truewatch-cocos install --project .

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

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

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

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

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

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

Building the Native Project¶

Android¶

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

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

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

TrueWatch Android Gradle Plugin

The Cocos build extension does not automatically apply ft-plugin. Automatic collection of OkHttp requests and startup time on Android requires ft-plugin. After the Cocos Creator Android native project is generated, configure the Plugin in the generated project. For detailed steps, see Android SDK.

After Cocos Creator regenerates the Android native project, confirm that the Plugin configuration is still present, and then run the Gradle build and package the app.

iOS¶

CocoaPods is used by default.

CocoaPods (Default)¶

The build extension adds FTCocosBridge to the Podfile of the generated project. After each regeneration of the iOS project, go to the directory containing the Podfile and run:

pod install

Then compile the app with the generated .xcworkspace; do not continue using the .xcodeproj. CocoaPods integrates both TrueWatchSDK/Agent and TrueWatchSDK/FTSessionReplay.

Updating the SDK¶

After installing a new version of the local .tgz package, run the installer again and regenerate the native project:

npm install /path/to/truewatchtech-cocos-sdk-0.1.0-alpha.4.tgz
npx --no-install truewatch-cocos install --project .

iOS projects using CocoaPods also need to run pod install again.

Next Steps¶

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