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¶

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:

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

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¶

• 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 App > Android/iOS.
2. Create separate apps for Cocos Creator Android and iOS.
3. Record the application IDs of the two apps, and fill them into androidAppId and iosAppId respectively.

4. 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 share the same base npm package. To integrate only RUM, Log, and Trace, run the following in the Cocos project root directory:

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6
npx --no-install guance-cocos install --project .

When Session Replay is needed, install the two packages together and enable native integration:

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6 @cloudcare/cocos-session-replay@0.1.0-alpha.6
npx --no-install guance-cocos install --project . --replay

The import entries of the two packages must use the same 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 project installation; they are not runtime initialization parameters:

To disable the integration, run:

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

After the change, you need to regenerate and compile the native project; with CocoaPods, also run pod install. Existing ReplayPrivacy.ts and .meta files are kept to avoid breaking scene or prefab references. Replay dependencies used by the native host itself remain managed by the host. Simply uninstalling the npm packages or stopping JS frame capture does not remove the already linked native libraries.

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/guance-cocos-sdk
• Creator 2: packages/guance-cocos-sdk

When --replay is enabled, the installer copies the ReplayPrivacy component script to assets/guance-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 guance-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 @cloudcare/cocos-sdk/creator2 for Creator 2 and @cloudcare/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.

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

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.

iOS¶

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

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. The base integration depends only on GuanceSDK/Agent; when --replay is enabled, the extension additionally adds a local FTCocosReplayBridge Pod, which depends on GuanceSDK/FTSessionReplay. Both share the same version of the native SDK.

Swift Package Manager (SPM)¶

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

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

This file controls the dependency installation method during native builds; you do not need to modify the SDK initialization parameters in TypeScript. When not configured, cocoapods is used.

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

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6
npx --no-install guance-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 GuanceSDK. When --replay is enabled, it also links the local FTCocosReplayBridge Swift Package and resolves the same version of GuanceSessionReplay. The first resolution requires access to the dependency repository; the currently locked iOS SDK version is 1.6.8-alpha.5.

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

Switching from CocoaPods

• The extension removes its auto-generated SDK Pod configuration block; when Pods are already installed, it automatically runs pod install to update the integration. Therefore, CocoaPods must still be runnable on your machine during migration.
• Manually declared FTCocosBridge, FTCocosReplayBridge, GuanceSDK, or other Pods that depend on the same native SDK must be migrated first. When a conflict is detected, the installer reports an error to avoid duplicate linking.
• Other Pod dependencies of the host keep their original management approach.
• 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 the SPM package references and link configuration. If you regenerate the project with CMake separately, rerun Creator's native build integration, and then open Xcode.

Updating the SDK¶

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

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6
npx --no-install guance-cocos install --project .

Projects using Replay need to upgrade the two npm packages in sync:

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6 @cloudcare/cocos-session-replay@0.1.0-alpha.6
npx --no-install guance-cocos install --project . --replay

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

iOS projects using CocoaPods also need to run pod install again. Projects using SPM have their dependencies re-resolved by Xcode; when rerunning the installer, omitting --ios-dependency-manager keeps the existing project configuration.

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.