Stats Interface

統計を管理するインターフェースです。

9 分で読めます

Stats インターフェース は、デベロッパーにアプリケーションのユーザーに関する 統計 を管理する機能を提供し、収集したアイテムの数、プレイヤーの最速レベル完了時間、勝負の成績、ユーザーが特定のアクションを実行した回数など、デベロッパーが追跡したい統計データを含めることができます。統計情報を使って、アチーブメント をアンロックするタイミングを判断したり リーダーボード でユーザーのランク付け方法を決定することができます。

Stats インターフェースを利用する

Stats インターフェースの関数を利用するには、Platform (プラットフォーム) インターフェースEOS_Platform_GetStatsInterface 関数を呼び出して EOS_HStats ハンドルを取得する必要があります。他のすべてのインターフェースと同様に、リクエストが完了したときに適切なコールバックが確実にトリガーされるように、EOS_HPlatform ハンドルが動作していることが重要となります。

統計データを投入する

Stats インターフェースをユーザーの統計と結びつけるには、Developer Portal (デベロッパー ポータル) でゲームの統計を定義する必要があります。次に EOS_Stats_IngestStat を呼び出してアプリケーション内の統計データを投入し、EOS バックエンド に送信します。

統計データの投入が完了しても統計の送信と処理に時間がかかるため、バックエンドの更新がすぐに有効化しない場合があります。そうした事情から、統計を使用するアチーブメントも、ロック解除されるまで時間を要すことがあります。

EOS_Stats_IngestStat 関数が取るパラメータを以下に示します。

パラメータ説明
Handle有効な EOS_HStats ハンドル。
Options投入する統計データに関する情報を含む EOS_Stats_IngestStatsOptions 構造体。
ClientDataCompletionDelegate から返ってくる任意のデータ。
CompletionDelegate署名が EOS_Stats_OnIngestStatCompleteCallback と一致する関数。統計データの投入操作が完了したときに呼び出されます。

この関数が正常に完了すると EOS_Success の値で EOS_EResult を返し、正しいオプションでない場合は EOS_InvalidParameters を返します。

統計データの投入オプション

EOS_Stats_IngestStatOptions 構造体のパラメータを以下に示します。

パラメータ説明
ApiVersionEOS_STATS_INGESTSTAT_API_LATEST に設定します。
LocalUserId統計データを投入するユーザーのアカウント ID を表す、有効な EOS_ProductUserId
Stats投入する統計情報を含む EOS_Stats_IngestData 構造体のリスト。
StatsCount投入する統計の数。
TargetUserId投入する特定のターゲット ユーザー ID。

データを投入する

特定の統計情報を含む EOS_Stats_IngestData 構造体のパラメータを以下に示します。

パラメータ説明
ApiVersionEOS_STATS_INGESTDATA_API_LATEST に設定します。
StatName投入する統計の名前。
IngestAmount統計に送信する整数値。

統計の完全なコールバック情報を投入する

操作が完了すると EOS_Stats_IngestStat に提供した CompletionDelegate をすべて呼び出します。これらは EOS_Stats_IngestStatCompleteCallbackInfo 構造体を返し、そのパラメータは以下の通りです。

パラメータ説明
ResultCodeリクエストが成功した場合の、EOS_Success の値を持つ EOS_EResult。これ以外のコードはすべてエラーを示します。
ClientDataClientData パラメータを使用して EOS_Stats_IngestStat に渡したコンテキスト。
UserId統計を読み込むユーザーのアカウント ID を表す、有効な EOS_ProductUserId

統計をクエリする

関数 EOS_Stats_QueryStats を使用して EOS バックエンドからユーザーの統計のリストを要求できます。この操作が完了すると、統計は関数自体から返されずローカルにキャッシュされます。詳細は、「統計をコピーする」セクションを参照してください。

EOS_Stats_QueryStats 関数が取るパラメータを以下に示します。

パラメータ説明
Handle有効な EOS_HStats ハンドル。
Options統計を取得するプレイヤーに関する情報を含む EOS_Stats_QueryStatsOptions 構造体。
ClientDataCompletionDelegate から返ってくる任意のデータ。
CompletionDelegate署名が EOS_Stats_OnQueryStatsCompleteCallback と一致する関数。統計データの投入操作が完了したときに呼び出されます。

統計をクエリするオプション

EOS_Stats_QueryStatsOptions 構造体は、クエリする対象のユーザーに関する情報、そして取得する統計の範囲を絞り込むオプションのパラメータを含みます。このパラメータを以下に示します。パラメータを以下に示します。

パラメータ説明
ApiVersionEOS_STATS_QUERYSTATS_API_LATEST に設定します。
UserId統計データを投入するユーザーのアカウント ID を表す、有効な EOS_ProductUserId
StartTime (オプション)EOS_STATS_TIME_UNDEFINED でない場合、これは開始時刻の POSIX タイムスタンプとなります。
EndTime (オプション)EOS_STATS_TIME_UNDEFINED でない場合、これは終了時刻の POSIX タイムスタンプとなります。
StatNames (オプション)クエリする固有の統計名のリスト。
StatNamesCount (オプション)StatNames にリストされた名前の数。

StartTimeEndTime のパラメータが設定されている場合、指定した開始時間と終了時間の間にクエリが制限されます。

統計のクエリが完了した時のコールバック情報

操作が完了すると EOS_Stats_QueryStats に提供した CompletionDelegate を呼び出します。これらは以下のパラメータを持つ EOS_Stats_OnQueryStatsCompleteCallbackInfo 構造体を返します。

パラメータ説明
ResultCodeリクエストが成功した場合の、EOS_Success の値を持つ EOS_EResult。これ以外のコードはすべてエラーを示します。
ClientDataClientData パラメータを使用して EOS_Stats_QueryStats に渡したコンテキスト。
UserId統計データを投入するユーザーのアカウント ID を表す、有効な EOS_ProductUserId

統計をコピーする

EOS_Stats_QueryStats の操作が正常に完了すると、要求された統計はローカルにキャッシュされます。次に EOS_Stats_CopyStatByIndexEOS_Stats_CopyStatByName を使用してローカルのキャッシュから特定の統計のコピーを取得します。

EOS 統計の構造体

統計情報をコピーする関数は EOS_Stats_Stat 構造体を返し、これは特定の 1 人のプレイヤーの統計情報を表します。このプロパティを以下に示します。

プロパティ説明
ApiVersionEOS_STATS_STAT_API_LATEST に設定します。
NameDeveloper Portal に表示する統計の名前。
StartTimeEOS_STATS_TIME_UNDEFINED でない場合、この統計を返したクエリを開始した時間の POSIX タイムスタンプとなります。
EndTimeEOS_STATS_TIME_UNDEFINED でない場合、この統計を返したクエリが終了した時間の POSIX タイムスタンプとなります。
Value整数で表した現在の統計値。

統計カウントを取得する

プレイヤーの統計を正常にクエリしたら、EOS_Stats_GetStatsCount を使用してローカルにキャッシュされた統計のカウントを確認できます。この関数が取るパラメータを以下に示します。この関数が取るパラメータを以下に示します。

パラメータ説明
Handle有効な EOS_HStats ハンドル。
OptionsEOS_Stats_GetStatCountOptions 構造体。これは EOS_STATS_GETSTATCOUNT_API_LATEST の値に設定された ApiVersion と、統計カウントを取得するユーザーの有効な EOS_ProductUserId に設定された UserId で構成されます。

この関数は現在キャッシュしている統計の数を整数で返します。

インデックスで統計をコピーする

関数 EOS_Stats_CopyStatByIndex は、キャッシュした統計のリストから、特定のインデックスに基づいて統計のコピーをフェッチします。このパラメータを以下に示します。パラメータを以下に示します。

パラメータ説明
Handle有効な EOS_HStats ハンドル。
Options統計を取得するキャッシュの、目的のインデックスを含む EOS_Stats_CopyStatByIndexOptions 構造体。
OutStat目的の統計情報を含む、種類 EOS_Stats_Stat の出力パラメータ。終了したら EOS_Stats_Stat_Release を使用します。

操作が完了すると、出力パラメータ OutStat を使用して目的の EOS_Stats_Stat を出力します。この関数の戻り値は EOS_EResult です。利用できる情報が OutStat で正常に渡された場合、この値が EOS_Success になります。無効なパラメータを含むか、出力パラメータが null ポインタを含む場合、この値は EOS_InvalidParameters になります。また要求した統計が見つからない場合、この値は EOS_NotFound になります。

インデックスで統計をコピーする際のオプション

EOS_Stats_CopyStatByIndex で要求した統計インデックスを含む EOS_Stats_CopyStatByIndexOptions 構造体です。このパラメータを以下に示します。パラメータを以下に示します。

パラメータ説明
ApiVersionEOS_STATS_COPYSTATBYINDEX_API_LATEST に設定します。
UserId統計のコピーを取得するユーザーのアカウント ID を表す、有効な EOS_ProductUserId
StatIndexキャッシュ済み統計リストのインデックスを参照する整数。

名前で統計をコピーする

EOS_Stats_CopyStatByName 関数は、Developer Portal で指定した統計の名前に基づいて、統計のコピーをフェッチします。パラメータを以下に示します。

パラメータ説明
Handle有効な EOS_HStats ハンドル。
Optionsキャッシュからフェッチする統計の名前を含む EOS_Stats_CopyStatByNameOptions 構造体。
OutStat目的の統計情報を含む、種類 EOS_Stats_Stat の出力パラメータ。終了したら EOS_Stats_Stat_Release を使用します。

操作が完了すると、出力パラメータ OutStat を使用して目的の EOS_Stats_Stat を出力します。この関数の戻り値は EOS_EResult です。利用できる情報が OutStat で正常に渡された場合、この値が EOS_Success になります。無効なパラメータを含むか、出力パラメータが null ポインタを含む場合、このパラメータの値は EOS_InvalidParameters になります。要求した統計が見つからない場合、この値は EOS_NotFound になります。

名前で統計をコピーする際のオプション

EOS_Stats_CopyStatByName で要求した統計インデックスを含む EOS_Stats_CopyStatByNameOptions 構造体。パラメータを以下に示します。

パラメータ説明
ApiVersionEOS_STATS_COPYSTATBYNAME_API_LATEST に設定します。
UserId統計のコピーを取得するユーザーのアカウント ID を表す、有効な EOS_ProductUserId
StatNameコピーをフェッチする統計の名前。

キャッシュ済み統計のメモリを解放する

EOS_Stats_CopyStatByIndex で統計データを取得したら、EOS_Stats_Stat_Release を呼び出してこの統計に関連するメモリを解放する必要があります。この関数は、EOS_Stats_CopyStatByName または EOS_Stats_CopyStatByIndexOutStat パラメータで出力した EOS_Stats_Stat 構造体を取ります。

使用上の制限事項

Stats インターフェース は、デベロッパーにアプリケーションのユーザーに関する統計を管理し、収集したアイテムの数、プレイヤーの最速レベル完了時間、勝負の成績、ユーザーが特定のアクションを実行した回数など、デベロッパーが追跡したい統計データを含めることができます。統計情報を使って、アチーブメントをアンロックするタイミングを判断したり、リーダーボードでユーザーのランク付け方法を決定することができます。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「」を参照してください。

以下の制限事項はすべての統計システムに適用されます。

機能制限事項
統計情報数500 / デプロイメント
統計情報名の文字数256 文字
コールあたりの読み込み最大統計情報数3000
最大マイルストーン (デフォルト)100

統計の読み込み はサービスに統計情報の変更をサブミットするエンドポイントで、ユーザーレートが制限されます。ユーザーの代わりに専用サーバーが統計情報をサブミットするとき、ユーザーあたりの制限は適用されません。このケースでは、制限事項はその時のデプロイメントあたりの同時接続数 (CCU) に基づきます。

使用タイプユーザーあたりの制限デプロイメントあたりの制限
統計情報の読み込み60 リクエスト / 分、 500 統計情報 / リクエスト1 リクエスト / 5 CCU / 分
PlayerId ごとの統計情報の取得100 リクエスト / 分-
Get Stats by PlayerIds100 リクエスト / 分、 64 プレイヤー / リクエスト、 25 統計情報 / プレイヤー-
統計情報の作成-100 リクエスト / 分
統計情報の削除-100 リクエスト / 分

アチーブメントと統計をテストする

テスト用サンドボックスでアチーブメントのテストを行う場合、そのサンドボックスへのデプロイメントに統計情報を含める必要があります。ライブ環境にデプロイする前にこの作業を行うことで、統計情報の構造エラーを確認し、プレイヤーが正常にアチーブメントの解除が可能であることを確認できます。

ゲームのテスト用サンドボックスの作成については、製品、サンドボックス、およびデプロイメントIDのドキュメントを参照してください。