SDK 初始化¶
本文说明 Cocos Creator SDK 的基础配置、初始化顺序、用户绑定和生命周期。
基础配置¶
import { guanceSdk } from '@cloudcare/cocos-sdk/creator3';
guanceSdk.start({
sdk: {
datakitUrl: 'https://your-datakit.example.com',
serviceName: 'cocos-game',
env: 'prod',
debug: true,
globalContext: {
game_channel: 'app-store',
},
},
});
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
datakitUrl |
string |
条件必填 | 本地 DataKit 上报地址。与 datawayUrl 二选一 |
datawayUrl |
string |
条件必填 | 公网 DataWay 上报地址。必须与 clientToken 同时配置 |
clientToken |
string |
条件必填 | DataWay 认证 Token |
serviceName |
string |
否 | 数据所属服务名，建议 Android 与 iOS 使用相同值 |
env |
string |
否 | 环境名，常用值为 prod、gray、pre、common、local，也支持自定义值 |
debug |
boolean |
否 | 是否打印 Native SDK 调试日志，生产环境建议关闭 |
globalContext |
Record<string, string> |
否 | 添加到 SDK 数据的静态全局标签 |
必须满足以下任一条件，否则初始化会抛出 Configure datakitUrl or datawayUrl with clientToken：
- 配置非空的
datakitUrl； - 同时配置非空的
datawayUrl与clientToken。
如果两种方式同时配置，Bridge 会优先使用 datakitUrl。建议只保留一种方式，避免环境切换时产生歧义。
SDK 会自动向基础全局标签加入 sdk_package_cocos，值为当前 Cocos npm 包版本。不要使用同名自定义标签。
完整初始化与顺序¶
guanceSdk.start() 按以下顺序初始化：
- 基础 SDK；
- RUM；
- Log；
- Trace；
- Session Replay；
- Cocos 自动采集。
只有传入对应配置对象时才会初始化该模块：
guanceSdk.start({
sdk: {
datawayUrl: 'https://open.dataway.url',
clientToken: 'client-token',
serviceName: 'cocos-game',
env: 'prod',
},
rum: {
androidAppId: 'android-rum-app-id',
iosAppId: 'ios-rum-app-id',
},
logger: {
enableCustomLog: true,
},
trace: {
traceType: 'ddTrace',
},
replay: {
captureFps: 1,
},
autoTrack: {
scenes: true,
},
});
请在首个采集场景加载前初始化，并保证应用生命周期内只调用一次。重复初始化可能在 Native SDK 或自动监听器中产生重复状态。
用户信息绑定¶
可以只传用户 ID：
也可以传入完整用户信息：
guanceSdk.mobile.bindUser({
userId: 'user-123',
userName: '玩家昵称',
userEmail: 'player@example.com',
extra: {
membership: 'gold',
region: 'cn-east',
},
});
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
userId |
string |
是 | 用户唯一标识，不能为空字符串 |
userName |
string |
否 | 用户名称 |
userEmail |
string |
否 | 用户邮箱 |
extra |
Record<string, string> |
否 | 用户附加标签 |
用户退出登录时解绑：
关闭 SDK¶
该方法会：
- 移除 Cocos 自动采集监听器；
- 停止 Session Replay 定时截帧；
- 关闭 Native SDK。
关闭后不要继续调用采集 API。如需重新启用，建议重新启动应用并完成一次初始化。
当前 Cocos API 未暴露手动清理缓存或立即上传方法，数据缓存与发送时机由 Native SDK 管理。
运行平台¶
浏览器预览和 Web 构建属于不支持的平台。TypeScript 调用不会进入 Native Bridge，也不会产生上报数据。接入验证必须使用 Android 或 iOS 原生构建。