数据与隐私¶

本文说明 Cocos Creator SDK 在 RUM、Log、Trace 和 Session Replay 中可能涉及的敏感数据边界。

基本原则¶

只采集定位性能与稳定性问题所需的数据。
不采集密码、验证码、Token、完整身份证件号码、银行卡号等敏感信息。
测试环境开启自动采集后，先检查实际上报内容，再决定生产配置。
自定义标签、日志和手动 Resource Body 均由业务负责脱敏。

Session Replay¶

默认规则¶

所有 EditBox 节点默认使用 mask。
重复帧和正在处理中的帧会被跳过。
截帧在进入 Native Bridge 前应用节点矩形遮罩。

使用 ReplayPrivacy 组件¶

对于场景或预制体中的敏感节点，优先使用 ReplayPrivacy 组件配置遮罩。Creator 2 和 Creator 3 均支持该组件。

安装 SDK 后，在 Cocos 项目根目录重新运行项目安装器：

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

安装器会按 Creator 主版本将组件脚本复制到 assets/guance-cocos-sdk/ReplayPrivacy.ts。重新打开 Cocos Creator，在目标节点的组件菜单中选择 Session Replay > ReplayPrivacy，或将脚本拖到属性检查器。
将 Mode 设置为 Mask（默认，灰色遮罩）或 Hide（黑色遮罩），并保存场景或预制体。

组件只影响 Session Replay 截帧，不改变应用中实时显示的节点。SDK 会在每次截帧时识别当前场景中有效且已启用的组件，包括运行时实例化的预制体。禁用或移除组件后，其规则不再生效；节点上的代码规则和 EditBox 默认规则仍然保留。

请保留脚本的 ReplayPrivacy 类名及 .meta 文件，避免破坏场景或预制体中的组件引用。Creator 3 的目标 UI 节点需要具有 UITransform，用于提供遮罩边界。

使用代码补充规则¶

对于不便添加组件的节点或需要动态覆盖的场景，使用 setPrivacy()：

以下 guanceSdk 指通过 withSessionReplay() 组合得到的实例。基础包自身不提供 .replay。

guanceSdk.replay.setPrivacy(passwordPanel, 'hide'); // 黑色遮罩
guanceSdk.replay.setPrivacy(playerName, 'mask'); // 灰色遮罩
guanceSdk.replay.setPrivacy(playerName, 'unmask'); // 清除代码覆盖

同一节点的规则优先级为：setPrivacy() 代码规则 > ReplayPrivacy 组件规则 > EditBox 默认遮罩。

unmask 仅清除先前设置的代码规则，随后恢复组件规则或 EditBox 默认规则，不会强制显示敏感内容。例如，节点组件设为 Hide 后，调用 setPrivacy(node, 'mask') 会改为灰色遮罩，再调用 setPrivacy(node, 'unmask') 会恢复黑色遮罩。组件的 Mode 因此仅提供 Mask 和 Hide。

使用代码管理不同页面的遮罩时，应在进入页面时设置，离开或销毁前使用 unmask 清除，重新进入时恢复。仅隐藏页面不会删除已注册的代码规则。完整示例见按页面管理遮罩。

当前 Replay 配置不提供 maskInputs 开关，EditBox 默认遮罩不能通过该字段关闭。

遮罩范围与验证¶

遮罩根据节点的世界坐标包围盒，经截帧 Camera 投影到截图中的矩形区域。若只需要遮挡某个敏感控件，应将组件加到该控件上，并让节点边界贴合目标区域。

例如，在同一页面并排放置三个敏感控件，在控件之间及四周保留公开文字或边框：

目标控件	配置方式	预期重放结果
玩家昵称	添加 `ReplayPrivacy`，Mode 为 Mask	目标矩形区域显示为灰色
账号信息	添加 `ReplayPrivacy`，Mode 为 Hide	目标矩形区域显示为黑色
动态敏感内容	调用 `setPrivacy(node, 'mask')`	目标矩形区域显示为灰色
矩形区域外的公开文字、边框	不设置隐私规则	保持可见，不被相邻控件遮罩覆盖

移动、缩放控件或其父节点，以及调整 Camera 和屏幕适配模式后，分别在 Android、iOS 原生运行环境中检查重放结果：遮罩应跟随目标位置，完整覆盖敏感内容，且不扩展到目标矩形以外的其他控件。矩形边缘会按截帧像素取整，应同时检查边缘是否存在内容泄漏或误遮挡。

遮罩边界

遮罩覆盖的是截图中的矩形区域，矩形内的子节点及其他重叠内容也会被遮挡。子节点的 unmask 不能取消父节点已经覆盖的像素，因此不要为只需局部遮挡的内容选择整个页面容器。

Shader、粒子、RenderTexture、自定义绘制、超出包围盒的内容和其他 Camera 画面不一定被覆盖。应在真机逐场景检查重放结果。

网络数据¶

开启 autoTrack.network 后会采集 URL、请求头、响应头、HTTP 方法和状态码。

需要重点检查：

URL Query 中的账号、Token 或业务 ID；
Authorization、Cookie 和自定义认证请求头；
响应头中的用户或租户信息。

当前 Cocos API 不提供 URL 或 Header 过滤回调。如果网络协议包含敏感字段，应关闭自动网络采集，并只对允许的请求使用手动 Resource 与 Trace API。

自动网络采集不读取请求 Body 和响应 Body。手动 addResource() 的 responseBody 会按业务传入内容处理，应默认不传，确有排查需要时先脱敏和截断。

Log 与 Console¶

autoTrack.console 会把 Console 参数转换为文本，可能包含：

调试 Token；
完整接口对象；
用户输入；
账号与设备标识；
异常对象中的业务数据。

生产环境建议保持 console: false，使用 guanceSdk.logger.log() 上报经过筛选的内容。

不要把敏感对象直接放入日志 attributes。对象会被 JSON 序列化后进入日志数据。

Error¶

Error Message 和 Stack 可能包含：

URL；
文件路径；
用户输入；
业务对象的字符串结果。

手动调用 addError() 前应清理消息、堆栈和属性中的敏感值。自动错误监听无法提供脱敏回调；如果应用异常内容不可控，可以关闭 autoTrack.errors，在业务错误边界中脱敏后手动上报。

用户与自定义标签¶

userId 建议使用内部不可逆标识，不使用手机号或邮箱作为 ID。
userEmail 只有业务确实需要时才传入。
extra 与所有 globalContext 只添加低敏感、稳定、可用于筛选的标签。
不把高基数字段或每次请求都变化的内容设置为全局标签。

Trace Header¶

Trace Header 只应注入信任的业务域名。第三方域名可能接收到 Trace 标识，从而暴露内部追踪关系。自动网络追踪无法按域名过滤时，应改用 trace.getHeaders() 手动控制注入范围。

发布前检查¶

在真机覆盖登录、支付、聊天、账号设置等敏感场景。
检查 RUM Resource 的 URL 与 Header。
检查 Error Message、Stack 和自定义属性。
检查 Console 和自定义日志。
回放 Session Replay，确认输入框和自定义敏感区域已遮罩。
检查 Trace Header 只发送到允许的域名。