Stats Interface

Interface for managing stats.

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_IngestStatsOptions 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.

UserId

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.

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_QueryStatOptions 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_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:

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 ingested.

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

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