Cocos Creator 应用接入¶

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

阅读路径¶

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

支持范围¶

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

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

SDK 版本与依赖要求¶

Cocos SDK 版本以实际安装的 npm 包为准，配套的 Android/iOS 原生 SDK 版本由该 npm 包中的依赖配置决定。Android Gradle Plugin 需单独接入，并满足下表的最低版本要求：

基础包 @cloudcare/cocos-sdk 与可选的 @cloudcare/cocos-session-replay 必须使用完全相同的版本。基础包不依赖 Replay；表中的 Session Replay 原生依赖仅在启用 Replay 集成时添加。

0.1.0-alpha.7 包含 Replay 单帧大小策略及 Creator 3 相机、触摸采集修复。升级时需同时升级两个包、重新运行安装器并重新构建原生工程，具体见升级到 alpha.7。

Cocos 构建扩展会配置配套的 Android/iOS 原生 SDK 依赖；Android Gradle Plugin 需按下文接入。原生宿主 Hybrid 工程也需使用与所安装 npm 包配套的原生 SDK 版本。

百分比采样字段的适用范围¶

新字段使用 0–100 的百分数，1 表示 1%，100 表示全量，0.1 表示 0.1%。RUM、Log、Trace 的参数及兼容规则见采样说明，Replay 参数见会话重放初始化。

前置条件¶

• 安装 DataKit。
• 配置 RUM 采集器。
• DataKit 配置为公网可访问，并且安装 IP 地理信息库。

应用接入¶

1. 进入 用户访问监测 > 新建应用 > Android/iOS。
2. 分别为 Cocos Creator Android 和 iOS 创建应用。
3. 记录两个应用的应用 ID，后续分别填写到 androidAppId 和 iosAppId。

4. 选择应用接入方式：

   • 公网 DataWay：直接接收数据，无需安装 DataKit 采集器。
   • 本地环境部署：满足前置条件后，由本地 DataKit 接收数据。

安装¶

Creator 2 和 Creator 3 共用基础 npm 包。仅接入 RUM、Log、Trace 时，在 Cocos 项目根目录执行：

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

需要 Session Replay 时，同时安装两个包并启用原生集成：

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

基础包与 Replay 包的版本号必须完全一致，导入入口必须使用相同的 Creator 主版本，并在代码中通过 withSessionReplay() 组合 SDK，详见会话重放初始化。仅安装 npm 包不会自动启用原生 Replay 集成。

Replay 安装参数¶

以下参数由接入 SDK 的开发者在项目安装阶段使用，不是运行时初始化参数：

关闭集成时执行：

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

修改后需重新生成并编译原生工程；使用 CocoaPods 时还需执行 pod install。已有的 ReplayPrivacy.ts 和 .meta 会保留，避免破坏场景或预制体引用。原生宿主自行使用的 Replay 依赖仍由宿主管理。只卸载 npm 包或停止 JS 截帧不会移除已链接的原生库。

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

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

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

启用 --replay 后，安装器会将 ReplayPrivacy 组件脚本复制到 assets/guance-cocos-sdk/ReplayPrivacy.ts，用于在场景或预制体中配置 Session Replay 节点遮罩，详见使用 ReplayPrivacy 组件。

安装完成后，重新打开 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。

基础集成添加 ft-sdk 与 ft-native；启用 --replay 时，才额外添加 Replay Bridge、ft-session-replay 和其所需的 AndroidX Fragment 依赖。

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

iOS¶

默认使用 CocoaPods。从 0.1.0-alpha.5 起，也可通过项目配置选择 Swift Package Manager。

CocoaPods（默认）¶

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

pod install

随后使用生成的 .xcworkspace 编译应用，不要继续使用 .xcodeproj。基础集成仅依赖 GuanceSDK/Agent；启用 --replay 时，扩展会额外加入本地 FTCocosReplayBridge Pod，由其依赖 GuanceSDK/FTSessionReplay。两者共享同一版本的原生 SDK。

Swift Package Manager（SPM）¶

在 Cocos 项目根目录（与 assets 同级）创建或修改 cocos-sdk.config.json：

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

此文件控制原生构建时的依赖安装方式，无需修改 TypeScript 中的 SDK 初始化参数。未配置时使用 cocoapods。

也可以在安装扩展时保存同一配置：

npm install @cloudcare/cocos-sdk
npx --no-install guance-cocos install --project . --ios-dependency-manager spm

修改配置后，重新打开 Creator 并生成 iOS 原生工程。构建扩展会自动关联本地 FTCocosBridge Swift Package，并解析锁定版本的 GuanceSDK。启用 --replay 时，还会关联本地 FTCocosReplayBridge Swift Package 并解析同版本的 同版本原生 Replay 库。首次解析需要能够访问依赖仓库。SPM 集成要求 iOS SDK 为 1.6.8-alpha.5 及以上版本，具体版本由所安装的 Cocos SDK npm 包决定。

全新 SPM 工程无需执行 pod install，直接打开生成的 .xcodeproj 编译。若原生宿主仍使用 CocoaPods 管理其他依赖，请继续打开宿主的 .xcworkspace。

从 CocoaPods 切换

• 扩展会移除其自动生成的 SDK Pod 配置块；已有 Pods 安装时，会自动执行 pod install 更新集成，因此迁移时仍需本机可运行 CocoaPods。
• 手动声明的 FTCocosBridge、FTCocosReplayBridge、GuanceSDK 或依赖同一原生 SDK 的其他 Pod，需要先完成迁移。检测到冲突时安装器会报错，避免重复链接。
• 宿主的其他 Pod 依赖保持原有管理方式。
• 若需切回 CocoaPods，将 ios.dependencyManager 改为 cocoapods，重新生成工程并执行 pod install。

Creator 3 在 Xcode 构建过程中触发 CMake 重新生成时，扩展会自动恢复 SPM 包引用与链接配置。若单独执行 CMake 重新生成工程，请重新运行 Creator 的原生构建集成，再打开 Xcode。

更新 SDK¶

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

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

使用 Replay 的项目需要同步升级两个 npm 包：

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

从 0.1.0-alpha.5 或更早的一体包升级时，还需迁移 Replay 导入和 Camera 调用，参见拆包迁移。

使用 CocoaPods 的 iOS 工程还需要重新执行 pod install。使用 SPM 的工程由 Xcode 重新解析依赖；重新运行安装器时，未指定 --ios-dependency-manager 会保留已有的项目配置。

下一步¶

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