リセット可能な統計とリーダーボードの使用

このチュートリアルでは、バージョン管理を使用した統計 (つまり リセット可能な 統計) と、それに伴うリーダーボードを構成および管理する方法について、完全にウォークスルーします。 Admin API メソッドの使用方法に焦点を当て、Client および Server API メソッドを使用して、現在のバージョンだけでなく以前のバージョンのデータをクエリする方法についての追加情報も提供します。私たちの目標は、リセット可能な統計が PlayFab でどのように動作するかを技術的にレビューし、それらをゲームで使用できるすべての方法を紹介することです。

統計とリーダーボード

まず、PlayFab でゲーム内のプレイヤーに対して定義されるすべての統計は、リーダーボードの一部であることに注意することが重要です。したがって、統計を定義することは、リーダーボードを定義することでもあります。統計は必ずしもプレイヤーに表示されるとは限りませんが、そこには存在します。統計を使用して、定義したスコアに基づくプレイヤーのリストを取得できます。すべてのスコアの上位、下位、現在のプレイヤーを中心とするもの、またはユーザーのフレンドリストに含まれるものなどを見つけられます。ゲーム内の多くの統計は ライフタイム 値を意図しています。つまり、プレイヤーは継続的にスコアを更新し、各プレイヤーが自分のパーソナルベストを更新するまで古い値が残ります。しかし、プレイヤー体験によっては、時折リーダーボードを「消去」できることが重要です。これは、ユーザーが特定の期間の最上位プレイヤーになろうとするインセンティブになったり、しばらくアクティブではなかったプレイヤーを単にランキングから削除したりするために使用できます。このチュートリアルで説明するように、PlayFab の統計は、事前に決められた間隔でリセットするように構成できます。これは、上記のシナリオだけでなく、最近のスコアの明確なリーダーボードを必要とするタイトルにも役立ちます。たとえば、プレイヤーに同程度のスキルレベルの相手に招待を送信させたい、ゲームチャレンジのようなものに使用できます。リセット期間を設定することで、たとえば GetLeaderboardAroundPlayer の呼び出しで返されるプレイヤーは、最近ゲームをプレイし、ローカルプレイヤーと同様のスコアを持つプレイヤーになります。また、統計を手動操作としてリセットすることもできます。これは、リリース前のテストやアルファ/ベータプレイのデータをクリアするための便利なシステムです。これは最悪の場合のシナリオでも役立ちます。たとえば、ゲームコードにバグが導入されて制御不能なスコアが発生した場合などです。いずれの場合も、リーダーボードを クリーン に消去できる能力が必要です。これによりプレイヤーは、リーダーボードに載る公正なチャンスがあると感じられます。

以下で示すように、統計のリセットはそれらの値を削除するわけではありません。リセット時に、PlayFab の統計はバージョン管理され、新しいバージョンが権威となり、以前のバージョンは後で分析するために保持されます (そして古いスコアに基づいてプレイヤーに報酬を与えることができます)。

リセット可能な統計の構成

統計のリセット期間は、Admin API セットまたは Game Manager を使用して構成されます。その後、Game Manager、Server API、Client API を介して更新およびクエリできます (ただし、クライアントから統計を投稿するには、Game Manager の Settings -> API Features タブで allow client to post statistics オプションを設定する必要があります)。これに対応する API メソッドを説明しますが、ここで定義されているパラメーターは Game Manager 自体で使用されるものと同じです。統計をセットアップするには、Admin CreatePlayerStatisticDefinition メソッドを使用でき、後で変更するには UpdatePlayerStatisticDefinition メソッドを使用できます。いずれの場合も、パラメーターは 2 つだけです:

StatisticName - プレイヤー統計の文字列識別子。
VersionChangeInterval - 統計を自動的にリセットするタイミングを定義する期間。

VersionChangeInterval はこの機能のキーであり、hourly、daily、weekly、または monthly として定義できます。また、定期的なリセットを行いたくないと後で判断した場合は、never に設定することもできます。以下の例では、CreatePlayerStatisticDefinition メソッドを呼び出して、日次リセットで統計 Headshots をセットアップしています。つまり、ゲーム内のこの統計のリーダーボードは毎日 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())
    );
}

この呼び出しは、統計のリセット期間を weekly に設定することを示しており、以下のレスポンスが返されます。

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

いずれの場合も、結果は PlayerStatisticDefinition で、以下を含みます:

統計の文字列 ID (StatisticName)。
統計がリセットされた回数 (CurrentVersion)。
統計がリセットされる時期を定義する期間 (VersionChangeInterval)。

リセット期間は定義されるとすぐに有効になります。この場合、2 回目の呼び出しはリセットが今や月曜日の午前 0:00 UTC (UTC タイムゾーンを使用した日曜夜/月曜早朝) として定義されることを意味します。呼び出し前の値は関係ありません。残りのリセット間隔も UTC を使用して定義され、Month の場合は毎月 1 日の 00:00 UTC にリセットが発生します。一覧を完全に示すと、リセット期間は次のとおりです:

Never: 時間ベースの統計のバージョン管理を停止します。
Hour: 毎時間の始まり (XX:00 UTC) に統計をバージョン管理します。
Day: 毎日の午前 0 時 (00:00 UTC) に統計をバージョン管理します。
Week: 毎週月曜日の午前 0 時 (00:00 UTC) に統計をバージョン管理します。
Month: 毎月 1 日の午前 0 時 (00:00 UTC) に統計をバージョン管理します。

既存の統計

ゲーム内で定義されているすべての統計は、リセット統計としてセットアップされているかどうかにかかわらず、定義をクエリできます。これは重要です。統計は UpdatePlayerStatistics 呼び出しを使用して作成できるためです。リセット期間 (VersionChangeInterval) なしで作成された統計には最初からリセット期間がないため、統計構成のクエリではこのパラメーターが Never に設定されて返されます。上記の例を使用すると、タイトルにも UpdatePlayerStatistics を使用して作成された FlagsCaptured という統計 (または Game Manager でプレイヤーに対して直接作成された) があり、数週間が経過していれば、以下の呼び出しに示すように表示されます。

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 は統計が 2 回リセットされたことを示します。一方、FlagsCaptured には VersionChangeInterval がありません。これが、CurrentVersion が 0 である理由でもあります (バージョン管理されたことがないため)。 UpdatePlayerStatistics (または PlayFab Game Manager) を介して作成された統計は、上記の通り UpdatePlayerStatisticDefinition を使用して依然としてリセット期間を持つように定義できます。これが実行されると、CreatePlayerStatisticDefinition を使用して最初から定義されたかのように、その間隔でリセットされます。

統計の手動リセット

ゲームバグにより統計に対する不正が可能だった状況や、単にリリース前ゲームプレイからのスコアを削除するためにリセットする必要がある場合、統計を Game Manager で、または IncrementPlayerStatisticVersion 呼び出しを介して強制的にリセットできます。これにより、指定した現在の統計が即座にリセットされ、ゲームのリーダーボードがクリアされ、新しい値を報告するためのブランクスレートが提供されます。この例では、この呼び出しは以下のようになります。

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

これにより、Headshots 統計がさらに 1 回インクリメントされ、アクティブになったバージョンに関する情報が返されます。

{
    "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 も持つ統計の場合、手動でリセットしても次のスケジュールされたリセット時間は変更 されません。統計が日次でリセットするようにスケジュールされていて、23:30 UTC に手動でリセットされた場合でも、UTC の午前 0 時に再度リセットされます。

リセットが発生するとき

前述のとおり、リセット間隔が発生すると統計はバージョン管理され、新しいバージョンがすぐに利用可能になり、その統計の古いバージョンは後の取得のためにアーカイブされます。リセット間隔が発生する (または手動リセットが実行される) と、統計がバージョン管理され、古いバージョンへの書き込みは最大 10 分間受け入れられます。それを過ぎると、統計は ロック され、それ以降の更新ができなくなります。有効期限が切れると、統計はアーカイブプロセスに入り、後でタイトルから取得できるようになります。統計のアーカイブプロセスの段階は次のとおりです:

NotScheduled - 統計のアーカイブが開始されていない (通常、現在アクティブな統計バージョンのみ)。
Scheduled - アーカイブプロセスがスケジュールされていますが、まだ進行していません。
InProgress - 統計がアーカイブにバックアップされています。
Failed - 予期しない失敗が発生しました (この場合は、サポートフォーラムにお問い合わせください)。
Complete - このバージョンの統計はアーカイブされています。

統計の過去および現在のすべてのバージョンは、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) も含まれます。

統計バージョンの読み取りと書き込み

最後に、Server および Client API 側では、これらの呼び出しは PlayFab の元のユーザーおよびキャラクター統計の呼び出しとよく似ています。違いは、バージョンがリクエストまたはレスポンスの一部になったことです。統計を取得する際、現在の統計バージョンの値とバージョン番号自体が返されます。以下の例は、Headshots 統計の呼び出しと、返されたデータを示しています。

Server リクエスト

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

Server レスポンス

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

Client リクエスト

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

Client レスポンス

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

一方、Update 呼び出しはオプションのバージョンを受け取り、ゲームプレイ中にバージョンがインクリメントされた可能性がある場合に、どのバージョンを更新するかをタイトルが制御できるようにします。

この例では、タイトルがまだ可能な間に以前のバージョンに書き込む場合、以下に示すように Version 2 に書き込まれることになります。

Server リクエスト

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())
    );
}

Server レスポンス

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

Client リクエスト

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())
    );
}

Client レスポンス

{
    "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
- Month
StatisticVersionArchivalStatus - ダウンロード可能なアーカイブにバージョンのプレイヤー統計値を保存するプロセスのステータス:
- NotScheduled
- Scheduled
- InProgress
- Failed
- Complete

ベースクラスとそのメンバー

PlayerStatisticDefinition
- StatisticName (string) - 統計の一意の名前。
- CurrentVersion (string) - 統計のアクティブな現在のバージョン。統計がリセットされるたびにインクリメントされます。
- VersionChangeInterval (Interval) - 全プレイヤーの統計値がリセットされる間隔。
PlayerStatisticVersion
- StatisticName (string) - バージョンがアクティブになったときの統計の名前。
- Version (string) - 統計のバージョン (文字列としてエンコードされた 16 進数)。
- ScheduledVersionChangeIntervalTime (DateTime) - 構成された ResetInterval に基づいて統計バージョンがアクティブになる予定だった時刻。
- CreatedTime (DateTime) - 統計バージョンがアクティブになった時刻。
- ArchivalStatus (StatisticVersionArchivalStatus) - このバージョンのプレイヤー統計値をダウンロード可能なアーカイブに保存するプロセスのステータス (構成されている場合)。
- ResetInterval (Interval) - バージョンがアクティブになるようトリガーしたリセット間隔 (構成されている場合)。
StatisticValue
- StatisticName (string) - 統計の一意の名前。
- Value (Int32) - プレイヤーの統計値。
- Version (string) - プレイヤーの既存の統計値については、ロード時の統計のバージョン。
StatisticUpdate
- StatisticName (string) - 統計の一意の名前。
- Version (string) - プレイヤーの統計値の更新については、更新される統計のバージョン。
- Value (Int32) - プレイヤーの統計値。

Admin API メソッド

CreatePlayerStatisticDefinition
- CreatePlayerStatisticDefinitionRequest
  - Name (string) - 最小長 1、最大長 128 - 統計の一意の名前。
  - (VersionChangeInterval) (Interval) - 全プレイヤーの統計値がリセットされる間隔 (リセットは次の間隔境界から始まります)。
- CreatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - 作成された統計の定義。
UpdatePlayerStatisticDefinition
- UpdatePlayerStatisticDefinitionRequest
  - StatisticName (string) - 統計の一意の名前。
  - VersionChangeInterval (Interval) - 全プレイヤーの統計値がリセットされる間隔 (リセットは次の間隔境界から始まります)。
- UpdatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - 作成された統計の定義。
GetPlayerStatisticDefinitions
- GetPlayerStatisticDefinitionsRequest (パラメーターなし)。
- GetPlayerStatisticDefinitionsResult
  - Statistics (PlayerStatisticDefinition[]) - リセットの定義の配列。
GetPlayerStatisticVersions
- GetPlayerStatisticVersionsRequest
  - StatisticName (string) - 統計の一意の名前。
- GetPlayerStatisticVersionsResult
  - StatisticVersions (PlayerStatisticVersion[]) - 統計のバージョン変更履歴 (すべてのバージョン)。
IncrementPlayerStatisticVersion
- IncrementPlayerStatisticVersionRequest
  - StatisticName (string) - 統計の一意の名前。
- IncrementPlayerStatisticVersionResult
  - StatisticVersion (PlayerStatisticVersion) - この操作の結果として期限切れになった統計バージョン (およびそのアーカイブステータス)。

Client API メソッド

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - StatisticNames (string[]) - 一意の名前で返される統計の配列。
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - リクエストされたすべての統計の StatisticValue データの配列。
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - Statistics (StatisticUpdate[]) - 提供された値で更新される統計。
- UpdatePlayerStatisticsResult (パラメーターなし)。

Server API メソッド

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - PlayFabId (string) - 統計が更新されるプレイヤーの PlayFab ID。
  - StatisticNames (string[]) - 一意の名前で返される統計の配列。
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - リクエストされたすべての統計の StatisticValue データの配列。
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - PlayFabId (string) - 統計が更新されるプレイヤーの PlayFab ID。
  - Statistics (StatisticUpdate[]) - 提供された値で更新される統計。
- UpdatePlayerStatisticsResult (パラメーターなし)。

​統計とリーダーボード

​リセット可能な統計の構成

​既存の統計

​統計の手動リセット

​リセットが発生するとき

​統計バージョンの読み取りと書き込み

​Server リクエスト

​Server レスポンス

​Client リクエスト

​Client レスポンス

​Server リクエスト

​Server レスポンス

​Client リクエスト

​Client レスポンス

​リソース

​ベース列挙型

​ベース クラスとそのメンバー

​Admin API メソッド

​Client API メソッド

​Server API メソッド

統計とリーダーボード

リセット可能な統計の構成

既存の統計

統計の手動リセット

リセットが発生するとき

統計バージョンの読み取りと書き込み

Server リクエスト

Server レスポンス

Client リクエスト

Client レスポンス

Server リクエスト

Server レスポンス

Client リクエスト

Client レスポンス

リソース

ベース列挙型

ベースクラスとそのメンバー

Admin API メソッド

Client API メソッド

Server API メソッド