跳转至

故障排查

初始化后无数据

依次检查：

  1. 必须使用 Android 或 iOS 原生构建，浏览器预览和 Web 构建不会上报。
  2. 确认已执行 npx --no-install guance-cocos install --project .，重新打开 Cocos Creator 并启用 guance-cocos-sdk 扩展。
  3. 升级或重新安装 npm 包后，必须重新生成原生工程。
  4. 确认 datakitUrl，或 datawayUrl 与 clientToken 配置正确。
  5. Android 必须提供 androidAppId，iOS 必须提供 iosAppId。
  6. 初始化阶段设置 debug: true，检查 Cocos 和原生日志。
  7. 确认 sampleRate 不为 0。
  8. 如使用本地环境部署，继续排查 DataKit 无数据问题。

安装器提示找不到 Cocos 项目

如果出现：

No Cocos project found ... (missing assets directory)

--project 必须指向包含 assets 目录的 Cocos 项目根目录：

npx --no-install guance-cocos install --project /absolute/path/to/cocos-project

使用了错误的 Creator 入口

Creator 2 和 Creator 3 使用同一个 @cloudcare/cocos-sdk npm 包，但导入入口不同：

  • Creator 2：@cloudcare/cocos-sdk/creator2
  • Creator 3：@cloudcare/cocos-sdk/creator3

修改导入入口后，重新运行安装器并生成原生工程。如果安装器无法识别 Creator 版本，显式传入 --creator 2 或 --creator 3。

Android Bridge 或依赖错误

出现 ClassNotFoundException、FTCocosBridge 找不到或原生 SDK 类缺失时：

  1. 确认生成工程包含 cocos-sdk-native/android。
  2. 检查应用模块 build.gradle 中是否存在 COCOS_SDK_BEGIN 标记块。
  3. 确认 Gradle 可以访问 https://mvnrepo.guance.com/repository/maven-releases。
  4. 确认 AndroidX 已启用。
  5. 确认 Compile SDK 与 Build Tools 不低于 34，Min SDK 不低于 21。
  6. 重新运行安装器并重新生成工程，不要只复用旧的 Native 工程。

iOS Bridge 或 CocoaPods 错误

以下检查适用于使用 CocoaPods 的工程：

  1. 确认生成工程包含 cocos-sdk-native/ios。
  2. 确认 Podfile 中存在 pod 'FTCocosBridge'。
  3. 在 Podfile 所在目录重新执行 pod install。
  4. 使用 .xcworkspace，不要使用 .xcodeproj。
  5. 清理 Xcode Build Folder 后重新构建。

Creator 2 工程的 iOS 最低版本会被提升到 12.0；Xcode 15 兼容链接参数由构建扩展自动写入生成配置。

iOS SPM 配置未生效或构建失败

  1. 确认已安装 0.1.0-alpha.5 或更高版本的 SDK 包，并重新运行安装器更新 Creator 扩展；功能可用性见 SPM 接入说明。
  2. 确认 cocos-sdk.config.json 位于 Cocos 项目根目录，且 ios.dependencyManager 为 spm，随后重新生成 iOS 工程。
  3. 检查生成目录中的 cocos-sdk-native/FTCocosBridge/Package.swift，以及应用 target 的 FTCocosBridge 包依赖。首次解析失败时，确认 Xcode 能访问清单中的 Git 仓库和版本标签。
  4. 若提示手动声明的 SDK Pod 或其他 Pod 仍依赖同一原生 SDK，先完成这些依赖的迁移。若更新已有 Pods 失败，检查本机 pod 命令和错误信息后重试。
  5. Creator 3 若提示旧式构建位置不支持 Packages，或 CMake 重生成后包引用丢失，重新运行更新后的 Creator 构建扩展；扩展会调整构建位置设置，并在 Xcode 触发 CMake 重生成后恢复 SPM 集成。
  6. 全新 SPM 工程打开 .xcodeproj；宿主还有其他 Pods 时继续使用 .xcworkspace。请勿手动添加第二份 Bridge 或原生 SDK 来解决链接错误。

有 RUM，但没有 View

  • 开启 autoTrack.scenes: true；或
  • 在业务场景进入时调用 guanceSdk.rum.startView()，离开时调用 stopView()。

初始化时间晚于首个场景启动时，可能错过场景事件。应在首个采集场景前初始化。

自动 Action 或 Error 不生效

Action：

  • 确认 autoTrack.actions: true；
  • 确认交互最终触发全局 TOUCH_END；
  • 自定义输入系统或吞掉全局事件的组件需要手动调用 Action API。

Error：

  • 确认 autoTrack.errors: true；
  • 当前运行时必须提供全局 addEventListener；
  • 已被业务 try/catch 捕获的异常需要手动调用 addError()。

Log 无数据或没有 RUM 关联

  • 初始化 logger 并设置 enableCustomLog: true。
  • 检查 sampleRate 和 logLevelFilters。
  • Console 采集还需要 autoTrack.console: true。
  • RUM 关联需要 enableLinkRumData: true、有效 RUM Session 和当前 View。
  • 早于首个 View 产生的日志可能没有 View 关联。

Trace Header 为空

  • 确认已初始化 trace。
  • URL 不能为空且必须是 Native SDK 可处理的有效 URL。
  • 检查 Trace 采样率。
  • 不支持平台会返回空对象。
  • 自动注入只覆盖运行时提供的 fetch 和 XMLHttpRequest。

网络数据重复

检查是否同时开启：

  • autoTrack.network 与 enableNativeUserResource；
  • autoTrack.network 与 enableNativeAutoTrace；
  • 自动网络采集与业务手动 Resource/Trace。

对同一请求栈保留一种采集路径，再比较 RUM Resource 数量与请求头。

Android 推荐保留 JS 网络采集，并保持原生 setEnableHttpURLConnectionResource(false)；enableNativeUserResource 是总开关，不会单独开启 HttpURLConnection 采集。参见 Android 网络采集建议。

iOS 需区分 Creator 2 的 NSURLConnection 与 Creator 3.8.8 的 NSURLSession。前者从 iOS SDK 1.6.8-alpha.5 开始通过独立开关启用，后者由原有开关控制；任一路径与 JS 自动或手动 Resource 同时采集都可能重复。参见 iOS 网络采集建议。

Replay 包或原生集成缺失

从 0.1.0-alpha.6 起，Replay 需要独立 npm 包、代码组合和原生集成三步：

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

随后重新生成并编译原生工程；使用 CocoaPods 时执行 pod install。代码使用 withSessionReplay(baseSdk) 返回的实例，参见拆包迁移。

提示或现象 处理方式
Cannot find module '@cloudcare/cocos-session-replay/...' / Session Replay is not installed 在当前 Cocos 项目安装与基础包完全同版本的 Replay 包
Session Replay requires @cloudcare/cocos-session-replay 在基础实例初始化之前调用 withSessionReplay()，将 replay 配置传给组合后的实例
SDK extension version or Creator engine does not match the base SDK 核对两个包版本完全相同，导入入口均为 /creator2 或均为 /creator3
Install SDK extensions before start() or attach() 将组合调用提前到 SDK 启动或 Hybrid 绑定之前
Session Replay native integration is unavailable 运行安装器 --replay 并重新构建；Hybrid 项目还需确认原生宿主已初始化兼容版本的 SDK
基础包不再导出 setReplayCamera 改用组合后实例的 guanceSdk.setReplayCamera(camera)

安装器检测到被本地修改的 SDK 文件时会停止并提示具体路径。先备份并核对这些定制修改，再重新安装；不要直接删除场景引用的 ReplayPrivacy.ts 或 .meta。

Session Replay 没有画面

  1. 确认已初始化 RUM 且当前存在有效 View。
  2. 确认场景中存在 Camera，或调用 guanceSdk.setReplayCamera()。
  3. 确认 Replay 与 RUM 的采样率不为 0。
  4. 静止画面会被判定为重复帧并跳过。
  5. 检查控制台是否出现捕获停止错误。
  6. 按SDK 版本与依赖要求检查 Session Replay 原生依赖，并重新生成、编译原生工程。

Creator 3 Replay 画面或触摸异常

0.1.0-alpha.7修复显示 Camera 受截帧影响、UI 控件消费的触摸在 Replay 中遗漏，以及 Replay 采集影响正常输入分发的问题。按升级步骤更新两个 npm 包并重新构建。

  • 确认使用组合后的 guanceSdk.setReplayCamera(camera) 指定所需 Camera；SDK 只采集一个 Camera，不合成多个 Camera 的画面。
  • Replay 没有触摸位置时，检查 touchPrivacy 是否显式设置为 show；默认 hide 不记录位置。autoTrack.actions 与 Replay 触摸采集独立。
  • 在按钮、摇杆和空白区域分别验证业务响应及 Replay 记录。避免为补偿旧版触摸遗漏而重复调用业务输入逻辑。
  • 图片缩小后，核对触摸及遮罩与显示坐标一致；不要把编码图片的尺寸直接当成游戏显示尺寸。

初始化参数抛出异常

错误 原因
Configure datakitUrl or datawayUrl with clientToken 未配置有效上报地址
... must be between 0 and 1 RUM、Log、Trace 或 Replay 采样率越界
captureFps must be an integer between 1 and 5 Replay FPS 不是 1–5 的整数
maxImageDimension must be between 1 and 2048 Replay 最长边越界
... must not be empty View、Action、Resource Key 或 Trace URL 等必填字符串为空

性能问题

  • Session Replay 从 captureFps: 1、maxImageDimension: 720 开始。
  • 不需要时关闭 Console 自动采集。
  • 避免在日志和事件属性中传入大型对象。
  • 只启用需要的 Native 监控指标。
  • 检查是否存在重复网络采集。

关闭 SDK 后不再采集

guanceSdk.shutdown() 会移除自动监听、停止 Session Replay 并关闭 Native SDK。关闭后不要继续调用采集方法；如需重新启用，建议重新启动应用并完成一次初始化。

文档评价

文档内容是否对您有帮助？