自定义标签使用¶

本文说明 SDK、RUM、Log 全局标签，单条事件属性和用户信息的使用边界。

全局标签类型¶

作用域	配置位置	值类型	生效范围
SDK	`sdk.globalContext`	`Record<string, string>`	Native SDK 基础数据
RUM	`rum.globalContext`	`Record<string, string>`	所有 RUM 事件
Log	`logger.globalContext`	`Record<string, string>`	所有日志
单条事件	RUM/Log API 的 `attributes`	JSON 可序列化值	当前事件
用户	`guanceSdk.mobile.bindUser()`	字符串字段	当前绑定用户

静态全局标签¶

全局标签在初始化时设置：

guanceSdk.start({
  sdk: {
    datakitUrl: 'https://your-datakit.example.com',
    globalContext: {
      game_channel: 'app-store',
      build_flavor: 'release',
    },
  },
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
    globalContext: {
      game_mode: 'ranked',
    },
  },
  logger: {
    enableCustomLog: true,
    globalContext: {
      log_source: 'cocos',
    },
  },
});

全局标签值必须是字符串。需要表达数值或布尔值时，在业务侧先转换为字符串。

单条事件属性¶

RUM 和 Log 手动 API 的 attributes 支持：

字符串；
数值；
布尔值；
null；
上述类型组成的数组；
JSON 对象。

guanceSdk.rum.addAction('Purchase', 'click', {
  product_id: 'sword-001',
  price: 9.9,
  success: true,
  tags: ['shop', 'weapon'],
});

guanceSdk.logger.log('purchase completed', 'info', {
  product_id: 'sword-001',
  result: {
    currency: 'CNY',
    amount: 9.9,
  },
});

不要传入函数、Cocos Node、Camera、循环引用对象或其他无法 JSON 序列化的值。

用户信息¶

用户登录后绑定：

guanceSdk.mobile.bindUser({
  userId: 'user-123',
  userName: '玩家昵称',
  userEmail: 'player@example.com',
  extra: {
    membership: 'gold',
  },
});

用户退出登录后解绑：

guanceSdk.mobile.unbindUser();

userId 不能为空字符串。extra 只支持字符串键值。

动态标签¶

当前 Cocos API 不提供运行时追加或删除全局标签的方法。初始化后发生变化的业务信息可选择：

作为单条事件 attributes 传入；
持久化到本地，在下次应用启动时加入 globalContext；
用户身份变化时调用 bindUser() 或 unbindUser()。

不要通过重复调用 guanceSdk.start() 更新标签，重复初始化可能产生重复监听器或 Native SDK 状态冲突。

命名与冲突¶

建议为业务标签加项目前缀，例如 game_region、game_channel。
不要覆盖 RUM 标准字段，如 app_id、session_id、view_id、service、env。
不要使用 sdk_package_cocos，该字段由 Cocos SDK 写入当前 npm 包版本。
track_id 用于链路追踪场景，只有明确需要时使用。
如果自定义字段与 Native SDK 内置字段冲突，最终值可能被内置字段覆盖。

所有标签都应遵循最小化原则，避免用户密码、Token、完整身份证件号码等敏感内容。详见数据与隐私。