Stats インターフェース は、デベロッパーにアプリケーションのユーザーに関する 統計 を管理する機能を提供し、収集したアイテムの数、プレイヤーの最速レベル完了時間、勝負の成績、ユーザーが特定のアクションを実行した回数など、デベロッパーが追跡したい統計データを含めることができます。統計情報を使って、アチーブメント をアンロックするタイミングを判断したり リーダーボード でユーザーのランク付け方法を決定することができます。
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_INGESTSTAT_API_LATEST に設定します。 |
|
|
統計データを投入するユーザーのアカウント ID を表す、有効な |
|
|
投入する統計情報を含む |
|
|
投入する統計の数。 |
|
|
投入する特定のターゲット ユーザー ID。 |
データを投入する
特定の統計情報を含む EOS_Stats_IngestData 構造体のパラメータを以下に示します。
|
パラメータ |
説明 |
|---|---|
|
|
|
|
|
投入する統計の名前。 |
|
|
統計に送信する整数値。 |
統計の完全なコールバック情報を投入する
操作が完了すると EOS_Stats_IngestStat に提供した CompletionDelegate をすべて呼び出します。これらは EOS_Stats_IngestStatCompleteCallbackInfo 構造体を返し、そのパラメータは以下の通りです。
|
パラメータ |
説明 |
|---|---|
|
|
リクエストが成功した場合の、 |
|
|
|
|
|
統計を読み込むユーザーのアカウント ID を表す、有効な |
統計をクエリする
関数 EOS_Stats_QueryStats を使用して EOS バックエンドからユーザーの統計のリストを要求できます。この操作が完了すると、統計は関数自体から返されずローカルにキャッシュされます。詳細は、「統計をコピーする」セクションを参照してください。
EOS_Stats_QueryStats 関数が取るパラメータを以下に示します。
|
パラメータ |
説明 |
|---|---|
|
|
有効な |
|
|
統計を取得するプレイヤーに関する情報を含む |
|
|
|
|
|
署名が |
統計をクエリするオプション
EOS_Stats_QueryStatsOptions 構造体は、クエリする対象のユーザーに関する情報、そして取得する統計の範囲を絞り込むオプションのパラメータを含みます。このパラメータを以下に示します。パラメータを以下に示します。
|
パラメータ |
説明 |
|---|---|
|
|
|
|
|
統計データを投入するユーザーのアカウント ID を表す、有効な |
|
|
|
|
|
|
|
|
クエリする固有の統計名のリスト。 |
|
|
|
StartTime や EndTime のパラメータが設定されている場合、指定した開始時間と終了時間の間にクエリが制限されます。
統計のクエリが完了した時のコールバック情報
操作が完了すると EOS_Stats_QueryStats に提供した CompletionDelegate を呼び出します。これらは以下のパラメータを持つ EOS_Stats_OnQueryStatsCompleteCallbackInfo 構造体を返します。
|
パラメータ |
説明 |
|---|---|
|
|
リクエストが成功した場合の、 |
|
|
|
|
|
統計データを投入するユーザーのアカウント ID を表す、有効な |
統計をコピーする
EOS_Stats_QueryStats の操作が正常に完了すると、要求された統計はローカルにキャッシュされます。次に EOS_Stats_CopyStatByIndex や EOS_Stats_CopyStatByName を使用してローカルのキャッシュから特定の統計のコピーを取得します。
EOS 統計の構造体
統計情報をコピーする関数は EOS_Stats_Stat 構造体を返し、これは特定の 1 人のプレイヤーの統計情報を表します。このプロパティを以下に示します。
|
プロパティ |
説明 |
|---|---|
|
|
|
|
|
Developer Portal に表示する統計の名前。 |
|
|
|
|
|
|
|
|
整数で表した現在の統計値。 |
統計カウントを取得する
プレイヤーの統計を正常にクエリしたら、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 構造体です。このパラメータを以下に示します。パラメータを以下に示します。
|
パラメータ |
説明 |
|---|---|
|
|
|
|
|
統計のコピーを取得するユーザーのアカウント ID を表す、有効な |
|
|
キャッシュ済み統計リストのインデックスを参照する整数。 |
名前で統計をコピーする
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 構造体。パラメータを以下に示します。
|
パラメータ |
説明 |
|---|---|
|
|
|
|
|
統計のコピーを取得するユーザーのアカウント ID を表す、有効な |
|
|
コピーをフェッチする統計の名前。 |
キャッシュ済み統計のメモリを解放する
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 リクエスト / 分 |