Stats Interface

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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