Cocos Creator 会话重放（实验性）¶

本文说明 Cocos Creator Session Replay 初始化、Camera 选择、性能参数、触摸隐私和节点隐私规则。

前置条件¶

Session Replay 依赖：

1. Android 或 iOS 原生构建；
2. 已初始化 RUM；
3. 当前存在有效 RUM View；
4. 当前 Native SDK 版本支持 Cocos External Replay。

如果没有有效 RUM Context，SDK 会跳过当前帧，不会生成独立于 RUM 的重放数据。建议开启 autoTrack.scenes，或在截帧前手动调用 guanceSdk.rum.startView()。

初始化¶

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

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  replay: {
    sampleRate: 1,
    sessionOnErrorSampleRate: 0,
    captureFps: 2,
    maxImageDimension: 720,
    imagePolicy: {
      quality: 'medium',
    },
    touchPrivacy: 'show',
  },
  autoTrack: {
    scenes: true,
  },
});

非法采样率、FPS、图片尺寸或流量策略会在 TypeScript 层抛出 TypeError 或 RangeError。

图片流量策略¶

imagePolicy 用于限制已录制会话产生的图片 Resource 流量。只配置质量档位即可使用对应预设：

replay: {
  captureFps: 2,
  imagePolicy: {
    quality: 'medium',
  },
}

imagePolicy 支持以下字段：

显式设置的 maxImageDimension、maxFrameBytes 和 maxBytesPerMinute 会覆盖档位预设。captureFps 始终独立配置；提高到 2 fps 或更高时，预算控制器会限制实际输出，因此流量不会按标称 FPS 持续线性增长。

开启 adaptiveCapture 后，SDK 按最近 60 秒已经接受的图片大小调整采集：

新 View 或横竖屏变化的首帧可使用最多 100 KiB 的独立突发额度，保证页面切换后尽快出现完整画面。为避免质量频繁抖动，预算下降后使用较低的恢复阈值逐步回到正常采集状态。

Camera 选择¶

默认使用当前场景中找到的第一个 Camera。多 Camera 项目应显式指定需要重放的 Camera：

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

export function selectReplayCamera(camera: unknown): void {
  setReplayCamera(camera);
}

setReplayCamera() 每次只保存一个 Camera。多次调用时，后一次传入的 Camera 会覆盖此前设置，SDK 不会同时采集或合成多个 Camera。如果调用时上一帧正在采集，新 Camera 将从下一次采集开始生效。

切换主 Camera 后应再次调用 setReplayCamera()。如果场景中没有可用 Camera，当前帧会被跳过。

触摸隐私¶

touchPrivacy 控制 Session Replay 是否记录触摸位置：

触摸采集属于 Session Replay，与 autoTrack.actions 相互独立：即使没有开启 autoTrack.actions，touchPrivacy: 'show' 仍会记录 Replay 触摸；反之，开启 Action 自动采集但保留 touchPrivacy: 'hide' 时，Replay 中仍不会出现触摸位置。即使前后两帧画面没有变化，待写入的触摸操作也会单独保存到 Replay。

当前 Cocos API 只支持全局触摸隐私设置，不支持按节点覆盖触摸隐私。guanceSdk.replay.setPrivacy(node, 'hide') 只隐藏节点画面，不会隐藏该位置上的触摸记录；敏感页面应在启动 Session Replay 时使用 touchPrivacy: 'hide'。

节点隐私¶

所有 EditBox 节点默认使用 mask。还可以为指定节点设置规则：

guanceSdk.replay.setPrivacy(accountNode, 'mask');
guanceSdk.replay.setPrivacy(secretPanelNode, 'hide');
guanceSdk.replay.setPrivacy(publicNode, 'unmask');

unmask 只删除自定义规则。节点如果仍是 EditBox，默认遮罩继续生效。

隐私区域按节点的世界坐标矩形计算。自定义渲染、粒子、Shader、RenderTexture 或超出节点包围盒的视觉内容不会自动推导隐私区域，必须在接入测试中逐场景检查。

更多隐私建议见数据与隐私。

运行行为¶

• 使用 Cocos RenderTexture 截取 RGBA 画面。
• 未配置 imagePolicy 时保留旧图片路径；显式配置后，Android 使用 WebP V2，iOS 使用 JPEG V2，并按实际编码大小记账。
• 隐私遮罩在图片压缩前完成。
• 内容完全相同或近似静止的帧会被跳过；View、画面尺寸或隐私规则变化会强制生成变化帧。
• 图片因去重、预算或编码大小被跳过时，待写入的触摸记录仍会单独保存。
• 上一帧仍在处理时，不会并发处理新帧。
• 单帧捕获或编码失败只丢弃当前帧，不会停止后续 Session Replay 采集。
• 临时图像写入 Native SDK 后会从应用临时目录删除。

流量估算¶

流量预算仅统计图片 Resource，不包含 Replay Segment、触摸记录和上传协议开销。连续战斗、镜头移动、粒子等高动态画面通常更接近档位上限；菜单、静态背景和少量 UI 动画会受完全相同帧与近似静止检测影响，实际消耗通常更低。

下表基于 V2 编码与对应档位的默认配置，按单个稳定 View 估算。它用于容量规划，不是实测数据或网络计费保证；显式修改 maxImageDimension、maxFrameBytes 或 maxBytesPerMinute 后，范围和上限会随之变化。

休闲场景范围假设画面持续存在少量变化；如果画面完全静止，去重后流量可能更低。高动态图片值是滚动 60 秒预算上限，不是固定消耗。总量参考在图片 Resource 的基础上估入低触摸密度下的 Replay Segment、触摸元数据和应用层上传开销，不包含生产网络中的 TLS、TCP/IP、蜂窝或 Wi-Fi 链路开销。

Android V2 使用 WebP，iOS V2 使用 JPEG。图片内容、压缩器的平台差异、实际变化帧数、View 或方向切换次数、触摸密度和上传重试都会影响最终流量；上线前应在目标平台和实际业务场景中测量。

可使用以下方式估算单个已录制会话的图片流量：

每分钟图片流量 ≈ min(每分钟实际变化帧数 × 平均编码大小, 图片滚动 60 秒预算)

例如 captureFps: 2、quality: 'medium' 时，动态画面在预算达到 75% 后自动降频，并在 90% 后降低质量和尺寸，图片 Resource 受 1.5 MiB 滚动 60 秒预算约束，而不是按照 2 × 60 × 40 KiB 持续增长到约 4.7 MiB/分钟。每次新 View 或方向切换的首帧仍可使用最多 100 KiB 的独立突发额度，因此对应窗口可能短时高于常规图片预算。

预算控制的是每个已录制会话，不能代替会话采样。生产环境可先将普通会话 sampleRate 设为 0.01–0.05，再按排障需求配置 sessionOnErrorSampleRate；诊断环境可以临时使用 100% 采样。整体图片流量可按以下方式估算，错误会话补采样、Segment 和网络协议开销需要另外计入：

整体图片流量 ≈ 总会话分钟数 × sampleRate × 已录制会话的估算图片流量/分钟

启停¶

如果未在 guanceSdk.start() 中传入 replay，也可以在 RUM 初始化并启动 View 后单独开启：

guanceSdk.replay.start({
  sampleRate: 1,
  captureFps: 1,
  maxImageDimension: 720,
  touchPrivacy: 'show',
});

停止截帧：

guanceSdk.replay.stop();

guanceSdk.shutdown() 也会停止截帧。不要同时通过 guanceSdk.start({ replay: ... }) 和 guanceSdk.replay.start() 重复启动。

原生宿主 Hybrid 模式不使用上述启停接口。Session Replay 由原生宿主以原生 recorder 模式初始化，Cocos 在 enterCocos() 和 leaveCocos() 之间自动切换到外部捕获源，详见原生宿主 Hybrid 接入。

性能建议¶

• 从 captureFps: 1、imagePolicy: { quality: 'medium' } 开始验证；需要更连贯画面时再提高到 2 fps。
• 只在需要重放的业务环境开启采样。
• 低端设备出现 GPU、内存或磁盘压力时，优先改用 low，再降低最长边尺寸和采样率。
• 在横竖屏切换、多 Camera、复杂 UI、低帧率场景下验证图像方向与遮罩位置。

iOS 兼容性¶

如果初始化时报错：

FTMobileSDK lacks external Session Replay API

表示当前 GuanceSDK 缺少 Cocos External Replay API。请升级到支持 Cocos 的 iOS SDK 版本，重新执行 pod install 并使用 .xcworkspace 构建；升级前可以移除 replay 配置，其他 RUM、Log 和 Trace 能力不受影响。