遥测密钥

  • 项目

借助遥测密钥，可以通过直接从游戏客户端引入自定义遥测事件来使用 PlayFab 的强大分析功能。 现在，可以在发送遥测数据时使用 WriteTelemetryEvents API 简化客户端对 PlayFab 的身份验证。

遥测密钥是可以使用的凭据，而不是通常调用 PlayFab 实体 API 所需的实体令牌。 这意味着即使没有玩家登录，你也可以利用 PlayFab 的遥测引入功能。 更重要的是，与游戏密钥不同，遥测密钥不授予对管理 API 的访问权限；它们只能用于发送遥测数据。 可以安全地直接与游戏客户端共享遥测密钥。

使用遥测密钥

可以从 GameManager 中的Data部分的Telemetry Keys选项卡管理为游戏配置的密钥。

创建密钥后，可以通过 HTTP 标头在调用 WriteTelemetryEvents 时从游戏客户端使用它X-TelemetryKey：

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

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

注意

调用方应提供遥测密钥或实体令牌。 如果同时提供这两个密钥，则将忽略遥测密钥，并且将处理请求，就像未提供请求一样。

限制

使用“遥测密钥”时存在以下限制：

  • 游戏最多可以配置五个遥测密钥。
  • 遥测密钥只能用于通过 WriteTelemetryEvents API 发送遥测事件。 它们不能用于通过 WriteEvents API 发送 PlayStream 事件。
  • 将 见解保留期 设置为超过 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 的属性将包含用于引入事件的密钥名称。 如果已配置多个遥测密钥，则可以使用此属性查看用于引入事件的密钥。