テレメトリ キー

  • [アーティクル]

テレメトリ キーを使用すると、カスタム テレメトリ イベントをゲーム クライアントから直接取り込むことで、PlayFab の強力な分析機能を使用できます。 WriteTelemetryEvents API を使用して、テレメトリを送信するときに PlayFab に対するクライアントの認証を簡略化できるようになりました。

テレメトリ キーは、PlayFab エンティティ API を呼び出すために通常必要なエンティティ トークンの代わりに使用できる資格情報です。 つまり、プレイヤーがサインインしていない場合でも、PlayFab のテレメトリ取り込み機能を利用できます。 さらに、タイトル シークレット キーとは異なり、テレメトリ キーは管理 API へのアクセスを許可しません。は管理 API はテレメトリの送信にのみ使用できます。 テレメトリ キーは、ゲーム クライアントと安全に直接共有できます。

テレメトリ キーの使用

タイトル用に構成されたキーは、GameManager のセクションの Data の下にある Telemetry Keys タブから管理できます。

キーを作成したら、HTTP ヘッダー X-TelemetryKey を介してキーを含めることで WriteTelemetryEvents を呼び出すときに、ゲーム クライアントからキーを使用できます。

POST https://<titleId>.playfabapi.com/Event/WriteTelemetryEvents
X-TelemetryKey: <Your Telemetry Key>

{
  "Events": [
    <Your Events>
  ]
}

注意

呼び出し元は、テレメトリ キーまたはエンティティ トークンを指定する必要があります。 両方が指定されている場合、テレメトリ キーは無視され、テレメトリ キーが指定されていないかのように要求が処理されます。

制限事項

テレメトリ キーを使用するときには、次の制限が適用されます。

  • 1 つのタイトルでは、最大 5 つのテレメトリ キーを構成できます。
  • テレメトリ キーは、WriteTelemetryEvents API を介してテレメトリ イベントを送信するためにのみ使用できます。 WriteEvents API を介して PlayStream イベントを送信するために使用することはできません。
  • Insights の保存期間が 30 日を超えて設定されているタイトルは、現時点ではテレメトリ キーを構成できません。

イベントのエンティティの指定

PlayFab イベントは、Entity プロパティを介してイベントのサブジェクトを示します。 エンティティ トークン認証を使用してテレメトリを送信すると、サインインしたエンティティに関する情報がこのフィールドに自動的に入力されます。 ただし、テレメトリ キーを使用する場合、サインインしたエンティティはありません。 そのため、テレメトリ キーを使用して送信されたテレメトリ イベントでは、PlayFab 組み込みエンティティ をサブジェクトとして指定することはできません。

テレメトリ キーを使用する場合でも、ゲームで使用されるカスタム プレイヤー識別子などのいくつかのサブジェクトにテレメトリ イベントを関連付ける必要がある場合があります。 これを行うには、クライアントでイベントを形成するときに外部エンティティを指定できます。

外部エンティティは、type を external に設定して指定する単なるエンティティです。 これらは、正式には PlayFab のエンティティ システムの一部ではありません。 これらは、このコンテキストでのみ使用され、システム内で意味のあるサブジェクト識別子にテレメトリ イベントを関連付けるための便利なメカニズムが提供されます。

コード内でイベントを形成するときに、外部エンティティをサブジェクトとして指定するには、次の手順を実行する必要があります。

  1. イベントの Entity.type フィールドを external に設定します (大文字と小文字が区別されます)。
  2. イベントの Entity.id フィールドをカスタム サブジェクト識別子に設定します。長さは最大 64 文字です。

外部エンティティを指定するイベントを送信する方法を示す例を次に示します。

POST https://<titleId>.playfabapi.com/Event/WriteTelemetryEvents
X-TelemetryKey: <Your Telemetry Key>

{
  "Events": [
    {
      "EventNamespace": "custom.MyCustomEventNS",
      "Name": "MyCustomEvent",
      "Entity": {
        "type": "external",
        "id": "<CUSTOM_ID>"
      },
      "Payload": {
         "MyCustomPayloadField": "MyCustomValue",
         "MyCustomScoreValue": 12345
      }
    }
  ]
}

PlayFab によってイベントが取り込まれると、次のようになります。

"EventData": { 
    "SchemaVersion": "2.0.1", 
    "Id": "9bb3a96d0faa4e2d9f74b6c166a44676", 
    "Timestamp": "2022-09-27T19:42:21.7427679Z", 
    "FullName": { 
        "Namespace": "custom.MyCustomEventNS", 
        "Name": "MyCustomEvent" 
    }, 
    "Entity": { 
        "Type": "external",
        "Id": "<CUSTOM_ID>"
    }, 
    "EntityLineage": { 
        "namespace": "B85A7CFE2803D5A2",
        "title": "A5F3",
        "externalId": "<CUSTOM_ID>"
    }, 
    "OriginInfo": { 
        "Timestamp": "2022-09-27T19:42:21.1560000Z",
        "Key": "<NAME_OF_YOUR_TELEMETRY_KEY>"
    }, 
    "PayloadContentType": "Json", 
    "Payload": { 
        "MyCustomPayloadField": "MyCustomValue",
        "MyCustomScoreValue": 12345
    } 
}

注意

イベントの OriginInfo.Key プロパティには、イベントの取り込みに使用されたキーの名前が含まれます。 複数のテレメトリ キーを構成した場合、このプロパティを使用して、イベントの取り込みに使用されたキーを確認できます。