다음을 통해 공유


초기화가 가능한 통계 및 순위표 사용

이 자습서는 통계와, 확장을 통한 순위표의 재설정을 지원하는 버전 지정 관련 통계를 구성 및 관리하는 완전한 연습을 제공합니다.

관리자 API 메서드를 사용하는 방법에 초점을 맞추며, 클라이언트 및 서버 API 메서드를 사용하여 현재 버전과 이전 버선에 대한 데이터를 쿼리하는 방법에 대한 추가 정보를 제공합니다.

PlayFab에서 다시 설정 가능한 통계의 작동 방식과 게임에서 이를 사용할 수 있는 모든 방법에 대한 기술 리뷰를 제공하는 것이 목표입니다.

통계 및 순위표

먼저, PlayFab에서 게임의 플레이어에 대해 정의된 모든 통계가 순위표의 일부임을 인지하는 것이 중요합니다. 따라서 통계를 정의하면 순위표 또한 정의하는 것입니다.

통계는 반드시 플레이어에게 표시되지 않을 수 있지만, 여전히 존재합니다. 통계를 사용하여 모든 점수 중 상위 점수, 하위 점수, 현재 플레이어 주위의 점수, 또는 사용자의 친구 목록에 있는 점수 등, 자신이 정의한 점수로 플레이어 목록을 가져올 수 있습니다.

게임에서 많은 통계는 수명 값으로 사용됩니다. 즉, 플레이어는 계속해서 자신의 점수를 업데이트하며, 각 플레이어가 자신의 개인 최고 점수를 경신할 때까지 이전 기록이 표시됩니다. 그러나 일부 플레이어 환경에서는 때때로 순위표를 "지우는" 기능이 있어야 합니다.

이는 사용자가 지정된 기간 동안 상위 플레이어 순위에 도전하도록 동기를 부여하거나, 단순히 순위에서 한동안 비활동 상태인 특정 플레이어를 제거하는 데 사용할 수 있습니다.

이 자습서에서 설명하겠지만, PlayFab의 통계는 미리 정해진 간격으로 재설정되도록 구성할 수 있습니다.

이러한 기능은 위에서 설명한 시나리오 이외에서도 유용합니다. 게임 챌린지에서 사용하거나, 플레이어가 유사한 기술 레벨의 다른 플레이어에게 초대장을 발송할 수 있도록 고유한 최근 점수 순위표가 필요한 타이틀에도 사용할 수 있습니다.

재설정 기간을 설정하면 예를 들어 GetLeaderboardAroundPlayer에 대한 호출에서 반환되는 플레이어가 최근에 게임을 플레이했으며, 로컬 플레이어와 점수가 유사함을 의미합니다.

수동 작업으로 통계를 다시 설정하는 것도 가능합니다. 이는 출시 이전 테스트 또는 알파/베타 플레이의 모든 데이터를 지우는 데 유용한 시스템입니다.

또한 게임 코드에 버그가 생겨 점수를 제어할 수 없는 문제가 발생하는 최악의 경우에도 유용합니다. 이러한 각 경우에 플레이어가 다시 도전할 공정한 기회가 있다고 느끼도록 순위표를 지우는 기능이 필요합니다.

참고 항목

통계를 재설정해도 아래와 같이 이러한 값은 삭제되지 않습니다. 재설정 시 PlayFab의 통계는 버전이 지정되며 새로운 버전에 권한이 부여되고 이전 버전은 이후 분석을 위해 보관됩니다(이전 점수에 따라 플레이어를 보상할 수 있도록).

재설정 가능한 통계 구성

통계 재설정 기간은 관리자 API 설정 또는 게임 관리자를 사용하여 구성됩니다. 그러면 이 기간은 게임 관리자, 서버 API 및 클라이언트 API(클라이언트에서 통계를 게시하려면 클라이언트가 플레이어의 통계를 게시할 수 있도록 허용 옵션이 게임 관리자의 설정->API Features 기능 탭에서 설정되어야 함)를 통해 업데이트 및 쿼리할 수 있습니다

이를 위한 API 메서드는 이후에 설명하며, 여기에서 정의된 매개 변수는 게임 관리자 자체에서 사용되는 것과 동일합니다.

통계를 설정하려면 관리자 CreatePlayerStatisticDefinition 메서드와 UpdatePlayerStatisticDefinition 메서드를 사용하여 나중에 변경할 수 있습니다.

두 경우 모두에서 두 가지 매개 변수는 다음과 같습니다.

  • StatisticName- 플레이어 통계의 문자열 식별자입니다.
  • VersionChangeInterval- 통계를 자동으로 다시 설정해야 하는 시점을 정의하는 기간입니다.

VersionChangeInterval은 이 기능의 핵심 요소이며 매시간, 매일, 매주 또는 매월로 정의할 수 있습니다. 또한 나중에 더 이상 통계를 정기적으로 다시 설정하지 않으려면 재설정 안 함으로 설정할 수 있습니다.

다음 예제에서는 CreatePlayerStatisticDefinition 메서드를 호출하여 매일 재설정되는 통계 헤드샷을 설정합니다. 이렇게 하면 게임에서 이 통계의 순위표가 매일 00:00 UTC에 초기화됩니다.

public void CreatePlayerStatisticDefinition() {
    PlayFabAdminAPI.CreatePlayerStatisticDefinition(
        new CreatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Day
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

다음 예시는 이전 API 호출에 대한 응답을 보여줍니다.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Day"
        }
    }
}

아래에 나타나는 코딩은 또 다른 예시입니다.

public void UpdatePlayerStatisticDefinition() {
    PlayFabAdminAPI.UpdatePlayerStatisticDefinition(
        new UpdatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Week
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

해당 호출은 다음과 같은 응답으로 통계 재설정 기간을 매주로 설정하는 방법을 보여 줍니다.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Week"
        }
    }
}

각각의 경우 결과는 다음을 포함하는 PlayerStatisticDefinition입니다.

  • 통계의 문자열 ID(StatisticName).
  • 통계를 다시 설정한 횟수(CurrentVersion).
  • 통계를 다시 설정할 시점에 대해 정의된 기간(VersionChangeInterval).

재설정 기간은 정의된 즉시 적용되며 따라서 이 경우 호출 이전에 값이 얼마였든지 상관없이 두 번째 호출은 재설정이 이제 월요일 오전 00:00 UTC(UTC 시간대를 사용한 일요일 밤/월요일 오전 자정)로 정의됨을 의미합니다.

나머지 재설정 간격 또한 UTC를 사용하여 정의되며, 매월로 정의하면 매 달 첫 번째 날 00:00 UTC에 재설정이 발생합니다.

재설정 기간의 전체 목록은 다음과 같습니다.

  • 재설정 안 함: 시간 기반 통계 버전 지정을 중지합니다.
  • 매시간: 매 시간(XX:00 UTC)마다 통계를 버전 지정합니다.
  • 매일: 각 날짜마다 자정(00:00 UTC)에 통계를 버전 지정합니다.
  • 매주: 매 월요일 자정(00:00 UTC)에 통계를 버전 지정합니다.
  • 매월: 매 달 첫 번째 날 자정(00:00 UTC)에 통계를 버전 지정합니다.

기존 통계

통계가 재설정 통계로 설정되었는지 여부와 관계없이 게임에서 정의된 모든 통계는 해당 정의에 대해 쿼리할 수 있습니다.

UpdatePlayerStatistics 호출을 사용해 통계를 만들 수 있으므로 이를 알아두는 것이 중요합니다. 재설정 기간(VersionChangeInterval)으로 만들어지지 않은 모든 통계는 시작할 호출이 없으며, 통계 구성에 대한 쿼리는 이 매개 변수를 Never으로 설정하여 반환됩니다.

위의 예를 사용하여, 타이틀에 UpdatePlayerStatistics를 사용해 만들어진(또는 플레이어의 게임 관리자에서 직접 만든) FlagsCaptured라는 통계가 있고 몇 주가 지난 경우 호출은 아래와 같이 나타날 수 있습니다.

public void GetPlayerStatisticDefinitions() {
    PlayFabAdminAPI.GetPlayerStatisticDefinitions(
        new GetPlayerStatisticDefinitionsRequest(),
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

그 결과는 다음과 같습니다.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 2,
            "VersionChangeInterval": "Week"
        },
        {
            "StatisticName": "FlagsCaptured",
            "CurrentVersion": 0,
            "VersionChangeInterval": “Never”
        }]
    }
}

이 경우 Headshots이라는 통계가 정의된 재설정 간격을 가지며 CurrentVersion이 통계가 두 번 다시 설정되었음을 나타냅니다.

한편, FlagsCaptured에는 VersionChangeInterval이 없습니다. 따라서 CurrentVersion0입니다(버전이 지정된 적이 없기 때문).

UpdatePlayerStatistics(또는 PlayFab 게임 관리자)를 통해 만들어진 통계는 위에 설명된 대로 여전히 UpdatePlayerStatisticDefinition을 사용하여 재설정 기간을 가지도록 정의할 수 있습니다.

이 작업이 완료되면 원래 CreatePlayerStatisticDefinition을 사용하여 정의된 것처럼 정확하게 해당 간격으로 재설정됩니다.

수동으로 통계 재설정

게임 버그로 인해 통계에서 치트가 가능한 상황이나, 단순히 출시 이전 게임 플레이의 점수를 제거해야 하는 경우 통계를 게임 관리자에서 또는 IncrementPlayerStatisticVersion을 호출하여 재설정되도록 할 수 있습니다.

이렇게 하면 지정한 현재 통계가 즉시 재설정되며, 게임에서 순위표가 삭제되고 보고할 새로운 값을 위해 빈 슬레이트가 제공됩니다.

본 예시에서는 이 호출이 다음과 같이 나타날 수 있습니다.

public void IncrementPlayerStatisticVersion() {
    PlayFabAdminAPI.IncrementPlayerStatisticVersion(
        new IncrementPlayerStatisticVersionRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

이는 Headshots 통계를 한 번 증분하며 방금 활성화된 버전의 정보를 반환합니다.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersion":
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }
    }
}

이 경우 PlayerStatisticVersion 정보가 반환되며, 통계 ID(StatisticName)와 해당 버전 번호, 권한 있는 버전이 된 시점(ActivationTime), ArchivalStatus(현재 버전에 대해 항상 NotScheduled가 됨)가 포함됩니다.

그러나 VersionChangeInterval 또한 포함된 통계의 경우 수동으로 재설정해도 예약된 다음 재설정 시점이 변경되지 않습니다. 통계가 매일 재설정되도록 예약되었고 수동으로 11:30PM UTC에 재설정된 경우에도 여전히 UTC 자정에 다시 재설정됩니다.

재설정이 발생하는 시점

언급한 바와 같이 재설정 간격이 발생하면 통계가 버전 지정되어 새로운 버전을 즉시 사용할 수 있으며 해당 통계의 이전 버전은 이후 검색을 위해 보관됩니다.

재설정 간격이 발생하거나 수동 재설정이 수행되면 통계가 버전 지정되며, 이전 버전에 대한 쓰기는 최대 10분 동안 허용됩니다. 해당 시점을 지나면 통계는 잠겨지며 향후 업데이트가 불가합니다.

만료되면 나중에 타이틀로 검색할 수 있도록 통계는 보관 프로세스를 시작합니다.

통계 보관 프로세스의 단계는 다음과 같습니다.

  • 예약되지 않음 - 통계의 보관이 시작되지 않았습니다(일반적으로 현재 활성인 통계 버전만 해당).
  • 예약됨 - 보관 프로세스가 예약되었지만 아직 진행 중이 아닙니다.
  • 진행 중 - 통계가 아카이브에 백업되는 중입니다.
  • 실패 - 예기치 못한 오류가 발생했습니다(이 경우 지원 포럼에 문의).
  • 완료 - 이 버전의 통계가 보관되었습니다.

모든 과거 및 현재 버전의 통계는 GetPlayerStatisticVersions를 사용하여 쿼리할 수 있습니다. 그러면 이전 수동 재설정 예제에서와 같이 각 버전에 대한 정보가 반환됩니다.

즉, 이 호출은 아래에 나타난 것처럼 표시됩니다.

public void GetPlayerStatisticVersions() {
    PlayFabAdminAPI.GetPlayerStatisticVersions(
        new GetPlayerStatisticVersionsRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

따라서 여기의 예시 타이틀에 대해 다음과 같은 정보가 반환될 수 있습니다.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersions": [
        {
            "StatisticName": "Headshots",
            "Version": 0,
            "ActivationTime": "2015-01-20T05:47:27.17Z",
            "DeactivationTime": "2016-01-25T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 1,
            "ActivationTime": "2016-01-25T00:00:00.000Z",
            "DeactivationTime": "2016-02-01T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 2,
            "ActivationTime": "2016-02-01T00:00:00.000Z",
            "DeactivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "InProgress"
        },
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }]
    }
}

응답에는 IncrementPlayerStatisticVersion에서 반환된 값 이외에도 현재 활성 버전 이전의 각 버전이 만료된 시점의 타임스탬프(DeactivationTime), 그리고 보관 프로세스가 완료되면 이전 순위표의 완전한 레코드를 포함하는 CSV 파일을 다운로드할 수 있는 URL(ArchiveDownloadUrl) 또한 포함됩니다.

통계 버전에 읽기/쓰기

마지막으로, 사례의 서버 및 클라이언트 API 쪽에서 호출은 원래 PlayFab 사용자 및 캐릭터 통계 호출로부터 알고 있는 것과 매우 유사합니다.

차이점은 이제 버전이 요청이나 응답의 일부라는 것입니다.

통계를 검색하면 버전 번호뿐만 아니라 현재 통계 버전에 대한 값 또한 반환됩니다.

다음 예제는 Headshots 통계를 호출하는 과정과 반환되는 데이터를 보여 줍니다.

서버 요청

public void GetPlayerStatistics() {
    PlayFabServerAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

서버 응답

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "PlayFabId": {{PlayFabId}},
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

클라이언트 요청

public void GetPlayerStatistics() {
    PlayFabClientAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

클라이언트 응답

{
    "code": 200,
    "status": "OK",
    "data": {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

한편, Update 호출은 선택적으로 게임 플레이 중에 버전이 증분했을 수 있는 경우를 위해 타이틀에서 업데이트되는 버전을 제어할 수 있도록 하는 버전을 가집니다.

참고 항목

이 예시에서 이전 버전을 아직 사용할 수 있을 때 타이틀을 이전 버전에 쓰려면 아래와 같이 버전 2에 쓰게 됩니다.

서버 요청

public void UpdatePlayerStatistics() {
    PlayFabServerAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

서버 응답

{
    "code": 200,
    "status": "OK",
    "data": {}
}

클라이언트 요청

public void UpdatePlayerStatistics() {
    PlayFabClientAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

클라이언트 응답

{
    "code": 200,
    "status": "OK",
    "data": {}
}

하지만 기억하십시오. 만료된 버전은 최대 10분 동안 쓸 수 있으며, 해당 시간 에 이 버전에 쓰려고 시도하면 실패하며 아래와 같은 응답이 반환됩니다.

{
    "code": 400,
    "status": "BadRequest",
    "error": "StatisticVersionClosedForWrites",
    "errorCode": 1197,
    "errorMessage": "The statistic version is not current and is no longer accepting updates"
}

리소스

완전성을 위해 이 섹션은 위에 설명한 모든 열거형, 클래스 및 API 메서드를 간략한 설명과 함께 나열합니다.

기본 열거형

  • Interval - 통계(순위표)를 다시 설정할 속도의 기간:

    • Never
    • Hour
    • Day
    • Week
  • StatisticVersionArchivalStatus - 다운로드할 수 있는 아카이브에 버전의 플레이어 통계 값을 저장하는 프로세스의 상태:

    • NotScheduled
    • 예약
    • InProgress
    • 실패
    • Complete

기본 클래스 및 구성원

  • PlayerStatisticDefinition

    • StatisticName(문자열) - 통계의 고유한 이름.
    • CurrentVersion(문자열) - 통계가 재설정될 때마다 증분되는 통계의 현재 활성 현재 버전.
    • VersionChangeInterval(Interval) - 모든 플레이어에 대한 통계 값을 다시 설정할 간격.
  • PlayerStatisticVersion

    • StatisticName(문자열) - 버전이 활성화될 시점의 통계 이름.
    • Version(문자열) - 통계의 버전(문자열로 인코딩된 16진수 숫자).
    • ScheduledVersionChangeIntervalTime(DateTime) - 구성된 ResetInterval에 따라 통계 버전을 활성화하도록 예약된 시점.
    • CreatedTime(DateTime) - 통계 버전을 활성화할 시점.
    • ArchivalStatus(StatisticVersionArchivalStatus) - 구성된 경우 다운로드할 수 있는 아카이브에 이 버전의 플레이어 통계 값을 저장하는 프로세스의 상태.
    • ResetInterval(Interval) - 구성된 경우 트리거된 버전을 활성화할 재설정 간격.
  • StatisticValue

    • StatisticName(문자열) - 통계의 고유한 이름.
    • Value(Int32) - 플레이어에 대한 통계 값.
    • Version(문자열) - 플레이어에 대한 기존 통계 값에 대해, 로드된 시점의 통계 버전.
  • StatisticUpdate

    • StatisticName(문자열) - 통계의 고유한 이름.
    • Version(문자열) - 플레이어의 통계 값에 대한 업데이트에 대해, 업데이트할 통계의 버전.
    • Value(Int32) - 플레이어에 대한 통계 값.

관리자 API 메서드

  • CreatePlayerStatisticDefinition

    • CreatePlayerStatisticDefinitionRequest

      • Name(문자열) - 최소 길이 1, 최대 길이 128 - 통계의 고유한 이름.
      • (VersionChangeInterval)(Interval) - 모든 플레이어에 대한 통계 값을 다시 설정할 간격(재설정은 다음 간격 경계에서 시작).
    • CreatePlayerStatisticDefinitionResult

      • Statistic(PlayerStatisticDefinition) - 만든 통계의 정의.
  • UpdatePlayerStatisticDefinition

    • UpdatePlayerStatisticDefinitionRequest

      • StatisticName(문자열) - 통계의 고유한 이름.
      • VersionChangeInterval(Interval) - 모든 플레이어에 대한 통계 값을 다시 설정할 간격(재설정은 다음 간격 경계에서 시작).
    • UpdatePlayerStatisticDefinitionResult

      • Statistic(PlayerStatisticDefinition) - 만든 통계의 정의.
  • GetPlayerStatisticDefinitions

    • GetPlayerStatisticDefinitionsRequest(매개 변수 없음).
    • GetPlayerStatisticDefinitionsResult
      • Statistics(PlayerStatisticDefinition[]) - 재설정에 대한 정의 배열.
  • GetPlayerStatisticVersions

    • GetPlayerStatisticVersionsRequest

      • StatisticName(문자열) - 통계의 고유한 이름.
    • GetPlayerStatisticVersionsResult

      • StatisticVersions(PlayerStatisticVersion[]) - 통계의 버전 변경 기록(모든 버전).
  • IncrementPlayerStatisticVersion

    • IncrementPlayerStatisticVersionRequest

      • StatisticName(문자열) - 통계의 고유한 이름.
    • IncrementPlayerStatisticVersionResult

      • StatisticVersion(PlayerStatisticVersion) - 작업의 결과로 만료된 통계 버전(및 보관 상태).

클라이언트 API 메서드

  • GetPlayerStatistics

    • GetPlayerStatisticsRequest

      • StatisticNames(string[]) - 고유한 이름으로 반환할 통계의 배열.
    • GetPlayerStatisticsResult

      • Statistics(StatisticValue[]) - 요청된 모든 통계에 대한 StatisticValue 데이터 배열.
  • UpdatePlayerStatistics

    • UpdatePlayerStatisticsRequest

      • Statistics(StatisticUpdate[]) - 제공된 값으로 업데이트할 통계.
    • UpdatePlayerStatisticsResult(매개 변수 없음).

서버 API 메서드

  • GetPlayerStatistics

    • GetPlayerStatisticsRequest

      • PlayFabId(문자열) - 통계가 업데이트된 플레이어의 PlayFab ID.
      • StatisticNames(string[]) - 고유한 이름으로 반환할 통계의 배열.
    • GetPlayerStatisticsResult

      • Statistics(StatisticValue[]) - 요청된 모든 통계에 대한 StatisticValue 데이터 배열.
  • UpdatePlayerStatistics

    • UpdatePlayerStatisticsRequest

      • PlayFabId(문자열) - 통계가 업데이트된 플레이어의 PlayFab ID.
      • Statistics(StatisticUpdate[]) - 제공된 값으로 업데이트할 통계.
    • UpdatePlayerStatisticsResult(매개 변수 없음).