原生宿主 Hybrid 接入¶

本文适用于主体为 Android/iOS 原生应用、仅一个或少数页面使用 Cocos Creator 的 Hybrid 场景。原生宿主负责初始化观测 SDK，Cocos 只在自身页面可见期间接管 Cocos 层的 RUM View、自动采集和 Session Replay 画面捕获。

当前自动管理范围仅支持独立的 Cocos Activity 或 UIViewController。嵌入原生页面局部区域的 Cocos Surface 需要宿主手动管理 RUM View，不支持自动替换并恢复宿主页面 View。

接入边界¶

独立 Cocos 应用与原生宿主 Hybrid 应用使用不同的初始化入口：

start() 与 attach() 互斥。进入 Hybrid 模式后，SDK 会拒绝 Cocos 侧的 mobile.start()、rum.start()、logger.start()、trace.start()、replay.start()、replay.stop() 和 shutdown() 调用，避免重复初始化或关闭原生宿主持有的 SDK。用户绑定、RUM 事件、日志写入和 Trace Header 等非初始化 API 仍可通过 bridge 使用。

attach() 只接受 Cocos 捕获和自动采集配置：

guanceSdk.attach({
  replay: {
    captureFps: 1,
    maxImageDimension: 720,
    touchPrivacy: 'show',
  },
  autoTrack: {
    scenes: true,
    actions: true,
    errors: true,
    network: true,
  },
});

attach() 会通过 FTCocosBridge 确认原生宿主已经初始化 SDK，并向原生全局上下文追加 sdk_package_cocos 版本信息；它不会传递上报地址、RUM App ID、采样率或重新初始化任何原生模块。

Replay 与 RUM 的采样决策、会话、数据存储和全局配置继续由原生 SDK 管理。

touchPrivacy 只控制 Cocos 页面 Replay 是否记录触摸位置；原生页面继续使用宿主的 Session Replay 隐私配置。可选值、默认行为和隐私注意事项见 Cocos Creator 会话重放。

初始化原生宿主¶

Cocos npm/ZIP 安装包已经包含 TypeScript API、Creator 扩展以及 Android/iOS 的 FTCocosBridge，无需在宿主工程中额外添加初始化辅助类。

Android/iOS App 按各自原生 SDK 的接入要求初始化所需的 RUM、Logger、Trace 和 Session Replay，并确保在首次调用 guanceSdk.attach() 前完成初始化。具体配置参考：

• Android SDK 文档
• iOS SDK 文档

对于独立的 Cocos Activity 或 UIViewController，无需为 Hybrid 接入改写原生 SDK 的初始化流程。Cocos 页面显示和离开时，分别调用 enterCocos() 与 leaveCocos() 完成 RUM View 和 Replay 捕获源的切换。

如果启用 Session Replay，原生宿主必须使用默认的原生 recorder 模式完成初始化，不要设置为 external-only；Cocos 侧仅在 attach() 中传入画面捕获配置。

接入 Cocos 生命周期¶

以下示例使用 Creator 3。Creator 2 的 API 完全一致，只需把导入入口改为 @cloudcare/cocos-sdk/creator2。

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

export function attachObservability(camera?: unknown): void {
  if (camera) setReplayCamera(camera);
  guanceSdk.attach({
    replay: {
      captureFps: 1,
      maxImageDimension: 720,
      touchPrivacy: 'show',
    },
    autoTrack: {
      scenes: true,
      actions: true,
      errors: true,
      network: true,
    },
  });
}

export function enterCocos(viewName = 'Cocos'): void {
  guanceSdk.enterCocos({ viewName });
}

export function leaveCocos(): void {
  guanceSdk.leaveCocos();
}

在 Cocos 页面组件中绑定生命周期：

onLoad(): void {
  attachObservability();
}

onEnable(): void {
  enterCocos('Game');
}

onDisable(): void {
  leaveCocos();
}

onDestroy(): void {
  leaveCocos();
}

默认使用当前场景中找到的第一个 Camera。多 Camera 项目应把用于重放的 Camera 传给 attachObservability(camera)，切换主 Camera 后再次调用 setReplayCamera(camera)。

attach()、已经进入后的 enterCocos()，以及已经离开后的 leaveCocos() 都是幂等操作。销毁路径可以再次调用 leaveCocos()，用于覆盖异常退出或重复回调。

如果 recorder 切换失败，相关调用会抛出错误。排除 Native SDK 版本或初始化问题后，应再次调用当前生命周期方法完成进入或离开，不要改用 shutdown() 清理原生宿主持有的实例。

如果 autoTrack.scenes 为 false，enterCocos() 必须传入 viewName，SDK 会手动创建一个 Cocos View。开启场景自动跟踪后，viewName 用作进入时的初始 View，后续场景切换由场景名接管。

View 与 Replay 所有权¶

页面切换时的所有权顺序如下：

原生全屏弹层、登录页或其他页面即使没有销毁 Cocos 页面，只要完全覆盖 Cocos，也必须在展示前通过业务生命周期通知 Cocos 调用 leaveCocos()；弹层关闭且 Cocos 再次可见后调用 enterCocos()。仅暂停 Cocos 渲染不能完成 RUM View 和 Replay 所有权转移。

同一时刻应只有一个有效 RUM View 和一个 Replay 捕获源。不要同时让原生自动跟踪与 Cocos 自动跟踪记录专用 Cocos 容器，也不要手动调用 guanceSdk.replay.start() 或 stop() 控制 attached Replay。

嵌入式 Cocos Surface¶

如果 Cocos 只占原生 Activity 或 UIViewController 的局部区域，当前 Native SDK 无法自动暂停并恢复宿主控制器的 View。该场景需要宿主关闭该页面的原生自动 View 跟踪，并自行使用手动 RUM API 管理宿主 View 与 Cocos View 的先后关系：进入前结束宿主 View，离开后重新启动宿主 View。

在 Native SDK 提供作用域化的 View 抑制和恢复接口前，不要仅根据 Cocos 引擎暂停、恢复回调推断 View 所有权。

验证接入¶

建议在 Android 和 iOS 真机上分别执行至少三轮 原生页面 -> Cocos 页面 -> 原生页面：

1. 每次进入 Cocos 前调用 enterCocos()，离开或被完全覆盖前调用 leaveCocos()。
2. 检查原生日志中没有 SDK 重复初始化、缺少 Hybrid recorder 接口或 Replay 未以原生模式初始化的错误。
3. 在 RUM 查看器确认每个时段只有一个 View，Cocos 场景没有同名原生容器 View。
4. 打开 Session Replay，确认原生页面与 Cocos 页面连续可播放，边界没有双重画面、空白帧或离开后的 Cocos 残留帧。
5. 检查 Cocos Action、Resource、Error，以及与 RUM 关联的 Log 和 Trace 数据。

常见错误：