Stats Interface

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.

The parameters taken by the EOS_Stats_IngestStat function are as follows:

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:

Ingest Data

The EOS_Stats_IngestData structure contains information for a specific stat. Its parameters are as follows:

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:

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:

Query Stat Options

The EOS_Stats_QueryStatOptions 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:

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:

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:

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:

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:

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:

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:

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:

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

Please consult the Service Usage Limitations page for information about usage limits that you should observe to maintain performance and speed.