Telemetrieschlüssel

Mit Telemetrieschlüsseln können Sie die leistungsstarken Analysefunktionen von PlayFab nutzen, indem Sie benutzerdefinierte Telemetrieereignisse direkt aus Ihrem Spielclient erfassen. Sie können jetzt die WriteTelemetryEvents-API verwenden, um die Authentifizierung Ihres Clients bei PlayFab beim Senden von Telemetriedaten zu vereinfachen.

Ein Telemetrieschlüssel ist eine Anmeldeinformation, die anstelle des Entitätstokens verwendet werden kann, das normalerweise zum Aufrufen der PlayFab-Entitäts-APIs erforderlich ist. Dies bedeutet, dass Sie die Telemetrieerfassungsfunktionen von PlayFab auch dann nutzen können, wenn Sie keinen Spieler angemeldet haben. Darüber hinaus gewähren Telemetrieschlüssel im Gegensatz zu Title Secret-Schlüsseln keinen Zugriff auf Administrative APIs. sie können nur zum Senden von Telemetriedaten verwendet werden. Sie können Telemetrieschlüssel sicher direkt für Ihre Spielclients freigeben.

Verwenden von Telemetrieschlüsseln

Sie können die für Ihren Titel konfigurierten Schlüssel über die Telemetry Keys Registerkarte im Data Abschnitt in GameManager verwalten.

Nachdem Sie einen Schlüssel erstellt haben, können Sie ihn über Ihren Spielclient verwenden, wenn Sie WriteTelemetryEvents aufrufen, indem Sie ihn über den HTTP-Header X-TelemetryKeyeinschließen:

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

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

Notiz

Der Aufrufer sollte entweder einen Telemetrieschlüssel oder ein Entitätstoken bereitstellen. Wenn beides angegeben wird, wird der Telemetrieschlüssel ignoriert, und die Anforderung wird so verarbeitet, als ob kein Telemetrieschlüssel angegeben wäre.

Einschränkungen

Bei Verwendung von Telemetrieschlüsseln gelten die folgenden Einschränkungen:

• Ein Titel kann bis zu fünf Telemetrieschlüssel konfigurieren.
• Telemetrieschlüssel können nur zum Senden von Telemetrieereignissen über die WriteTelemetryEvents-API verwendet werden. Sie können nicht zum Senden von PlayStream-Ereignissen über die WriteEvents-API verwendet werden.
• Titel, die ihre Insights-Aufbewahrungsdauer auf mehr als 30 Tage festgelegt haben, können zurzeit keine Telemetrieschlüssel konfigurieren.

Angeben von Entitäten für Ereignisse

PlayFab-Ereignisse geben den Betreff des Ereignisses über ihre Entity -Eigenschaft an. Wenn Sie Telemetriedaten mithilfe der Entitätstokenauthentifizierung senden, wird dieses Feld automatisch mit Informationen zur angemeldeten Entität aufgefüllt. Wenn Sie jedoch einen Telemetrieschlüssel verwenden, ist keine Entität angemeldet. Telemetrieereignisse, die mit einem Telemetrieschlüssel gesendet werden, dürfen daher nicht PlayFab Built-In Entitäten als Betreff angeben.

Wenn Sie Telemetrieschlüssel verwenden, können Sie Ihre Telemetrieereignisse einem Thema zuordnen, z. B. einem benutzerdefinierten Spielerbezeichner, der in Ihrem Spiel verwendet wird. Zu diesem Ziel können Sie beim Erstellen der Ereignisse in Ihrem Client eine externe Entität angeben.

Externe Entitäten sind einfach Entitäten, die Sie mit type auf festlegen external. Sie sind formal nicht Teil des Entitätssystems von PlayFab. Sie werden nur in diesem Kontext verwendet, um einen bequemen Mechanismus zum Zuordnen von Telemetrieereignissen mit Antragstellerbezeichnern bereitzustellen, die in Ihrem System sinnvoll sind.

Wenn Sie beim Erstellen des Ereignisses in Ihrem Code eine externe Entität als Betreff angeben möchten, sollten Sie:

1. Legen Sie das Feld des Ereignisses Entity.type auf fest external (Groß-/Kleinschreibung beachten).
2. Legen Sie das Feld des Ereignisses Entity.id auf Ihren benutzerdefinierten Antragstellerbezeichner fest, der maximal 64 Zeichen lang ist.

Hier ist ein Beispiel, das zeigt, wie ein Ereignis gesendet wird, das eine externe Entität angibt:

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

Nachdem das Ereignis von PlayFab erfasst wurde, sieht es wie folgt aus:

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

Notiz

Die OriginInfo.Key -Eigenschaft des Ereignisses enthält den Namen des Schlüssels, der zum Erfassen des Ereignisses verwendet wurde. Wenn Sie mehrere Telemetrieschlüssel konfiguriert haben, können Sie diese Eigenschaft verwenden, um zu sehen, welcher Schlüssel zum Erfassen des Ereignisses verwendet wurde.