快速开始¶

本文提供 Cocos Creator SDK 的最短接入路径，帮助您完成一次可验证的 RUM、Log 和 Trace 数据上报。

接入前请确认所安装的 npm 包及原生依赖符合SDK 版本与依赖要求。

前置准备¶

在用户访问监测中分别创建 Android 和 iOS 应用，并获取两个应用 ID。
准备一种上报方式：
- 本地环境部署：准备 datakitUrl。
- 公网 DataWay：准备 datawayUrl 和 clientToken。
安装 @cloudcare/cocos-sdk 并运行项目安装器，详细步骤见应用接入。
重新打开 Cocos Creator，并生成 Android 或 iOS 原生工程。
使用 CocoaPods 的 iOS 工程进入 Podfile 所在目录执行 pod install，随后打开 .xcworkspace。使用 SPM 时，按 iOS 原生构建配置后编译，无需为全新工程安装 Pods。

以下最小示例只使用基础包。需要会话重放时，先按Replay 安装参数安装独立包并运行 --replay，再使用组合后的 SDK 实例初始化。

最小初始化¶

以下示例使用 Creator 3。Creator 2 只需把导入入口改为 @cloudcare/cocos-sdk/creator2。

import { guanceSdk } from '@cloudcare/cocos-sdk/creator3';

export function startObservability(): void {
  guanceSdk.start({
    sdk: {
      datakitUrl: 'https://your-datakit.example.com',
      serviceName: 'cocos-game',
      env: 'prod',
      debug: true,
    },
    rum: {
      androidAppId: 'android-rum-app-id',
      iosAppId: 'ios-rum-app-id',
      sampleRate: 1,
    },
    logger: {
      enableCustomLog: true,
      enableLinkRumData: true,
      sampleRate: 1,
    },
    trace: {
      traceType: 'ddTrace',
      enableLinkRumData: true,
      sampleRate: 1,
    },
    autoTrack: {
      scenes: true,
      actions: true,
      errors: true,
      network: true,
    },
  });
}

请在第一个需要采集的场景加载前调用 startObservability()，并确保整个应用生命周期只初始化一次。

迁移到百分比采样字段

上面的最小示例使用 0.1.0-alpha.7 支持的旧字段 sampleRate: 1，表示全量采样。使用包含百分比采样改造的 SDK 构建时，可分别替换为 rum.sessionSamplingRate: 100、logger.logSamplingRate: 100 和 trace.traceSamplingRate: 100。

新字段的单位为 0–100，1 仅表示 1%，不能直接沿用旧字段的数值。同一采样项同时设置新旧字段时，新字段优先，包括显式的 0。旧字段继续兼容；小数百分比及 iOS 原生限制见采样说明。

如果应用主体为 Android/iOS 原生页面，仅一个或少数页面使用 Cocos，不要再次调用 guanceSdk.start()。该场景应由原生宿主完成一次 SDK 初始化，Cocos 通过 attach() 接入，详见原生与 Cocos 混合开发。

如果使用公网 DataWay，将 sdk 改为：

sdk: {
  datawayUrl: 'https://open.dataway.url',
  clientToken: 'client-token',
  serviceName: 'cocos-game',
  env: 'prod',
  debug: true,
},

datakitUrl 与 datawayUrl 二选一；使用 datawayUrl 时必须同时传入 clientToken。

打印一条自定义日志¶

在初始化后调用：

guanceSdk.logger.log('Cocos SDK initialized', 'info', {
  scene: 'Boot',
});

验证接入¶

使用 Android 或 iOS 原生构建运行应用，浏览器预览不会上报数据。
切换场景、触发一次触摸操作并发起网络请求。
检查 Cocos 控制台和原生日志中是否有初始化或 Bridge 错误。
进入用户访问监测 > 查看器，选择对应的 Android 或 iOS 应用。
确认存在 View、Action 或 Resource 数据，并在日志查看器中确认自定义日志。
验证完成后，在生产环境关闭 debug。

下一步¶

基础参数与用户绑定：SDK 初始化
RUM 与自动采集：RUM 配置
日志：Log 配置
链路追踪：Trace 配置
会话重放：Cocos Creator 会话重放（实验性）
原生 App 局部使用 Cocos：原生与 Cocos 混合开发
手动采集：RUM 手动埋点
无数据或构建失败：故障排查