원격 분석 키

아티클
10/14/2023

원격 분석 키를 사용하면 게임 클라이언트에서 직접 사용자 지정 원격 분석 이벤트를 수집하여 PlayFab의 강력한 분석 기능을 사용할 수 있습니다. 이제 WriteTelemetryEvents API를 사용하여 원격 분석을 보낼 때 PlayFab에 대한 클라이언트의 인증을 간소화할 수 있습니다.

원격 분석 키는 PlayFab 엔터티 API를 호출하는 데 일반적으로 필요한 엔터티 토큰 대신 사용할 수 있는 자격 증명입니다. 즉, 플레이어가 로그인하지 않은 경우에도 PlayFab의 원격 분석 수집 기능을 활용할 수 있습니다. 또한 타이틀 비밀 키와 달리 원격 분석 키는 관리 API에 대한 액세스 권한을 부여하지 않습니다. 원격 분석을 보내는 데만 사용할 수 있습니다. 원격 분석 키를 게임 클라이언트와 직접 안전하게 공유할 수 있습니다.

원격 분석 키 사용

GameManager의 Data 섹션 아래 Telemetry Keys 탭에서 타이틀에 대해 구성된 키를 관리할 수 있습니다.

키를 만든 후에는 HTTP 헤더 X-TelemetryKey를 통해 키를 포함하여 WriteTelemetryEvents를 호출할 때 게임 클라이언트에서 키를 사용할 수 있습니다.

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

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

참고 항목

호출자는 원격 분석 키 또는 엔터티 토큰을 제공해야 합니다. 둘 다 제공되면 원격 분석 키가 무시되고 요청이 원격 분석 키가 제공되지 않은 것처럼 처리됩니다.

제한 사항

원격 분석 키를 사용할 때 적용되는 제한 사항은 다음과 같습니다.

타이틀은 최대 5개의 원격 분석 키를 구성할 수 있습니다.
원격 분석 키는 WriteTelemetryEvents API를 통해 원격 분석 이벤트를 보내는 데만 사용할 수 있습니다. WriteEvents API를 통해 PlayStream 이벤트를 보내는 데 사용할 수 없습니다.
Insights 보존 기간을 30일 이상으로 설정한 타이틀은 현재 원격 분석 키를 구성할 수 없습니다.

이벤트에 대한 엔터티 지정

PlayFab 이벤트는 Entity 속성을 통해 이벤트의 제목을 나타냅니다. 엔터티 토큰 인증을 사용하여 원격 분석을 보내면 이 필드는 로그인한 엔터티에 대한 정보로 자동으로 채워집니다. 그러나 원격 분석 키를 사용하는 경우에는 로그인된 엔터티가 없습니다. 따라서 원격 분석 키를 사용하여 전송된 원격 분석 이벤트는 PlayFab 기본 제공 엔터티를 해당 주체로 지정할 수 없습니다.

원격 분석 키를 사용하는 경우 원격 분석 이벤트를 일부 주체(예: 게임에서 사용되는 사용자 지정 플레이어 식별자)와 연결하려고 할 수 있습니다. 이렇게 하려면 클라이언트에서 이벤트를 구성할 때 외부 엔터티를 지정할 수 있습니다.

외부 엔터티는 external로 설정된 type을 사용하여 지정하는 엔터티일 뿐입니다. 공식적으로 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 속성에는 이벤트를 수집하는 데 사용된 키의 이름이 포함됩니다. 여러 원격 분석 키를 구성한 경우 이 속성을 사용하여 이벤트를 수집하는 데 사용된 키를 확인할 수 있습니다.

다음을 통해 공유

원격 분석 키

원격 분석 키 사용

제한 사항

이벤트에 대한 엔터티 지정

추가 리소스