事件、属性、用户身份与同意管理

事件命名

业务事件使用稳定、可读的英文 CODE，例如：

signup_completed
order_created
invoice_paid

• 建议使用小写蛇形命名，并采用“对象 + 完成动作”。
• 业务事件不能以 $ 开头；该前缀保留给 SDK 自动事件，如 $page_view、$identify、$screen_view。
• 不要把订单号、用户 ID 等高基数字段拼进事件名，应放入属性。
• 同一个事件名在不同端应保持同一触发语义。

属性类型

推荐属性示例：

{
  "order_id": "order-1001",
  "amount": 199,
  "paid": true,
  "coupon": null,
  "tags": ["new-user", "campaign-a"],
  "item": {
    "sku": "sku-42",
    "category": "book"
  }
}

属性支持字符串、数字、布尔值、null、标量数组，以及一层标量对象。属性名保持稳定，不要在不同事件中让同名属性混用数字和字符串。

用户与匿名身份

• SDK 会维护匿名访客和会话 ID。
• 业务登录态就绪后调用 identify，使用稳定的内部用户主键。
• 页面刷新或应用重新初始化后，如用户仍登录，应再次调用 identify。
• 用户退出登录时调用 reset，开始新的匿名身份和会话。
• 不要使用邮箱、手机号、昵称、访问 Token 或 Session ID 作为 user_id。

Go 服务端事件的 UserID 必须来自可信登录态。Browser 产生的 identity_context 只用于统计关联；后端不得解码、记录、鉴权或用它覆盖可信 UID。

同意状态

状态	行为
pending	等待业务取得用户授权，不发送数据
grant	开始采集并发送队列
deny	停止采集并清空队列
revoke	撤回授权，清空队列和本地身份状态

Browser 默认是 grant；Android、iOS 和小程序默认是 pending。宿主应用负责根据隐私政策和适用法规选择初始状态，并把 CMP、ATT 或隐私设置的变化同步给 SDK。

密钥与数据安全

• pk_… 只用于 Browser，sk_… 只用于 Go 服务端，ck_… 只用于移动端和小程序。
• Server Key 是秘密；使用密钥管理系统或部署环境变量保存。
• SDK 的客户端批次采用 HPKE 加密。公钥发现或加密失败时不会降级成明文。
• 不上报密码、Cookie、Token、完整支付凭据、非必要手机号/邮箱或其他敏感信息。
• 日志可记录事件名、SDK 版本、HTTP 状态和错误类别，不要记录密钥、identity_context 或完整身份标识。

环境一致性

密钥、来源白名单、客户端登记和查看实时事件必须来自同一个项目环境。测试代码使用 staging 密钥时，要在 staging 实时页验证；跨环境不会自动合并数据。