カスタムタグの使用¶

このドキュメントでは、SDK、RUM、Log のグローバルタグ、単一イベント属性、およびユーザー情報の使用範囲について説明します。

グローバルタグの種類¶

静的グローバルタグ¶

グローバルタグは初期化時に設定されます。

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 は、実行時にグローバルタグを追加または削除するメソッドを提供していません。初期化後に変化するビジネス情報には、次の方法を選択できます：

1. 単一イベントの attributes として渡します。
2. ローカルに永続化し、次回のアプリ起動時に globalContext に追加します。
3. ユーザー身份が変わった場合は、bindUser() または unbindUser() を呼び出します。

guanceSdk.start() を繰り返し呼び出してタグを更新しないでください。再初期化すると、リスナーが重複したり、Native SDK の状態が競合したりする可能性があります。

命名と競合¶

• ビジネスタグにはプロジェクトプレフィックスを付けることをお勧めします。例：game_region、game_channel。
• app_id、session_id、view_id、service、env などの RUM 標準フィールドを上書きしないでください。
• sdk_package_cocos は使用しないでください。このフィールドには、Cocos SDK が現在の npm パッケージのバージョンを書き込みます。
• track_id は分散型トレーシングのシナリオで使用されます。明確に必要な場合のみ使用してください。
• カスタムフィールドが Native SDK の組み込みフィールドと競合する場合、最終的な値が組み込みフィールドによって上書きされる可能性があります。

すべてのタグは最小化の原則に従い、ユーザーのパスワード、Token、完全な身分証明書番号などの機密情報を避けてください。詳細はデータとプライバシーを参照してください。