Using Custom Tags¶

This document describes the usage boundaries for SDK, RUM, and Log global tags, single event attributes, and user information.

Global Tag Types¶

Static Global Tags¶

Global tags are set during initialization:

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',
    },
  },
});

Global tag values must be strings. If you need to represent numeric or boolean values, convert them to strings on the business side first.

Single Event Attributes¶

The attributes of the manual RUM and Log APIs support:

• strings;
• numbers;
• booleans;
• null;
• arrays of the above types;
• JSON objects.

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,
  },
});

Do not pass functions, Cocos Nodes, Cameras, circularly referenced objects, or other values that cannot be serialized to JSON.

User Information¶

Bind the user after login:

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

Unbind the user after logout:

guanceSdk.mobile.unbindUser();

userId cannot be an empty string. extra only supports string key-value pairs.

Dynamic Tags¶

The current Cocos API does not provide a method to add or remove global tags at runtime. For business information that changes after initialization, you can:

1. Pass it as attributes of a single event;
2. Persist it locally and add it to globalContext on the next app startup;
3. Call bindUser() or unbindUser() when user identity changes.

Do not update tags by calling guanceSdk.start() repeatedly. Repeated initialization may cause duplicate listeners or Native SDK state conflicts.

Naming and Conflicts¶

• It is recommended to prefix business tags with a project prefix, for example game_region, game_channel.
• Do not override RUM standard fields such as app_id, session_id, view_id, service, and env.
• Do not use sdk_package_cocos; this field is populated by the Cocos SDK with the current npm package version.
• track_id is used for distributed tracing scenarios; use it only when explicitly required.
• If a custom field conflicts with a field built into the Native SDK, the final value may be overwritten by the built-in field.

All tags should follow the data minimization principle and avoid sensitive content such as user passwords, tokens, and full ID card numbers. For more details, see Data and Privacy.