Cocos Creator 应用接入¶

通过 Cocos Creator SDK 采集 Android 和 iOS 原生游戏的 RUM、Log、Trace 与 Session Replay 数据。

阅读路径¶

首次接入：先阅读快速开始。
安装与原生构建：继续阅读本文。
参数说明：查看 SDK 初始化、RUM 配置、Log 配置、Trace 配置和 Cocos Creator 会话重放（实验性）。
手动采集：查看 RUM 手动埋点和 Logger 日志打印。
采集范围与隐私：查看应用数据采集和数据与隐私。
问题排查：查看故障排查。

支持范围¶

npm 包	导入入口	Cocos Creator 版本	Node.js	原生平台
`@cloudcare/cocos-sdk`	`@cloudcare/cocos-sdk/creator2`	2.4.5–2.4.15	14+	Android API 21+、iOS 12+
`@cloudcare/cocos-sdk`	`@cloudcare/cocos-sdk/creator3`	3.6.3–3.8.x	16+	Android API 21+、iOS 12+

Creator 3.0–3.6.2 可尝试接入，但稳定的原生构建扩展 API 从 3.6.3 开始提供。

SDK 仅在 Android、iOS 原生构建中调用 Native SDK。浏览器预览和 Web 构建不会上报数据。

前置条件¶

注意

若已开通 RUM Headless 服务，前置条件已自动配置，可直接接入应用。

应用接入¶

进入 用户访问监测 > 新建应用 > Android/iOS。
分别为 Cocos Creator Android 和 iOS 创建应用。
记录两个应用的应用 ID，后续分别填写到 androidAppId 和 iosAppId。
选择应用接入方式：
- 公网 DataWay：直接接收数据，无需安装 DataKit 采集器。
- 本地环境部署：满足前置条件后，由本地 DataKit 接收数据。

安装¶

Creator 2 和 Creator 3 使用同一个 npm 包。在 Cocos 项目根目录执行：

npm install @cloudcare/cocos-sdk
npx @cloudcare/cocos-sdk install --project .

安装器会自动识别 Cocos Creator 主版本。无法从项目元数据识别时，可以显式传入 --creator 2 或 --creator 3。

安装器会把构建扩展与原生 Bridge 复制到以下目录：

Creator 3：extensions/guance-cocos-sdk
Creator 2：packages/guance-cocos-sdk

安装完成后，重新打开 Cocos Creator，确认 guance-cocos-sdk 扩展已启用，再重新生成 Android 或 iOS 原生工程。重复运行安装命令会更新同一目录。

TypeScript 代码应按 Creator 主版本选择导入入口：Creator 2 使用 @cloudcare/cocos-sdk/creator2，Creator 3 使用 @cloudcare/cocos-sdk/creator3。

原生工程构建¶

Android¶

构建扩展会在生成原生工程后自动完成以下配置：

加入 Cocos Bridge 与 Android 原生 SDK 依赖；
启用 AndroidX；
将 compileSdkVersion 和 Build Tools 的最低版本提升到 34；
将 minSdkVersion 的最低版本提升到 21。

如果项目已经使用更高版本，扩展会保留原配置。完成 Cocos Creator 原生构建后，使用 Android Studio 或命令行正常编译应用即可。

观测云 Android Gradle Plugin

Cocos 构建扩展不会自动应用 ft-plugin。Android 的 OkHttp 请求和启动耗时自动采集需要配合 ft-plugin 使用。完成 Cocos Creator Android 原生工程生成后，在生成工程中配置 Plugin，详细步骤见 Android SDK。

Cocos Creator 重新生成 Android 原生工程后，请确认 Plugin 配置仍然保留，再执行 Gradle 编译和应用打包。

iOS¶

构建扩展会把 FTCocosBridge 加入生成工程的 Podfile。每次重新生成 iOS 工程后，进入 Podfile 所在目录执行：

pod install

随后使用生成的 .xcworkspace 编译应用，不要继续使用 .xcodeproj。CocoaPods 会同时集成 GuanceSDK/Agent 和 GuanceSDK/FTSessionReplay。

iOS Session Replay

iOS Session Replay 依赖包含 Cocos External Replay API 的 GuanceSDK 版本。如果当前版本缺少该接口，请升级到支持 Cocos 的 iOS SDK 版本，或暂时不传入 replay 配置。

更新 SDK¶

升级 npm 包后需要再次执行安装器并重新生成原生工程：

npm update
npx @cloudcare/cocos-sdk install --project .

iOS 工程还需要重新执行 pod install。

下一步¶

完成安装后，按照快速开始初始化 SDK 并验证第一条数据。完整配置与能力边界请从本页顶部的阅读路径进入对应专题。