Claves de telemetría - XBOX Game Development Documentation

Las claves de telemetría le permiten usar las eficaces capacidades de análisis de PlayFab mediante la ingesta de eventos de telemetría personalizados directamente desde el cliente del juego. Ahora puede usar la API WriteTelemetryEvents para simplificar la autenticación del cliente en PlayFab al enviar telemetría. Una clave de telemetría es una credencial que se puede usar en lugar del token de entidad que normalmente se requiere para llamar a las API de entidad de PlayFab. Esto significa que puede utilizar las capacidades de ingesta de telemetría de PlayFab incluso si no hay un jugador con sesión iniciada. Además, a diferencia de las claves secretas del título, las claves de telemetría no conceden acceso a las API administrativas; solo se pueden usar para enviar telemetría. Puede compartir las claves de telemetría directamente con los clientes del juego de forma segura.

Uso de las claves de telemetría

Puede administrar las claves configuradas para su título desde la pestaña Telemetry Keys en la sección Data de GameManager. Una vez creada una clave, puede usarla desde el cliente del juego al llamar a WriteTelemetryEvents incluyéndola mediante el encabezado HTTP X-TelemetryKey:

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

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

El autor de la llamada debe proporcionar una clave de telemetría O un token de entidad. Si se proporcionan ambos, la clave de telemetría se omitirá y la solicitud se procesará como si no se hubiera proporcionado.

Limitaciones

Se aplican las siguientes restricciones al usar claves de telemetría:

Un título puede configurar hasta cinco claves de telemetría.
Las claves de telemetría solo se pueden usar para enviar eventos de telemetría mediante la API WriteTelemetryEvents. No se pueden usar para enviar eventos de PlayStream mediante la API WriteEvents.
Los títulos que hayan establecido su retención de Insights en más de 30 días no pueden configurar claves de telemetría en este momento.

Especificación de entidades para los eventos

Los eventos de PlayFab indican el sujeto del evento mediante su propiedad Entity. Cuando envía telemetría mediante la autenticación con token de entidad, este campo se rellena automáticamente con información sobre la entidad con sesión iniciada. Sin embargo, cuando usa una clave de telemetría, no hay ninguna entidad con sesión iniciada. Por lo tanto, los eventos de telemetría enviados con una clave de telemetría no pueden especificar entidades integradas de PlayFab como sujeto. Al usar claves de telemetría, es posible que aun así quiera asociar los eventos de telemetría con algún sujeto, por ejemplo, un identificador de jugador personalizado que se use en su juego. Para ello, puede especificar una entidad externa al formar los eventos en el cliente. Las entidades externas son simplemente entidades que se especifican con type establecido en external. No forman parte formalmente del sistema de entidades de PlayFab. Solo se usan en este contexto para proporcionar un mecanismo cómodo para asociar los eventos de telemetría con identificadores de sujeto que tengan sentido en su sistema. Para especificar una entidad externa como sujeto al formar el evento en el código, debe:

Establecer el campo Entity.type del evento en external (distingue mayúsculas de minúsculas).
Establecer el campo Entity.id del evento en su identificador de sujeto personalizado, con una longitud máxima de 64 caracteres.

Este es un ejemplo que muestra cómo enviar un evento que especifica una entidad externa:

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

Una vez que PlayFab ingiere el evento, tiene este aspecto:

"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 propiedad OriginInfo.Key del evento contendrá el nombre de la clave que se usó para ingerir el evento. Si ha configurado varias claves de telemetría, puede usar esta propiedad para ver qué clave se usó para ingerir el evento.

​Uso de las claves de telemetría

​Limitaciones

​Especificación de entidades para los eventos

Uso de las claves de telemetría

Limitaciones

Especificación de entidades para los eventos