Skip to main content

Statistics

Last updated on

Overview​

AccelByte Gaming Services (AGS) Starter Statistics service provides game developers with persistent statistics tracking for their games. Tracked statistics include gameplay-related stats such as number of kills, wins, dies, assists, and internal game data such as maps 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 a reference point for consistent value tracking across other services such as Progression, Achievements, Matchmaking, and Leaderboards. We use messaging to update statistics values asynchronously in relation to other 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.

Managing Statistics in the Admin Portal​

Create a New Statistic Configuration​

  1. In the Admin Portal, open your desired game namespace, expand the Statistics menu, and select Configurations.

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

    create-a-new-statistics-configuration

  3. The Add New Configuration form will appear. Fill in the required fields.

    create-a-new-statistics-configuration

    • Input the statistic code in the Code field, using a hyphen (-) as the separator. For example: total-skins-owned, total-kills, etc.
    • Input the name of the configuration in the Name field.
    • Input a description of the configuration in the Description field. 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. Players are assigned this value when they join your game for the first time.
    • Choose the Increment. If set to True, the stat value can only be increased over time through gameplay. If False, the stat value can be increased or decreased.
    • Choose the Set As Global. 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

View Statistics Value​

You can view an individual player’s statistics for monitoring purposes, or view global statistics.

  1. In the Admin Portal, open the desired game title, expand the Statistics menu, and select the Statistics Value option.

  2. The Statistics Value page will appear with two tabs: Player and Global.

    a. The Player tab allows you to view a specific user’s statistics, i.e., Stat Code, Stat Name, and Current Value. Our user search allows fuzzy search, meaning that you can find the player you’re looking for by typing just the first few characters of the player’s credentials rather than their full name or email address.

    view-a-player's-statistics

    b. The Global tab allows you to view the global statistics tied to a specific game title. The Global Value column indicates an aggregated value which is collected from each player.

    view-a-player's-statistics

Implementing Statistics Using the Client SDKs​

In this section, you will learn how to use the Client SDKs to manage the statistics for a player.

Create Statistics for a Player​

Use the following code to create a new statistic item for a player.

TArray<FString> StatCodes;
StatCodes.Add(FString("coin"));
StatCodes.Add(FString("popularity"));

FRegistry::Statistic.CreateUserStatItems(
StatCodes, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateWeakLambda(this, [](const TArray<FAccelByteModelsBulkStatItemOperationResult>& Result)
{
    // Do something if CreateUserStatItems has been successful
}), 
FErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if CreateUserStatItems has an error
    UE_LOG(LogTemp, Error, TEXT("Error CreateUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Increment User Stat Items​

Use the following code to increment the user statistic items. You can increment multiple statistic codes with certain values simultaneously.

TArray<FAccelByteModelsBulkStatItemInc> Data;
FAccelByteModelsBulkStatItemInc Data1;
Data1.statCode = FString("coin");
Data1.inc = 500;
Data.Add(Data1);

FAccelByteModelsBulkStatItemInc Data2;
Data2.statCode = FString("popularity");
Data2.inc = 2500;
Data.Add(Data2);

FRegistry::Statistic.IncrementUserStatItems(
Data, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateWeakLambda(this, [](const FAccelByteModelsBulkStatItemOperationResult& Result)
{
    // Do something if IncrementUserStatItems has been successful
}), 
FErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if IncrementUserStatItems has an error
    UE_LOG(LogTemp, Error, TEXT("Error IncrementUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve a Player’s Statistic by StatCode or Tag​

Use the following code to retrieve a player’s statistic by a specific StatCodes or Tags. This call return will only contain stat items specified by statCodes and tags.

TArray<FString> StatCodes;
StatCodes.Add(FString("Kill"));
StatCodes.Add(FString("Death"));
StatCodes.Add(FString("Assist"));

TArray<FString> Tags;
Tags.Add(FString("Tag1"));
Tags.Add(FString("Tag2"));
Tags.Add(FString("Tag3"));

FRegistry::Statistic.GetUserStatItems(
StatCodes, 
Tags, THandler<FAccelByteModelsUserStatItemPagingSlicedResult>::CreateWeakLambda(this, [](const FAccelByteModelsUserStatItemPagingSlicedResult& Result)
{
    // Do something if GetUserStatItems has been successful
}), 
FErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserStatItems has an error
    UE_LOG(LogTemp, Error, TEXT("Error GetUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve All Players’ Statistics​

Use the following code to retrieve all stat items.

FRegistry::Statistic.GetAllUserStatItems(
THandler<FAccelByteModelsUserStatItemPagingSlicedResult>::CreateWeakLambda(this, [](const FAccelByteModelsUserStatItemPagingSlicedResult& Result)
{
    // Do something if GetALlUserStatItems has been successful
}), 
FErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetAllUserStatItems has an error
    UE_LOG(LogTemp, Error, TEXT("Error GetAllUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Reset Multiple Statistics​

Use the following code to reset a player's statistics to the default values in your game namespace. You can specify which statistics to reset.

NOTE

Resetting multiple statistics is not supported yet in the Unreal Engine AccelByte plugin.

List<StatItemReset> resets = new List<StatItemReset>();
        resets.Add(new StatItemReset
        {
            statCode = "coin"
        });
        resets.Add(new StatItemReset
        {
            statCode = "popularity"
        });

        AccelBytePlugin.GetStatistic().ResetUserStatItems(resets.ToArray(), result =>
        {
            if (result.IsError)
            {
                // Do something if ResetUserStatItems has an error
                Debug.Log($"Error ResetUserStatItems, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if ResetUserStatItems has been successful
            }
        });

Update Multiple Statistics​

Use the following code to update multiple statistics. There are four update strategies that you can use.

  • OVERRIDE: Update a player’s StatItem value.
  • INCREMENT: Add to or subtract from a player’s StatItem value.
  • MAX: Update a player’s StatItem with a specified value greater than the current value.
  • MIN: Update a player’s StatItem with a specified value lower than the current existing value.
EXAMPLE

Suppose you want to implement a ranking system for your game. Whenever your players lose a match, their stats value decreases, meaning they go down a rank. To do this, you can use the INCREMENT strategy with a negative value to subtract the value and set the Increment field to False.

You also can use additionalKey to add more additional information about the player. The additionalKey parameter is added as a suffix to userId and is used to support multi-level players' stat items such as character stat items. If provided, the user's stat items will be saved with the key userId_additionalKey.

TArray<FAccelByteModelsUpdateUserStatItemWithStatCode> UserStatItems;

FAccelByteModelsUpdateUserStatItemWithStatCode Data1;
Data1.StatCode = "coin";
Data1.UpdateStrategy = EAccelByteStatisticUpdateStrategy::OVERRIDE;
Data1.Value = 250;
UserStatItems.Add(Data1);

FAccelByteModelsUpdateUserStatItemWithStatCode Data2;
Data2.StatCode = "popularity";
Data2.UpdateStrategy = EAccelByteStatisticUpdateStrategy::INCREMENT;
Data2.Value = 1000;
UserStatItems.Add(Data2);

FRegistry::Statistic.BulkUpdateUserStatItemsValue(
"AdditionalKey",
UserStatItems,
THandler<TArray<FAccelByteModelsUpdateUserStatItemsResponse>>::CreateWeakLambda(this, [](const TArray<FAccelByteModelsUpdateUserStatItemsResponse>& Result)
    {
        // Bulk Update user stat items value success
    }),
FErrorHandler::CreateWeakLambda(this, [](int32 ErrorCode, const FString& ErrorMessage)
    {
        // Bulk Update user stat items value failed
        UE_LOG(LogTemp, Error, TEXT("Bulk Update User Stat Items Value Failed. Error Code: %d, Error Message: %s"), ErrorCode, *ErrorMessage);
    }));