Statistics

Overview

The Statistics service provides game developers with persistent statistic tracking for their game. Tracked statistics include gameplay related stats such as kill, die, and assist, and internal game data such as map played and game modes played. Statistics are tied to players and can be easily integrated or displayed as game profile attributes through the game profile service.

The statistics service also acts as the reference point for consistent value tracking across other services such as Progression, Achievements, and Leaderboards. We use messaging to update statistics values asynchronously to other related services in real-time. You only need to define the statistics you want to measure once, and they’ll be applied to all related services.

Tutorials

Create a New Statistic Configuration

Create a New Statistic Configuration Using the API

  1. Use the Create Stat: POST - /v1/admin/namespaces/{namespace}/stats endpoint.
  2. Input the Namespace field with the game namespace.
  3. Fill out the Request Body:
    • Input the Default Value of the statistic.
    • Input a Description of the configuration. This field is optional.
    • Input the Increment value. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.
    • Define the maximum value of the statistic in Max. Value field.
    • Define the minimum value of the statistic in the Min. Value field.
    • Input the Name of the configuration.
    • Input the Set As Global value. If set to true, every time the stat is updated the global stat value will also be updated.
    • Input the Set By value. You can input either the game client or game server. This determines which client will update the stat value.
    • Input the statistic code in the Code field, following the formatting rules below:
      • Only lowercase alphanumeric (a-z and 0-9) characters are allowed
      • Spaces a not allowed
      • The code must start and end in a lowercase letter
      • Hyphens (-) are the only separator allowed
      • Separators cannot appear twice or more in a row
    • Input the Tag field with contextual information related to the statistic. This field is optional. Upon successful request, a new statistic configuration will be created.

Create a New Statistic Configuration Through the Admin Portal

  1. In the Statistics section of the Admin Portal, open the Configurations menu.

    cloud-save

  1. In the Statistic Configurations window, click the Add Configuration button.

    cloud-save

  1. Fill in the required fields.

    cloud-save

  • Input the statistic code in the Code field, following the formatting rules given.
  • Input the Name of the configuration.
  • Input a Description of the configuration. This field is optional.
  • Define the minimum value of the statistic in the Min. Value field.
  • Define the maximum value of the statistic in Max. Value field.
  • Input the Default Value of the statistic.
  • Choose the Increment value. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.
  • Choose the Set As Global value. If set to true, every time the stat is updated the global stat value will also be updated.
  • Select the Set By value. You can select either the game client or game server. This determines which client will update the stat value.
  • Input the Tag field with contextual information related to the statistic. This field is optional.

Create Statistics for Players

Create a Single Statistic for a Player Using the API

To create a statistic for a player, follow the steps below.

  1. Use the Create User’s Stat Item: POST - /v1/admin/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems endpoint.
  2. Input the Namespace field with the game namespace.
  3. Input the User ID you want to tie to the statistic.
  4. Input the Stat Code to be tied to the user.

Upon successful request, the statistic configuration will be tied to the specified user.

Create a Single Statistic for a Player Using the SDK

You can use SDK to create a statistic for a player from your game server by following the example below.

FAccelByteModelsUserStatItemInfo CreateStatItemResult;
FString UserId = "Player'sUserId";
FString StatCode = TEXT("TOTAL_KILLS");
FRegistry::ServerStatistic.CreateUserStatItem(UserId, StatCode, THandler<FAccelByteModelsUserStatItemInfo>::CreateLambda([&CreateStatItemResult](FAccelByteModelsUserStatItemInfo Result)
{
GetUserStatItemResult = Result;
UE_LOG(LogTemp, Log, TEXT("Create User StatItems SUCCESS!"));
}), FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage) {
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

Create a Multiple Statistics for a Player Using the API

To create multiple statistics for a player, follow the steps below.

  1. Use the Bulk Create Users Stat Items: POST - /v1/admin/namespaces/{namespace}/users/{userId}/statitems/bulk endpoint.
  2. Input the Namespace field with the game namespace.
  3. Input the User ID you want to tie to the statistic.
  4. Input the statCode to be tied to the user in the bulkStatItemCreateList. Here you can input several stat codes to be tied to the user.

Upon successful request, the statistic configurations will be tied to the specified user.

Create Multiple Statistics for a Player Using the SDK

To create statistics for a player in bulk, follow the example below.

TArray<FAccelByteModelsBulkStatItemCreate> BulkStatCodes;
BulkStatCodes.Add(FAccelByteModelsBulkStatItemCreate{"TOTAL_KILLS"});
BulkStatCodes.Add(FAccelByteModelsBulkStatItemCreate{"TOTAL_DIES"});
TArray<FAccelByteModelsBulkStatItemOperationResult> CreateStatItemResult;
FString UserId = "Player'sUserId";
FRegistry::ServerStatistic.BulkCreateUserStatItems(UserId, BulkStatCodes, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateLambda([&CreateStatItemResult](TArray<FAccelByteModelsBulkStatItemOperationResult> Result)
{
CreateStatItemResult = Result;
}), FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage) {
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

Retrieve a Player’s Statistics

Once you have tied a statistics configuration to a player, you can then retrieve the statistics that are tied to a specific player. You can do this using direct API calls or using our SDKs from your game client.

Retrieve All of a Player’s Statistics Using the API

To list all of a player’s statistics, follow these steps:

  1. Use the List User’s StatItems: GET - /v1/admin/namespaces/{namespace}/users/{userId}/statitems endpoint.
  2. Input the Namespace where the configuration belongs. This field is required.
  3. Input the player’s User ID. This field is required.
  4. Input the statCode of the statistic you want to retrieve.

The following fields are optional. You can fill them in if you want to paginate the results.

  1. Input the tags of the statistics to query player statistics attributes based on the specified tag.
  2. Input the offset of items you want to skip for the query.
  3. Input the limit with the maximum number of items you want to display.

Upon successful request, you will be able to retrieve all of a player’s statistics, based on the specified query parameters.

Retrieve a Player’s Statistic by StatCode Using the SDK

This example will only retrieve a playerer's statistic for the specified statCode in a game namespace.

const TArray<FString> StatCodes = {"TOTAL_KILLS", "TOTAL_DEATHS"};
FAccelByteModelsUserStatItemPagingSlicedResult GetResult;
FRegistry::Statistic.GetUserStatItemsByStatCodes(StatCodes, THandler<FAccelByteModelsUserStatItemPagingSlicedResult>::CreateLambda([this, &GetResult, &bGetUserStatItemsByStatCodesSuccess](const FAccelByteModelsUserStatItemPagingSlicedResult& Result)
{
UE_LOG(LogTemp, Log, TEXT("GET User STATITEMS SUCCESS!"));
GetResult = Result;
for (FAccelByteModelsUserStatItemInfo data : GetResult.Data)
{
UE_LOG(LogTemp, Log, TEXT("StatCode: %s | Value: %d"), *data.StatCode, data.Value);
}
}), FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage) {
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

Retrieving a Player’s Statistic by Tag

This example will only retrieve a player's statistic for the specified tag in a game namespace.

const TArray<FString> Tags = {"INCREMENT", "INGAME"};
FAccelByteModelsUserStatItemPagingSlicedResult GetResult;
FRegistry::Statistic.GetUserStatItemsByTags(Tags, THandler<FAccelByteModelsUserStatItemPagingSlicedResult>::CreateLambda([this, &GetResult, &bGetUserStatItemsByTagsSuccess](const FAccelByteModelsUserStatItemPagingSlicedResult& Result)
{
UE_LOG(LogTemp, Log, TEXT("GET User STATITEMS SUCCESS!"));
GetResult = Result;
for (FAccelByteModelsUserStatItemInfo data : GetResult.Data)
{
UE_LOG(LogTemp, Log, TEXT("StatCode: %s | Value: %d"), *data.StatCode, data.Value);
}
}), FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage) {
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

Update a Player’s Statistics

Player statistics can be updated throughout the game. You can either update a single player statistic, or update player statistics in bulk.

Update a Single Statistic for a Player Using the API

To update a player’s statistic, follow these steps:

  1. Use the Update User’s Statitem Value: PATCH - /v1/admin/namespaces/{namespace}/users/{userId}/stats/{statCode}/statitems/value** **endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Input the player’s User ID.
  4. Input the statCode of the statistic you want to update.
  5. Define the statItemInc. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.

Upon successful request, you will be able to update the player's statistic.

Update Multiple Statistics for Multiple Players Using the API

To update multiple statistics for multiple players, follow these steps.

  1. Use the Bulk Update Multiple User’s StatItem Value: PATCH - /v1/admin/namespaces/{namespace}/statitems/value/bulk endpoint.
  2. Input the Namespace where the configuration belongs.
  3. Define the statItemInc.
    • Input the inc value. If set to true, the stat value can only be increased. If false, the stat value can be increased or decreased.
    • Input the statCodes of the statistics you want to update.
    • Input the User IDs of the players whose statistics you want to update.

Upon successful request, you will be able to update the specified statistics.

Update Multiple Statistics for a Player Using the SDK

This example is used to update multiple statistics for a player simultaneously.

TArray<FAccelByteModelsBulkStatItemOperationResult> BulkAddUserStatItemResult;
FAccelByteModelsBulkStatItemInc MVP;
MVP.inc = 1;
MVP.statCode = "MVP";
FRegistry::Statistic.IncrementUserStatItems({ MVP }, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateLambda([&BulkAddUserStatItemResult](TArray<FAccelByteModelsBulkStatItemOperationResult> Result)
{
UE_LOG(LogTemp, Log, TEXT("Bulk Add User Stat Items Success!"));
BulkAddUserStatItemResult = Result;
for (FAccelByteModelsBulkStatItemOperationResult data : Result)
{
UE_LOG(LogTemp, Log, TEXT("StatCode: %s | Success: %d"), *data.StatCode, data.Success);
}
}), FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage) {
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

Update Multiple Statistics for Multiple Players

This example is used to update multiple statistics for multiple players simultaneously. This update must be authorized by a user with higher privileges, such as an admin.

const FString StatCode = "MVP";
TArray<FAccelByteModelsBulkUserStatItemInc> Data = {
FAccelByteModelsBulkUserStatItemInc {1, UserId1, StatCode},
FAccelByteModelsBulkUserStatItemInc {1, UserId2, StatCode}
};
TArray<FAccelByteModelsBulkStatItemOperationResult> IncrementResult;
FRegistry::ServerStatistic.IncrementManyUsersStatItems(
Data, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateLambda([](const TArray<FAccelByteModelsBulkStatItemOperationResult>& Result)
{
UE_LOG(LogTemp, Log, TEXT("Increment Many User Stat Items Success!"));
for (FAccelByteModelsBulkStatItemOperationResult Data : Result)
{
UE_LOG(LogTemp, Log, TEXT("StatCode: %s | Success: %d"), *Data.StatCode, Data.Success);
}
}), FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage) {
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

Global Statistics

Global statistics accumulate users’ statistics globally. It can be used for tracking purposes, so it is easier for you to track important game wide statistics in real-time. Global statistics also can be used to trigger further actions such as events, or announcements. You can query global statistics based on a specific namespace.

Retrieve Global Statistic s Using the API

To list all global statistics, follow the steps below.

  1. Use the List All Global Statistic Items: POST - ​/v1​/admin​/namespaces​/{namespace}​/globalstatitems endpoint.
  2. Input the Namespace where the configuration belongs. This field is required.

The following fields are optional. They can be filled in if you want to paginate your results.

  1. Input the offset of items you want to skip for the query.
  2. Input the limit with the maximum number of items you want to display.

Upon successful request, the global statistics will be retrieved.

Retrieve Global Statistics Through the Admin Portal

  1. In the Admin Portal, click the Statistics Value menu.

cloud-save

  1. Switch to the Global tab. Here you’ll see the global statistics.

cloud-save

Related Concepts