Clés de télémétrie - XBOX Game Development Documentation

Les clés de télémétrie (Telemetry Keys) vous permettent d’exploiter les puissantes capacités d’analytique de PlayFab en ingérant des événements de télémétrie personnalisés directement depuis votre client de jeu. Vous pouvez désormais utiliser l’API WriteTelemetryEvents pour simplifier l’authentification de votre client auprès de PlayFab lors de l’envoi de télémétrie. Une clé de télémétrie est une information d’identification qui peut être utilisée à la place du jeton d’entité (Entity Token) normalement requis pour appeler les API d’entité PlayFab. Cela signifie que vous pouvez utiliser les capacités d’ingestion de télémétrie de PlayFab même si aucun joueur n’est connecté. De plus, contrairement aux clés secrètes de titre (Title Secret), les clés de télémétrie n’accordent pas l’accès aux API d’administration ; elles ne peuvent être utilisées que pour envoyer de la télémétrie. Vous pouvez partager en toute sécurité les clés de télémétrie directement avec vos clients de jeu.

Utilisation des clés de télémétrie

Vous pouvez gérer les clés configurées pour votre titre à partir de l’onglet Telemetry Keys de la section Data dans GameManager. Une fois que vous avez créé une clé, vous pouvez l’utiliser depuis votre client de jeu lors de l’appel à WriteTelemetryEvents en l’incluant via l’en-tête HTTP X-TelemetryKey :

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

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

L’appelant doit fournir soit une clé de télémétrie, SOIT un jeton d’entité. Si les deux sont fournis, la clé de télémétrie est ignorée et la requête est traitée comme si aucune clé n’avait été fournie.

Limitations

Les restrictions suivantes s’appliquent lors de l’utilisation des clés de télémétrie :

Un titre peut configurer jusqu’à cinq clés de télémétrie.
Les clés de télémétrie ne peuvent être utilisées que pour envoyer des événements de télémétrie via l’API WriteTelemetryEvents. Elles ne peuvent pas être utilisées pour envoyer des événements PlayStream via l’API WriteEvents.
Les titres dont la rétention Insights est définie sur plus de 30 jours ne peuvent pas configurer de clés de télémétrie pour le moment.

Spécification des entités pour les événements

Les événements PlayFab indiquent le sujet de l’événement via leur propriété Entity. Lorsque vous envoyez de la télémétrie à l’aide de l’authentification par jeton d’entité, ce champ est automatiquement renseigné avec des informations sur l’entité connectée. Toutefois, lorsque vous utilisez une clé de télémétrie, aucune entité n’est connectée. Les événements de télémétrie envoyés à l’aide d’une clé de télémétrie ne sont donc pas autorisés à spécifier des entités intégrées PlayFab comme sujet. Lorsque vous utilisez des clés de télémétrie, vous pouvez quand même vouloir associer vos événements de télémétrie à un sujet, par exemple un identifiant de joueur personnalisé utilisé dans votre jeu. Pour ce faire, vous pouvez spécifier une entité externe lors de la formation des événements dans votre client. Les entités externes sont simplement des entités que vous spécifiez avec type défini sur external. Elles ne font pas formellement partie du système d’entités de PlayFab. Elles ne sont utilisées dans ce contexte que pour fournir un mécanisme pratique permettant d’associer des événements de télémétrie à des identifiants de sujet pertinents dans votre système. Pour spécifier une entité externe comme sujet lors de la formation de l’événement dans votre code, vous devez :

Définir le champ Entity.type de l’événement sur external (sensible à la casse).
Définir le champ Entity.id de l’événement sur votre identifiant de sujet personnalisé, d’une longueur maximale de 64 caractères.

Voici un exemple qui montre comment envoyer un événement spécifiant une entité externe :

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
      }
    }
  ]
}

Une fois l’événement ingéré par PlayFab, il se présente ainsi :

"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
    } 
} 

La propriété OriginInfo.Key de l’événement contient le nom de la clé utilisée pour ingérer l’événement. Si vous avez configuré plusieurs clés de télémétrie, vous pouvez utiliser cette propriété pour savoir quelle clé a été utilisée pour ingérer l’événement.

​Utilisation des clés de télémétrie

​Limitations

​Spécification des entités pour les événements

Utilisation des clés de télémétrie

Limitations

Spécification des entités pour les événements