リセットできる統計情報とランキングの使用

[アーティクル]
07/13/2023

このチュートリアルでは、統計情報 (および拡張機能としてランキング) のリセットを可能にするバージョン管理により、統計情報を構成および管理する方法の詳しいチュートリアルを提供します。

管理 API メソッドの使い方に焦点を当て、クライアントおよびサーバー API メソッドを使ってデータをクエリする方法 (最新のバージョンと以前のバージョンの両方) の追加情報を提供します。

目標は、リセットできる統計情報の PlayFab におけるしくみと、それらをゲームで使う詳しい方法について技術的なレビューを提供することです。

統計情報とランキング

最初に、ゲーム内でのプレイヤーに対して定義されているすべての統計情報がランキングの一部であることに注意することが重要です。したがって、統計情報を定義するとランキングも定義されます。

統計情報は必ずしもにプレイヤーに表示されるわけではありませんが、存在します。それらを使って、定義したスコアによってプレイヤーの一覧や (全スコアの上位、下位、現在のプレイヤーを中心とするスコアのどれを見つけるためであっても)、ユーザーのフレンドリストに掲載されているプレイヤーの一覧を取得することができます。

ゲーム内の多くの統計情報は、ライフタイム値となることが意図されています。つまり、プレイヤーは自身のスコアを継続的に更新し、古いスコアは各プレイヤーが自分の個人ベストを上回るまで残ります。ただし、一部のプレイヤーエクスペリエンスでは、ランキングを随時 "ワイプ" できることが重要です。

これは、特定期間のトップランクプレイヤーとなるようユーザーに促したり、単に一定期間アクティブでないプレイヤーをランキングから削除したりするために使うことができます。

このチュートリアルで説明するように、PlayFab の統計情報は事前に定義した間隔でリセットするように構成できます。

これが便利なのは上記で説明したシナリオだけではありません。最新のスコアの別個のランキングが必要なタイトルにも使うことができ、ゲームチャレンジ (プレイヤーが同じようなスキルレベルのプレイヤーに招待を発行できる) などに使うことができます。

リセット期間のリセットは、GetLeaderboardAroundPlayer の呼び出しで返されたプレイヤーが、たとえば、最近ゲームをプレイし、ローカルプレイヤーと同様のスコアを持っているプレイヤーであることを意味します。

手動操作としての統計情報をリセットすることもできます。これは、ローンチ前のテストまたはアルファ/ベータプレイから得られたすべてのデータを消去するための便利なシステムです。

バグがゲームコードに入り込んでスコアを制御できなくなった最悪のシナリオにも役立ちます。いずれの場合も、プレイヤーがスコアを獲得する機会が公平であると感じるように、ランキングをクリーンにワイプする機能が必要です。

注意

以下に示すように、統計情報をリセットしても、これらの値は削除されません。リセット時、PlayFab の統計情報はバージョン管理され、後で分析できるように (および古いスコアに基づいてプレイヤーにリワードを付与できるように) 以前のバージョンを維持しながら、新しいバージョンが有効になります。

リセットできる統計情報の構成

統計情報のリセット期間は、管理 API セットまたはゲームマネージャーを使って構成されます。その後、ゲームマネージャー、サーバー API、クライアント API を使って更新およびクエリできます (クライアントから統計情報を投稿しても [クライアントにプレイヤー統計情報のポストを許可する] オプションをゲームマネージャーにあるゲームの [設定]->[API 機能] タブで設定する必要はありません)。

この API メソッドについて説明しますが、ここで定義されているパラメーターはゲームマネージャー自体で使用されるものと同じです。

統計情報をセットアップするには、管理 CreatePlayerStatisticDefinition メソッドを使うことができ、UpdatePlayerStatisticDefinition メソッドを使って後で変更を加えることができます。

どちらの場合も、2 つのパラメーターのみ指定できます。

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

VersionChangeInterval はこの機能のキーであり、時間、日、週、または月単位で定義できます。後で統計情報を定期的にリセットしないことにした場合、まったく設定しないでもかまいません。

以降の例では、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())
    );
}

この呼び出しは、統計情報のリセット期間を毎週に設定する方法を示しており、応答は以下のとおりです。

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

いずれの場合も、結果は PlayerStatisticDefinition であり、次の内容が含まれています。

統計情報の文字列 ID (StatisticName)。
統計情報がリセットされた回数 (CurrentVersion)。
統計情報がリセットされるタイミングの定義された期間 (VersionChangeInterval)。

リセット期間は定義するとすぐに有効になるため、この場合、2 番目の呼び出しは、呼び出し前の設定内容に関係なく、リセットが月曜日の始まりの 00:00 UTC と定義されていることを意味します (日曜日の深夜/月曜日の始まり。UTC タイムゾーンを使用)。

他のリセット間隔も UTC を使って定義されます。Month の場合、各月の初日の 00:00 UTC にリセットが行われます。

完了した一覧のリセット期間は次のとおりです。

Never: 時間ベースでの統計情報のバージョン管理を停止します。
Hour: 1 時間単位で統計情報をバージョン管理します (XX:00 UTC)。
Day: 毎日深夜 (00:00 UTC) に統計情報をバージョン管理します。
Week: 毎週月曜日 (00:00 UTC) に統計情報をバージョン管理します。
Month: 毎月初日の深夜 (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 は統計が 2 回リセットされていることを示しています。

一方、FlagsCaptured には VersionChangeInterval がありません。これも CurrentVersion が 0 である理由です (まったくバージョン管理されていないため)。

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:30 PM 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) も含まれています。

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

最後の点として、サーバーとクライアントの 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
- Month
StatisticVersionArchivalStatus - あるバージョンのプレイヤー統計情報値をダウンロード可能なアーカイブに保存するプロセスのステータス。
- NotScheduled
- 予定
- InProgress
- Failed
- Complete

基本クラスとそのメンバー

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

管理 API メソッド

CreatePlayerStatisticDefinition
- CreatePlayerStatisticDefinitionRequest
  - Name (文字列) - 最小長 1、最大長 128 - 統計情報の一意の名前。
  - (VersionChangeInterval) (間隔) - すべてのプレイヤーの統計情報値がリセットされる間隔 (リセットは次の間隔境界に開始されます)。
- CreatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - 作成された統計の定義。
UpdatePlayerStatisticDefinition
- UpdatePlayerStatisticDefinitionRequest
  - StatisticName (文字列) - 統計情報の一意の名前。
  - VersionChangeInterval (間隔) - すべてのプレイヤーの統計情報値がリセットされる間隔 (リセットは次の間隔境界で開始されます)。
- 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 (パラメーターなし)。

次の方法で共有

リセットできる統計情報とランキングの使用

統計情報とランキング

リセットできる統計情報の構成

既存の統計情報

統計情報の手動でのリセット

リセットが発生するタイミング

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

サーバー要求

サーバー応答

クライアント要求

クライアント応答

サーバー要求

サーバー応答

クライアント要求

クライアント応答

リソース

基本の列挙型

基本クラスとそのメンバー

管理 API メソッド

クライアント API メソッド

サーバー API メソッド

フィードバック

その他のリソース