The Stats Interface provides the ability for developers to manage users' stats for an application, which can include any statistical data that a developer wishes to track, such as the number of items collected, the player's fastest completion time for a level, the total number of victories or losses, or the number of times that a user has performed a certain action. You can use stats to determine when to unlock achievements and how to use rank users in leaderboards.
Accessing the Stats Interface
To access Stats Interface functions, you need to acquire an EOS_HStats handle by calling the EOS_Platform_GetStatsInterface function from the Platform Interface. Similarly to all other interfaces, it is important that the EOS_HPlatform handle is ticking to ensure that the appropriate callbacks are triggered when requests are completed.
Ingesting Stats
For the Stats Interface to interact with users' stats, you must define the stats for your game on the Developer Portal. You can then call EOS_Stats_IngestStat to ingest stats inside the application, which will submit them to the EOS backend.
Once a stat has been ingested the update on the backend may not take effect immediately, as it takes time to both submit and process the stat. As such, achievements using stats may also take a while to unlock.
The parameters taken by the EOS_Stats_IngestStat function are as follows:
| Parameter | Description |
|---|---|
Handle | A valid EOS_HStats handle. |
Options | An EOS_Stats_IngestStatOptions structure that contains information about the stat we are ingesting. |
ClientData | Arbitrary data that is passed back in CompletionDelegate. |
CompletionDelegate | A function whose signature is consistent with EOS_Stats_OnIngestStatCompleteCallback. Called when the ingest stat operation is complete. |
The function will return an EOS_EResult with a value of EOS_Success if it is completed successfully, and EOS_InvalidParameters if any of the options are incorrect.
Ingest Stat Options
The parameters for the EOS_Stats_IngestStatOptions struct are as follows:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_STATS_INGESTSTAT_API_LATEST. |
LocalUserId | A valid EOS_ProductUserId representing an account ID for the user whose stats are being ingested. |
Stats | A list of EOS_Stats_IngestData structures with information for the stats that we want to ingest. |
StatsCount | The number of stats to ingest. |
TargetUserId | A specific target user ID to ingest. |
Ingest Data
The EOS_Stats_IngestData structure contains information for a specific stat. Its parameters are as follows:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_STATS_INGESTDATA_API_LATEST. |
StatName | The name of the stat to ingest. |
IngestAmount | The integer value to submit for the stat. |
Ingest Stat Complete Callback Info
Any CompletionDelegate provided to EOS_Stats_IngestStat will be called when the operation is completed. These return an EOS_Stats_IngestStatCompleteCallbackInfo structure, whose parameters are as follows:
| Parameter | Description |
|---|---|
ResultCode | An EOS_EResult with a value of EOS_Success if the request was successful. All other codes indicate an error. |
ClientData | The context that was passed into EOS_Stats_IngestStat using its ClientData parameter. |
UserId | A valid EOS_ProductUserId representing the account ID for the user whose stats are being ingested. |
Querying Stats
The function EOS_Stats_QueryStats can be used to request a list of a user's stats from the EOS backend. When the operation completes, the stats are cached locally rather than returned through the function itself. See the Copying Stats section for more info.
The EOS_Stats_QueryStats function takes the following parameters:
| Parameter | Description |
|---|---|
Handle | A valid EOS_HStats handle. |
Options | An EOS_Stats_QueryStatsOptions structure containing information about the player whose stats we are retrieving. |
ClientData | Arbitrary data that is passed back in CompletionDelegate. |
CompletionDelegate | A function whose signature is consistent with EOS_Stats_OnQueryStatsCompleteCallback. Called when the ingest stat operation is complete. |
Query Stat Options
The EOS_Stats_QueryStatsOptions structure contains information about the user we are trying to query for, as well as optional parameters that can narrow the scope of the stats that we want to retrieve. Its parameters are as follows:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_STATS_QUERYSTATS_API_LATEST. |
UserId | A valid EOS_ProductUserId representing an account ID for the user whose stats are being retrieved. |
StartTime (Optional) | If not EOS_STATS_TIME_UNDEFINED then this is the POSIX timestamp for start time. |
EndTime (Optional) | If not EOS_STATS_TIME_UNDEFINED then this is the POSIX timestamp for end time. |
StatNames (Optional) | A list of specific stat names to query for. |
StatNamesCount (Optional) | The number of names listed in StatNames. |
If the StartTime and EndTime parameters are set, the query will be limited between the given start and end times.
On Query Stats Complete Callback Info
The CompletionDelegate provided to EOS_Stats_QueryStats will be called when the operation is completed. These return an EOS_Stats_OnQueryStatsCompleteCallbackInfo structure, which has the following parameters:
| Parameter | Description |
|---|---|
ResultCode | An EOS_EResult with a value of EOS_Success if the request was successful. All other codes indicate an error. |
ClientData | The context that was passed into EOS_Stats_QueryStats using its ClientData parameter. |
UserId | A valid EOS_ProductUserId representing the account ID for the user whose stats are being ingested. |
Copying Stats
When EOS_Stats_QueryStats completes its operation successfully, the requested stats are cached locally. You can then use EOS_Stats_CopyStatByIndex or EOS_Stats_CopyStatByName to get a copy of a given stat from the local cache.
EOS Stats Structure
The functions for copying stat info return an EOS_Stats_Stat structure, which represents the information for a single, specific player stat. Its properties are as follows:
| Property | Description |
|---|---|
ApiVersion | Set to EOS_STATS_STAT_API_LATEST. |
Name | The name of the stat as it appears in the Developer Portal. |
StartTime | If not EOS_STATS_TIME_UNDEFINED then this is the POSIX timestamp for the start time of the query that returned this stat. |
EndTime | If not EOS_STATS_TIME_UNDEFINED then this is the POSIX timestamp for the end time of the query that returned this stat. |
Value | The current value of the stat as an integer. |
Getting Stats Count
Once you have successfully queried a player's stats, you can use EOS_Stats_GetStatsCount to check the number of stats that are locally cached. This function takes the following parameters:
| Parameter | Description |
|---|---|
Handle | A valid EOS_HStats handle. |
Options | An EOS_Stats_GetStatCountOptions structure consisting of an ApiVersion set to a value of EOS_STATS_GETSTATCOUNT_API_LATEST, and a UserId set to a valid EOS_ProductUserId for the user whose stat count we are retrieving. |
This function returns an integer representing the number of stats that are currently cached.
Copy Stat By Index
The function EOS_Stats_CopyStatByIndex fetches a copy of a stat based on a given index in the list of cached stats. Its parameters are as follows:
| Parameter | Description |
|---|---|
Handle | A valid EOS_HStats handle. |
Options | An EOS_Stats_CopyStatByIndexOptions struct containing the desired index within the cache to fetch a stat from. |
OutStat | An out parameter of the type EOS_Stats_Stat containing the desired stat's information. Use EOS_Stats_Stat_Release when finished. |
The out parameter OutStat is used to output the desired EOS_Stats_Stat when the operation completes. The return value of the function is an EOS_EResult. It will have a value of EOS_Success if the information is available and successfully passed out through OutStat. If any of the parameters are invalid or a null pointer is provided for the out parameter, then it will have a value of EOS_InvalidParameters, and if the requested stat is not found it will have a value of EOS_NotFound.
Copy Stat By Index Options
The EOS_Stats_CopyStatByIndexOptions structure the requested stat index for EOS_Stats_CopyStatByIndex. Its parameters are as follows:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_STATS_COPYSTATBYINDEX_API_LATEST. |
UserId | A valid EOS_ProductUserId representing the account ID for the user whose stats we are getting a copy of. |
StatIndex | An integer referring to the index within the cached list of stats. |
Copy Stat By Name
The EOS_Stats_CopyStatByName function fetches a copy of a stat based on the stat's name as given in the Developer Portal. Its parameters are as follows:
| Parameter | Description |
|---|---|
Handle | A valid EOS_HStats handle. |
Options | An EOS_Stats_CopyStatByNameOptions struct containing the name of the stat to fetch from the cache. |
OutStat | An out parameter of the type EOS_Stats_Stat containing the desired stat's information. Use EOS_Stats_Stat_Release when finished. |
The out parameter OutStat is used to output the desired EOS_Stats_Stat when the operation completes. The return value of the function is an EOS_EResult. It will have a value of EOS_Success if the information is available and successfully passed out through OutStat. If any of the parameters are invalid or a null pointer is provided for the out parameter, then it will have a value of EOS_InvalidParameters. If the requested stat is not found it will have a value of EOS_NotFound.
Copy Stat By Name Options
The EOS_Stats_CopyStatByNameOptions structure contains the requested stat index for EOS_Stats_CopyStatByName. Its parameters are as follows:
| Parameter | Description |
|---|---|
ApiVersion | Set to EOS_STATS_COPYSTATBYNAME_API_LATEST. |
UserId | A valid EOS_ProductUserId representing the account ID for the user whose stats we are getting a copy of. |
StatName | The name of the stat we are fetching a copy of. |
Releasing Memory from Cached Stats
After retrieving a stat's data with EOS_Stats_CopyStatByIndex, you must call EOS_Stats_Stat_Release to release the memory associated with that stat. This function takes in the EOS_Stats_Stat structure output by the OutStat parameter of either EOS_Stats_CopyStatByName or EOS_Stats_CopyStatByIndex.
Usage Limitations
The Stats Interface manages users' stats for an application, which can include any statistical data that a developer wishes to track, such as the number of items collected, the player's fastest completion time for a level, the total number of victories or losses, or the number of times that a user has performed a certain action. You can use stats to determine when to unlock achievements and how to use rank users in leaderboards. For general information about throttling, usage quotas, and best practices, see Service Usage Limitations.
The following limits apply to the overall Stats system:
| Feature | Limitation |
|---|---|
| Number of stats | 500 per deployment |
| Stat name length | 256 characters |
| Max stats ingested per call | 3000 |
| Max milestones (default) | 100 |
Stats Ingestion is the endpoint for submitting stat changes to the service, and has a per-user rate limit. When a dedicated server submits stats on behalf of users, the per-user limits do not apply; in these cases, limits are based on the number of concurrent users (CCU) per deployment at that time.
| Usage Type | Per-User Limit | Per-Deployment Limit |
|---|---|---|
| Ingest stats | 60 requests per minute, 500 stats per request | 1 request per 5 CCU per minute |
| Get stats by Player ID | 100 requests per minute | - |
| Get stats by Player IDs | 100 requests per minute, 64 players per request, 25 stats per player | - |
| Create Stat | - | 100 requests per minute |
| Delete Stat | - | 100 requests per minute |
Test Your Achievements and Stats
If you want to test your achievements in a test sandbox, you must also include your stats in a deployment to that sandbox. You should do this before you deploy to your live environment, so that you can check for errors in the stats structure and make sure that players can unlock achievements successfully.
For more information on creating a test sandbox for your game, see the documentation on Product, Sandbox, and Deployment IDs.