Store additional data in user statistic

Last updated on October 24, 2024

Introduction

The Statistics feature allows you to store additional data for player-related statistic information. The additional data can be utilized to include more detail about the statistic data being tracked. For instance, it can be used to track general information about the player such as, weapon name, vehicle name, game mode, and other relevant details in conjunction with the statistic value itself.

In this section, you will learn about how to utilize statistical additional data, update it, and the integration with other services.

Prerequisites

Access to the AccelByte Gaming Services (AGS) Admin Portal
AccelByte Unreal or Unity SDK, including the following permissions:
- Client ID
- Client Secret
Access to the AccelByte Statistics API documentation

Statistic additional data update behaviors

Additional data can be updated in the user statistics in two ways:

Always: choose this option to always replace additional data in all related cycles every time the game client or server updates player statistics. This option is suitable for tracking players' general information, such as the display names.
This example shows that the display name is changed (From Alex to Bob) and that there is an update for a specific cycle (daily). All additional data will be also updated.
State All time Weekly Daily
Before update 3012 - Alex 2600 - Alex 2441 - Alex
After update 3012 - Bob 2600 - Bob 2461 - Bob
On Updated: choose this option to update additional data only if the value change is accepted. When you update player statistics with the MIN/MAX strategy, the additional data will be updated only if the value is larger or smaller than the current user's point. Read more about supported update strategies in Track global statistics for players and games. This option is suitable if you want to track a player's attribute when a point is achieved.
This example shows that the player is changing their weapon from Slingshot to Bow and achieving new records for a specific leaderboard cycle (daily).
State All time Weekly Daily
Before update 100 - Gun 100 - Gun 40 - Slingshot
After update 100 - Gun 100 - Gun 90 - Bow

State	All time	Weekly	Daily
Before update	3012 - Alex	2600 - Alex	2441 - Alex
After update	3012 - Bob	2600 - Bob	2461 - Bob

State	All time	Weekly	Daily
Before update	100 - Gun	100 - Gun	40 - Slingshot
After update	100 - Gun	100 - Gun	90 - Bow

note

By default, every statistic configuration you create will use the Always update additional data options. You can specify this option in the Admin Portal.

Set up additional data update behavior in statistic configuration

You can create and update statistic configuration in the AGS Admin Portal.

Create a new statistic configuration

To specify additional data update strategy when creating a new statistics configuration, follow these steps:

In the AGS Admin Portal, go to your game namespace.
On the sidebar, go to Progression & Inventory > Statistics > Configuration. The Statistic Configuration page appears.
Click the Add Configuration button. The Add New Configuration form appears.
Fill in the required fields on the form. For more information about the fields on this form, see Create user and global statistics configuration.
Scroll down the form and expand the Advanced Configuration section.
Define the Additional Data Update Strategy by selecting Always or On Updated, whichever is appropriate for your configuration.
Click the Add button to save the new statistic configuration.

Update existing statistic configuration

To change the additional data update strategy of an existing statistic configuration, follow these steps:

In the AGS Admin Portal, go to your game namespace.
On the sidebar, go to Progression & Inventory > Statistics > Configuration. The Statistic Configuration page appears.
From the list, find the statistic configuration you want to update. Then, click its corresponding View button. The Configuration Details page appears.
Click on the pencil button at the Additional Data Update Strategy field.
From the dropdown, select Always or On Updated to update the additional data update strategy of the statistic configuration. The configuration will be updated.

Update player statistics with additional data

You can update player statistics from the game client and from the game server.

Update from game client

This update functionality can be called from the game client directly and is suitable for a non-competitive genre such as single player or peer-to-peer multiplayer that doesn't utilize any game server.

Unreal
Unity

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString AdditionalKey = "";
TArray<TSharedPtr<FJsonValue>> JsonArray;
JsonArray.Add(MakeShareable(new FJsonValueString("sword")));

FJsonObjectWrapper AdditionalData;
AdditionalData.JsonObject = MakeShared<FJsonObject>();
AdditionalData.JsonObject->SetStringField("characterName", "hero");
AdditionalData.JsonObject->SetArrayField("weapons", JsonArray);

FAccelByteModelsUpdateUserStatItemWithStatCode UserStatItem1{};
UserStatItem1.StatCode = " Your 2nd stat code ";
UserStatItem1.UpdateStrategy = EAccelByteStatisticUpdateStrategy::INCREMENT;
UserStatItem1.Value = 50.0f;
UserStatItem1.AdditionalData = AdditionalData;

TArray<FAccelByteModelsUpdateUserStatItemWithStatCode> BulkUpdateUserStatItems = { UserStatItem1 };

ApiClient->Statistic.BulkUpdateUserStatItemsValue(AdditionalKey
    , BulkUpdateUserStatItems
    , THandler<TArray<FAccelByteModelsUpdateUserStatItemsResponse>>::CreateLambda([](TArray<FAccelByteModelsUpdateUserStatItemsResponse> Result)
     {
      // Do something if BulkUpdateUserStatItemsValue is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
      // Do something if BulkUpdateUserStatItemsValue has an error
     }));

Statistic statistic = AccelByteSDK.GetClientRegistry().GetApi().GetStatistic();

string additionalKey = "";

StatItemUpdate userStatItem = new StatItemUpdate
{
    statCode = " Your stat code ",
    updateStrategy = StatisticUpdateStrategy.INCREMENT,
    value = 50,
    additionalData = new Dictionary<string, object>
    {
        {"characterName", "hero"},
        {"weapons", new [] {"sword"} }
    }
};

StatItemUpdate[] bulkUpdateUserStatItems = { userStatItem };

statistic.UpdateUserStatItems(additionalKey, bulkUpdateUserStatItems, result =>
{
    if (result.IsError)
    {
        // Do something if UpdateUserStatItems an error
        Debug.Log($"Error UpdateUserStatItems, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if UpdateUserStatItems is successful
});

Update from game server

Server authoritative statistics are suitable for multiplayer competitive gaming, or if you have a dedicated game server running for your game. This can be applied to the following cases:

Maintaining ELO or matchmaking rating (MMR) scores, from your dedicated server, when a match ends
Tracking statistics for an online MMO character

To use the server SDK functionality, use the appropriate code for your game engine.

Unreal
Unity

FServerApiClientPtr ApiServer = FMultiRegistry::GetServerApiClient();

FString AdditionalKey = "";
FString UserId = " Your User Id";

TArray<TSharedPtr<FJsonValue>> JsonArray;
JsonArray.Add(MakeShareable(new FJsonValueString("sword")));

FJsonObjectWrapper AdditionalData;
AdditionalData.JsonObject = MakeShared<FJsonObject>();
AdditionalData.JsonObject->SetStringField("characterName", "hero");
AdditionalData.JsonObject->SetArrayField("weapons", JsonArray);

FAccelByteModelsUpdateUserStatItemWithStatCode UserStatItem1{};
UserStatItem1.StatCode = " Your 2nd stat code ";
UserStatItem1.UpdateStrategy = EAccelByteStatisticUpdateStrategy::INCREMENT;
UserStatItem1.Value = 50.0f;
UserStatItem1.AdditionalData = AdditionalData;

TArray<FAccelByteModelsUpdateUserStatItemWithStatCode> BulkUpdateUserStatItems = { UserStatItem1 };

ApiServer->ServerStatistic.BulkUpdateUserStatItemValue(UserId
    , AdditionalKey
    , BulkUpdateUserStatItems
    , THandler<TArray<FAccelByteModelsUpdateUserStatItemsResponse>>::CreateLambda([](TArray<FAccelByteModelsUpdateUserStatItemsResponse> Result)
     {
         // Do something if BulkUpdateUserStatItemValue is successful
     })
    , FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if BulkUpdateUserStatItemValue has an error
     }));

ServerStatistic serverStatistic = AccelByteSDK.GetServerRegistry().GetApi().GetStatistic();

string additionalKey = "";
string userId = "Player User Id";

StatItemUpdate userStatItem = new StatItemUpdate
{
    statCode = " Your stat code ",
    updateStrategy = StatisticUpdateStrategy.OVERRIDE,
    value = 100,
    additionalData = new Dictionary<string, object>
    {
        {"characterName", "hero"},
        {"weapons", new [] {"sword"} }
    }
};
StatItemUpdate[] bulkUpdateUserStatItems = { userStatItem };

serverStatistic.UpdateUserStatItems(userId, additionalKey, bulkUpdateUserStatItems, result =>
{
    if (result.IsError)
    {
        // Do something if UpdateUserStatItems an error
        Debug.Log($"Error UpdateUserStatItems, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if UpdateUserStatItems is successful
});

Introduction​

Prerequisites​

Statistic additional data update behaviors​

Set up additional data update behavior in statistic configuration​

Create a new statistic configuration​

Update existing statistic configuration​

Update player statistics with additional data​

Update from game client​

Update from game server​

On this page