Resettable の統計情報とスコアボードの使用

このチュートリアルでは、バージョン管理を使用して統計情報を設定および管理する方法についての詳しい説明を提供します。これにより、統計のリセット、および拡張スコアボードの リセット が可能になります。

ここでは、管理 API メソッドの使い方について説明します。また、クライアントとサーバーの API メソッドを使用して、現在のバージョンと古いバージョンの両方でデータのクエリを行う方法についても説明します。

私たちの目標は、PlayFab での統計の再設定方法、およびゲームでの使用方法に関する技術的なレビューを提供することです。

統計とスコアボード

まず、PlayFab のゲームのプレイヤーに対して定義されているすべての統計情報がスコアボードに含まれていることに注意してください。 したがって、統計を定義すると、スコアボードも定義されます。

統計情報は、プレイヤーには表示されない場合もありますが、表示されます。 このスコアを使って、定義したスコアに基づいてプレイヤーの一覧を取得することができます。すべてのスコアの一番上にあるか、現在のプレイヤーを中心としているか、またはユーザーのフレンドリスト上のユーザーを検索します。

ゲームの統計情報の多くは、 有効期間 の値として使用されています。つまり、プレイヤーがスコアを継続的に更新することを意味します。これは、プレイヤーがそれぞれの得点を最大限に活用できるようにするものです。 ただし、プレーヤーの一部のエクスペリエンスについては、スコアボードを随時 "ワイプ" することが重要です。

これは、特定の期間についての上位のプレーヤーとして使用するようにユーザーを促したり、しばらくの間アクティブでないプレイヤーをランク付けから削除したりするために使うことができます。

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

これは、上で説明したシナリオについてのものではありません。また、ゲームの問題などに使用されるタイトルにも使用できます。これは、プレイヤーが同様のスキルレベルの招待を発行することを希望する場合にも使用できます。

リセット期間を設定するということは、たとえば、 GetLeaderboardAroundPlayerへの通話で返されたプレーヤーが、ゲームを最近プレイしたプレイヤーであり、ローカルプレイヤーに似たスコアを持っているユーザーであることを意味します。

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

また、最悪のケースのシナリオでは、ゲームコードにバグが導入され、その結果として制御されないスコアが発生する場合にも便利です。 どちらの場合も、スコアボードをワイプする機能を備えている必要があります。これに より、プレイヤーがすぐにアクセスできるようになります。

注意

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

Resettable の統計情報を設定する

統計のリセット期間は、管理 API セットまたはゲームマネージャーを使用して構成されます。 次に、ゲームマネージャー、サーバー api、クライアント API を使用して、更新して照会することができます (ただし、クライアントからの統計情報の投稿は、ゲームマネージャーのゲームの設定 -> APIの [機能] タブで設定する必要があります)。

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

統計情報を設定するには、管理者メソッドとメソッドを使用して CreatePlayerStatisticDefinition UpdatePlayerStatisticDefinition 後で変更を行うことができます。

どちらの場合も、次の2つのパラメーターしかありません。

  • 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 )。

リセット期間は、ユーザーが定義するとすぐに有効になります。この例では、2番目の呼び出しは、通話の前後の時刻に関係なく、00:00 UTC の月曜日の朝に定義されていることを意味します。

残りのリセット間隔は、UTC を使用して定義されます。月を設定すると、月の最初の日に 00:00 UTC でリセットできます。

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

  • Never: 時間ベースで統計情報のバージョン管理を停止します。
  • Hour: すべての 時間 (XX:00 UTC) の一番上に統計情報をバージョンとして示します。
  • : 日付の深夜 (00:00 UTC) で統計情報をバージョンします。
  • : 月曜日に0時 (00:00 UTC) に統計情報をバージョンとして示します。
  • Month: バージョンでは、毎月最初の曜日の深夜 (00:00 UTC) で統計情報が指定されます。

既存の統計情報

統計のリセットとして設定されているかどうかに関係なく、ゲームで定義されているすべての統計情報は、定義に対して照会できます。

UpdatePlayerStatistics通話を使用して統計情報を作成できるため、これは重要です。 再設定期間 () で作成されていない統計情報に VersionChangeInterval ついては、開始することはできません。そのため、統計構成のクエリでは、このパラメーターをに設定して戻り Never ます。

上の例を使用する FlagsCaptured と、 UpdatePlayerStatistics を使用して (またはプレーヤーで直接ゲームマネージャーで作成された) 統計情報がタイトルに含まれている場合に、次のように表示されるようになります。

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 でリセットされます。

リセットが発生した場合

前に説明したように、再設定の間隔を指定すると、統計情報のバージョンが更新され、新しいバージョンはすぐに使用できるようになりますが、その統計の古いバージョンは、後で取得するためにアーカイブされます。

再設定の間隔が経過すると (または手動によるリセットが実行されます)、統計のバージョンが更新されると、古いバージョンへの書き込みは最大10分間受け入れられます。 この点を超えて、統計情報は ロックされ、将来の更新を防止できます。

有効期限が切れた後は、後でタイトルで取得できるように、統計情報がアーカイブプロセスに始まります。

統計情報のアーカイブプロセスの段階は次のとおりです。

  • Notscheduled 設定 されている統計情報のアーカイブが開始されていません (通常は、現在アクティブな統計バージョンでのみ)。
  • スケジュール 済み-アーカイブプロセスはスケジュールされていますが、まだ進行中ではありません。
  • InProgress -統計情報はアーカイブにバックアップされています。
  • 失敗 -予期しないエラーが発生しました (この場合は、 サポートフォーラムにお問い合わせください)。
  • 完了 -このバージョンの統計情報はアーカイブされています。

統計の過去と現在のバージョンはすべて、を使って照会でき 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"
}

Resources

これについては、このセクションでは、上で説明したすべての列挙体、クラス、および API メソッドの一覧を簡単に説明します。

基本列挙

  • 期間-統計 (スコアボード) がリセットされる間隔

    • Never
    • Hour
    • Day
    • Week
    • Month
  • StatisticVersionArchivalStatus -ダウンロード可能なアーカイブに、バージョンのプレーヤー統計値を保存するプロセスの状態。

    • NotScheduled
    • スケジュール
    • InProgress
    • Failed
    • Complete

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

  • PlayerStatisticDefinition

    • StatisticName (文字列)-統計の一意の名前。
    • CurrentVersion (文字列): 統計値の現在のアクティブなバージョン。統計情報がリセットされるたびにインクリメントされます。
    • Versionchangeinterval (interval): すべてのプレイヤーの統計情報の値がリセットされる間隔です。
  • PlayerStatisticVersion

    • StatisticName (文字列): バージョンがアクティブになったときの統計情報の名前。
    • Version (文字列)-統計のバージョン (文字列としてエンコードされた16進数)。
    • Scheduledversionchangeintervaltime (DateTime): 構成済みの resetintervalに基づいて、統計バージョンがアクティブになるスケジュールが設定された時刻。
    • アーカイブ 可能な状態 (StatisticVersionArchivalStatus): 構成されている場合は、このバージョンの player 統計値をダウンロード可能なアーカイブに保存するプロセスの状態。
    • Resetinterval (interval): 構成されている場合に、バージョンがアクティブになるようにトリガーされるリセット間隔です。
  • StatisticValue

    • StatisticName (文字列)-統計の一意の名前。
    • Version (string)-プレイヤーの既存の統計値の場合は、読み込み時の統計情報のバージョン。
  • StatisticUpdate

    • StatisticName (文字列)-統計の一意の名前。
    • バージョン (文字列)-プレイヤーの統計値の更新の場合、更新される統計のバージョン

管理 API のメソッド

  • CreatePlayerStatisticDefinition

    • CreatePlayerStatisticDefinitionRequest

      • Name (文字列)-min length 1、最大長 128-統計の一意の名前。
      • (バージョンの Changeinterval)(Interval): すべてのプレイヤーの統計情報の値がリセットされる間隔です (リセットされるのは次の間隔で開始します)。
    • CreatePlayerStatisticDefinitionResult

      • 統計 (PlayerStatisticDefinition): 作成された統計情報の定義です。
  • UpdatePlayerStatisticDefinition

    • UpdatePlayerStatisticDefinitionRequest

      • StatisticName (文字列)-統計の一意の名前。
      • Versionchangeinterval (interval)-すべてのプレイヤーの統計情報の値がリセットされる間隔 (リセットされるのは次の間隔で開始します)。
    • UpdatePlayerStatisticDefinitionResult

      • 統計 (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 (パラメーターなし)。

Server API メソッド

  • GetPlayerStatistics

    • GetPlayerStatisticsRequest

      • PlayFabId (string): 統計が更新されているプレーヤーの PLAYFAB ID。
      • StatisticNames (string [])-返される統計の配列。一意の名前を指定します。
    • GetPlayerStatisticsResult

      • Statistics (StatisticValue [])-要求されたすべての統計情報の StatisticValue データの配列です。
  • UpdatePlayerStatistics

    • UpdatePlayerStatisticsRequest

      • PlayFabId (string): 統計が更新されているプレーヤーの PLAYFAB ID。
      • Statistics (StatisticUpdate []): 指定された値を使用して、更新される統計情報を指定します。
    • UpdatePlayerStatisticsResult (パラメーターなし)。