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 構造体。 |
ClientData | CompletionDelegate から返ってくる任意のデータ。 |
CompletionDelegate | 署名が EOS_Stats_OnIngestStatCompleteCallback と一致する関数。統計データの投入操作が完了したときに呼び出されます。 |
この関数が正常に完了すると EOS_Success
の値で EOS_EResult
を返し、正しいオプションでない場合は EOS_InvalidParameters
を返します。
統計データの投入オプション
EOS_Stats_IngestStatOptions
構造体のパラメータを以下に示します。
パラメータ | 説明 |
---|---|
ApiVersion | EOS_STATS_INGESTSTAT_API_LATEST に設定します。 |
LocalUserId | 統計データを投入するユーザーのアカウント ID を表す、有効な EOS_ProductUserId 。 |
Stats | 投入する統計情報を含む EOS_Stats_IngestData 構造体のリスト。 |
StatsCount | 投入する統計の数。 |
TargetUserId | 投入する特定のターゲット ユーザー ID。 |
データを投入する
特定の統計情報を含む EOS_Stats_IngestData
構造体のパラメータを以下に示します。
パラメータ | 説明 |
---|---|
ApiVersion | EOS_STATS_INGESTDATA_API_LATEST に設定します。 |
StatName | 投入する統計の名前。 |
IngestAmount | 統計に送信する整数値。 |
統計の完全なコールバック情報を投入する
操作が完了すると EOS_Stats_IngestStat
に提供した CompletionDelegate
をすべて呼び出します。これらは EOS_Stats_IngestStatCompleteCallbackInfo
構造体を返し、そのパラメータは以下の通りです。
パラメータ | 説明 |
---|---|
ResultCode | リクエストが成功した場合の、EOS_Success の値を持つ EOS_EResult 。これ以外のコードはすべてエラーを示します。 |
ClientData | ClientData パラメータを使用して EOS_Stats_IngestStat に渡したコンテキスト。 |
UserId | 統計を読み込むユーザーのアカウント ID を表す、有効な EOS_ProductUserId 。 |
統計をクエリする
関数 EOS_Stats_QueryStats
を使用して EOS バックエンドからユーザーの統計のリストを要求できます。この操作が完了すると、統計は関数自体から返されずローカルにキャッシュされます。詳細は、「統計をコピーする」セクションを参照してください。
EOS_Stats_QueryStats
関数が取るパラメータを以下に示します。
パラメータ | 説明 |
---|---|
Handle | 有効な EOS_HStats ハンドル。 |
Options | 統計を取得するプレイヤーに関する情報を含む EOS_Stats_QueryStatsOptions 構造体。 |
ClientData | CompletionDelegate から返ってくる任意のデータ。 |
CompletionDelegate | 署名が EOS_Stats_OnQueryStatsCompleteCallback と一致する関数。統計データの投入操作が完了したときに呼び出されます。 |
統計をクエリするオプション
EOS_Stats_QueryStatsOptions
構造体は、クエリする対象のユーザーに関する情報、そして取得する統計の範囲を絞り込むオプションのパラメータを含みます。このパラメータを以下に示します。パラメータを以下に示します。
パラメータ | 説明 |
---|---|
ApiVersion | EOS_STATS_QUERYSTATS_API_LATEST に設定します。 |
UserId | 統計データを投入するユーザーのアカウント ID を表す、有効な EOS_ProductUserId 。 |
StartTime (オプション) | EOS_STATS_TIME_UNDEFINED でない場合、これは開始時刻の POSIX タイムスタンプとなります。 |
EndTime (オプション) | EOS_STATS_TIME_UNDEFINED でない場合、これは終了時刻の POSIX タイムスタンプとなります。 |
StatNames (オプション) | クエリする固有の統計名のリスト。 |
StatNamesCount (オプション) | StatNames にリストされた名前の数。 |
StartTime
や EndTime
のパラメータが設定されている場合、指定した開始時間と終了時間の間にクエリが制限されます。
統計のクエリが完了した時のコールバック情報
操作が完了すると EOS_Stats_QueryStats
に提供した CompletionDelegate
を呼び出します。これらは以下のパラメータを持つ EOS_Stats_OnQueryStatsCompleteCallbackInfo
構造体を返します。
パラメータ | 説明 |
---|---|
ResultCode | リクエストが成功した場合の、EOS_Success の値を持つ EOS_EResult 。これ以外のコードはすべてエラーを示します。 |
ClientData | ClientData パラメータを使用して EOS_Stats_QueryStats に渡したコンテキスト。 |
UserId | 統計データを投入するユーザーのアカウント ID を表す、有効な EOS_ProductUserId 。 |
統計をコピーする
EOS_Stats_QueryStats
の操作が正常に完了すると、要求された統計はローカルにキャッシュされます。次に EOS_Stats_CopyStatByIndex
や EOS_Stats_CopyStatByName
を使用してローカルのキャッシュから特定の統計のコピーを取得します。
EOS 統計の構造体
統計情報をコピーする関数は EOS_Stats_Stat
構造体を返し、これは特定の 1 人のプレイヤーの統計情報を表します。このプロパティを以下に示します。
プロパティ | 説明 |
---|---|
ApiVersion | EOS_STATS_STAT_API_LATEST に設定します。 |
Name | Developer Portal に表示する統計の名前。 |
StartTime | EOS_STATS_TIME_UNDEFINED でない場合、この統計を返したクエリを開始した時間の POSIX タイムスタンプとなります。 |
EndTime | EOS_STATS_TIME_UNDEFINED でない場合、この統計を返したクエリが終了した時間の POSIX タイムスタンプとなります。 |
Value | 整数で表した現在の統計値。 |
統計カウントを取得する
プレイヤーの統計を正常にクエリしたら、EOS_Stats_GetStatsCount
を使用してローカルにキャッシュされた統計のカウントを確認できます。この関数が取るパラメータを以下に示します。この関数が取るパラメータを以下に示します。
パラメータ | 説明 |
---|---|
Handle | 有効な EOS_HStats ハンドル。 |
Options | EOS_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
構造体です。このパラメータを以下に示します。パラメータを以下に示します。
パラメータ | 説明 |
---|---|
ApiVersion | EOS_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
構造体。パラメータを以下に示します。
パラメータ | 説明 |
---|---|
ApiVersion | EOS_STATS_COPYSTATBYNAME_API_LATEST に設定します。 |
UserId | 統計のコピーを取得するユーザーのアカウント ID を表す、有効な EOS_ProductUserId 。 |
StatName | コピーをフェッチする統計の名前。 |
キャッシュ済み統計のメモリを解放する
EOS_Stats_CopyStatByIndex
で統計データを取得したら、EOS_Stats_Stat_Release
を呼び出してこの統計に関連するメモリを解放する必要があります。この関数は、EOS_Stats_CopyStatByName
または EOS_Stats_CopyStatByIndex
の OutStat
パラメータで出力した EOS_Stats_Stat
構造体を取ります。
使用上の制限事項
Stats インターフェース は、デベロッパーにアプリケーションのユーザーに関する統計を管理し、収集したアイテムの数、プレイヤーの最速レベル完了時間、勝負の成績、ユーザーが特定のアクションを実行した回数など、デベロッパーが追跡したい統計データを含めることができます。統計情報を使って、アチーブメントをアンロックするタイミングを判断したり、リーダーボードでユーザーのランク付け方法を決定することができます。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「」を参照してください。
以下の制限事項はすべての統計システムに適用されます。
機能 | 制限事項 |
---|---|
統計情報数 | 500 / デプロイメント |
統計情報名の文字数 | 256 文字 |
コールあたりの読み込み最大統計情報数 | 3000 |
最大マイルストーン (デフォルト) | 100 |
統計の読み込み はサービスに統計情報の変更をサブミットするエンドポイントで、ユーザーレートが制限されます。ユーザーの代わりに専用サーバーが統計情報をサブミットするとき、ユーザーあたりの制限は適用されません。このケースでは、制限事項はその時のデプロイメントあたりの同時接続数 (CCU) に基づきます。
使用タイプ | ユーザーあたりの制限 | デプロイメントあたりの制限 |
---|---|---|
統計情報の読み込み | 60 リクエスト / 分、 500 統計情報 / リクエスト | 1 リクエスト / 5 CCU / 分 |
PlayerId ごとの統計情報の取得 | 100 リクエスト / 分 | - |
Get Stats by PlayerIds | 100 リクエスト / 分、 64 プレイヤー / リクエスト、 25 統計情報 / プレイヤー | - |
統計情報の作成 | - | 100 リクエスト / 分 |
統計情報の削除 | - | 100 リクエスト / 分 |
アチーブメントと統計をテストする
テスト用サンドボックスでアチーブメントのテストを行う場合、そのサンドボックスへのデプロイメントに統計情報を含める必要があります。ライブ環境にデプロイする前にこの作業を行うことで、統計情報の構造エラーを確認し、プレイヤーが正常にアチーブメントの解除が可能であることを確認できます。
ゲームのテスト用サンドボックスの作成については、製品、サンドボックス、およびデプロイメントIDのドキュメントを参照してください。