Chaves de telemetria - XBOX Game Development Documentation

As chaves de telemetria permitem que você use os poderosos recursos de análise do PlayFab ingerindo eventos de telemetria personalizados diretamente do cliente do jogo. Agora você pode usar a API WriteTelemetryEvents para simplificar a autenticação do seu cliente no PlayFab ao enviar telemetria. Uma chave de telemetria é uma credencial que pode ser usada no lugar do Entity Token normalmente necessário para chamar as APIs de Entidade do PlayFab. Isso significa que você pode utilizar os recursos de ingestão de telemetria do PlayFab mesmo que não haja um jogador conectado. Além disso, ao contrário das chaves Title Secret, as chaves de telemetria não concedem acesso a APIs administrativas; elas só podem ser usadas para enviar telemetria. Você pode compartilhar com segurança as chaves de telemetria diretamente com os clientes do jogo.

Usar chaves de telemetria

Você pode gerenciar as chaves configuradas para o seu title na guia Telemetry Keys da seção Data no GameManager. Depois de criar uma chave, você pode usá-la no cliente do jogo ao chamar WriteTelemetryEvents, incluindo-a por meio do cabeçalho HTTP X-TelemetryKey:

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

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

O chamador deve fornecer uma chave de telemetria OU um Entity Token. Se ambos forem fornecidos, a chave de telemetria será ignorada e a solicitação será processada como se ela não tivesse sido fornecida.

Limitações

As seguintes restrições se aplicam ao usar chaves de telemetria:

Um title pode configurar até cinco chaves de telemetria.
As chaves de telemetria só podem ser usadas para enviar eventos de telemetria por meio da API WriteTelemetryEvents. Elas não podem ser usadas para enviar eventos do PlayStream por meio da API WriteEvents.
Titles que definiram sua Retenção do Insights como superior a 30 dias não podem configurar chaves de telemetria no momento.

Especificar entidades para eventos

Os eventos do PlayFab indicam o assunto do evento por meio da propriedade Entity. Quando você envia telemetria usando a autenticação por Entity Token, esse campo é preenchido automaticamente com informações sobre a entidade conectada. No entanto, quando você usa uma chave de telemetria, não há nenhuma entidade conectada. Portanto, os eventos de telemetria enviados usando uma chave de telemetria não têm permissão para especificar Entidades Internas do PlayFab como assunto. Ao usar chaves de telemetria, talvez você ainda queira associar seus eventos de telemetria a algum assunto, por exemplo, um identificador de jogador personalizado usado no seu jogo. Para fazer isso, você pode especificar uma entidade externa ao formar os eventos no seu cliente. Entidades externas são simplesmente entidades que você especifica com type definido como external. Elas não fazem parte formalmente do sistema de entidades do PlayFab. Elas são usadas apenas nesse contexto para fornecer um mecanismo conveniente de associar eventos de telemetria a identificadores de assunto que façam sentido no seu sistema. Para especificar uma entidade externa como assunto ao formar o evento no seu código, você deve:

Definir o campo Entity.type do evento como external (diferencia maiúsculas de minúsculas).
Definir o campo Entity.id do evento como seu identificador de assunto personalizado, com no máximo 64 caracteres.

Veja um exemplo que mostra como enviar um evento que especifica uma entidade 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
      }
    }
  ]
}

Depois que o evento é ingerido pelo PlayFab, ele fica assim:

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

A propriedade OriginInfo.Key do evento conterá o nome da chave usada para ingerir o evento. Se você tiver configurado várias chaves de telemetria, poderá usar essa propriedade para ver qual chave foi usada para ingerir o evento.

​Usar chaves de telemetria

​Limitações

​Especificar entidades para eventos

Usar chaves de telemetria

Limitações

Especificar entidades para eventos