Telemetry Keys - XBOX Game Development Documentation

Telemetry Keys를 사용하면 게임 클라이언트에서 사용자 지정 원격 분석 이벤트를 직접 수집하여 PlayFab의 강력한 분석 기능을 사용할 수 있습니다. 이제 WriteTelemetryEvents API를 사용하여 원격 분석을 전송할 때 클라이언트의 PlayFab에 대한 인증을 간소화할 수 있습니다. Telemetry Key는 일반적으로 PlayFab Entity API를 호출하는 데 필요한 Entity Token 대신 사용할 수 있는 자격 증명입니다. 즉, 플레이어가 로그인되어 있지 않아도 PlayFab의 원격 분석 수집 기능을 활용할 수 있습니다. 게다가 Title Secret 키와 달리 Telemetry Keys는 관리 API에 대한 액세스 권한을 부여하지 않습니다. 원격 분석을 보내는 용도로만 사용할 수 있습니다. Telemetry Keys는 게임 클라이언트와 직접 안전하게 공유할 수 있습니다.

Telemetry Keys 사용하기

Game Manager의 Data 섹션에 있는 Telemetry Keys 탭에서 타이틀에 구성된 키를 관리할 수 있습니다. 키를 만들면 WriteTelemetryEvents를 호출할 때 HTTP 헤더 X-TelemetryKey를 통해 포함시켜 게임 클라이언트에서 사용할 수 있습니다.

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

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

호출자는 Telemetry Key 또는 Entity Token 중 하나를 제공해야 합니다. 둘 다 제공되면 Telemetry Key는 무시되고, 요청은 마치 제공되지 않은 것처럼 처리됩니다.

제한 사항

Telemetry Keys를 사용할 때 다음 제한이 적용됩니다.

타이틀은 최대 5개의 Telemetry Keys를 구성할 수 있습니다.
Telemetry Keys는 WriteTelemetryEvents API를 통해 원격 분석 이벤트를 보내는 데만 사용할 수 있습니다. WriteEvents API를 통해 PlayStream 이벤트를 보내는 데는 사용할 수 없습니다.
Insights Retention이 30일보다 크게 설정된 타이틀은 현재 Telemetry Keys를 구성할 수 없습니다.

이벤트에 대한 Entity 지정

PlayFab 이벤트는 Entity 속성을 통해 이벤트의 주체를 나타냅니다. Entity Token 인증을 사용하여 원격 분석을 보내면 이 필드는 로그인된 엔터티에 대한 정보로 자동 채워집니다. 그러나 Telemetry Key를 사용하면 로그인된 엔터티가 없습니다. 따라서 Telemetry Key를 사용하여 전송된 원격 분석 이벤트는 주체로 PlayFab 기본 제공 엔터티를 지정할 수 없습니다. Telemetry Keys를 사용할 때에도 게임에서 사용하는 사용자 지정 플레이어 식별자와 같이 원격 분석 이벤트를 특정 주체와 연결하고 싶을 수 있습니다. 이를 위해 클라이언트에서 이벤트를 구성할 때 외부 엔터티를 지정할 수 있습니다. 외부 엔터티는 단순히 type을 external로 지정한 엔터티입니다. 이는 공식적으로 PlayFab의 엔터티 시스템의 일부가 아닙니다. 이 컨텍스트에서만 사용되며, 시스템에서 의미 있는 주체 식별자와 원격 분석 이벤트를 연결하는 편리한 메커니즘을 제공합니다. 코드에서 이벤트를 구성할 때 외부 엔터티를 주체로 지정하려면 다음을 수행합니다.

이벤트의 Entity.type 필드를 external(대소문자 구분)로 설정합니다.
이벤트의 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 속성에는 이벤트를 수집하는 데 사용된 키의 이름이 포함됩니다. 여러 Telemetry Keys를 구성한 경우, 이 속성을 사용하여 어떤 키가 이벤트를 수집하는 데 사용되었는지 확인할 수 있습니다.

​Telemetry Keys 사용하기

​제한 사항

​이벤트에 대한 Entity 지정

Telemetry Keys 사용하기

제한 사항

이벤트에 대한 Entity 지정