Skip to main content

Statistics

Last updated on

Overview​

AccelByte Cloud's Statistics service provides game developers with persistent statistic tracking for their games. 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 Cloud Profile service.

AccelByte Cloud's 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.

Permissions​

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage achievements in the Admin Portal. For a full list of permissions that impact achievements management, see the Social tab of the permissions reference.

UsagePermission TagAction
Create a New Statistic ConfigurationADMIN:NAMESPACE:{namespace}:STATCreate
Create a Single Statistic for a PlayerADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEMCreate
Create a Multiple Statistics for a PlayerADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEMCreate
Retrieve All of a Player's StatisticsADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEMRead
Update a Single Statistic for a PlayerADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEMUpdate
Update Multiple Statistics for Multiple PlayersADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEMUpdate
Retrieve Global StatisticsADMIN:NAMESPACE:{namespace}:USER:{userId}:STATITEMRead

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, see our Cloud Authentication and Authorization documentation.

Manage Statistics in the Admin Portal​

Create a New Statistic Configuration​

  1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Configurations menu.

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

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

    • Input the statistic code or StatCode in the Code field, following the formatting rules given.

      NOTE

      StatCode will be used when you create an Incremental Achievement and Leaderboard as these Cloud services use player statistics to determine achievement conditions and generate leaderboards.

    • 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 choose 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.

Retrieve a Player's Statistics​

  1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Statistics Value menu.

  2. Search for a player using the by using Email, Display Name, Username or by using User ID search filters. You can input the specific value that corresponds to the user you're looking for.

  3. Click View on the action panel of the desired player.

  4. On the Statistics Values page, you can see detailed information about the player's statistics.

Edit a Player's Statistics​

  1. On a player's Statistics Value page, choose the statistic you want to edit and click the pencil icon under the Current Value column. Once you have made a change, click the blue tick button to save.

Retrieve Global Statistics​

  1. In the Admin Portal, go to the Game Management section, expand the Statistics section, and select the Statistics Value menu.

  2. Switch to the Global tab. Here you'll see the global statistics.

Implement Statistics Using the Client Server SDKs​

You can manage your statistics using the Client or Game Server. In this tutorial, you will learn how to set up the SDK using the Client Server.

Create a Single Statistic for a Player​

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

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

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

Create Multiple Statistics for a Player​

Use the following code to create multiple new statistics for a player.

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>>::CreateLambda([](const FAccelByteModelsBulkStatItemOperationResult& Result)
{
    // Do something if IncrementUserStatItems has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if IncrementUserStatItems has an error
    UE_LOG(LogTemp, Log, TEXT("Error IncrementUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve a Player's Statistic by StatCodes or Tags​

Use the following code to retrieve a player's statistic by a specific StatCodes or 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>::CreateLambda([](const FAccelByteModelsUserStatItemPagingSlicedResult& Result)
{
    // Do something if GetUserStatItems has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserStatItems has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve All Players' Statistics​

Use the following code to retrieve all of your players' statistics.

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

Reset Multiple Statistics​

Use the following code to reset a player's statistic to the default values as specified in your game namespace.

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 4 update strategies that you can use to handle the strategy.

Update StrategyUsage
OVERRIDEUpdate a player's StatItem value.
INCREMENTAdd to or subtract from a player's StatItem value.
MAXUpdate a player's StatItem with a specified value greater than the current value.
MINUpdate a player's StatItem with a specified value lower than the current existing value.

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.

// Update User Statistics without using additional key
        List<StatItemUpdate> updates = new List<StatItemUpdate>();
        updates.Add(new StatItemUpdate
        {
            statCode = "coin",
            updateStrategy = StatisticUpdateStrategy.OVERRIDE,
            value = 250
        });
        updates.Add(new StatItemUpdate
        {
            statCode = "popularity",
            updateStrategy = StatisticUpdateStrategy.INCREMENT,
            value = 1000
        });

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

        // Update User Statistics using additional key
        string additionalKey = "SomeUserId";

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

Implement Statistics Using the Game Server SDKs​

You can manage your statistics using the Client or Game Server. In this tutorial, you will learn how to set up the SDK using Game Server.

Create a Single Statistic for a Player​

Use the following code to create a new statistic for a player from your game server.

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

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

Create Multiple Statistics for a Player​

Use the following code to multiple statistics for a player simultaneously.

FString UserId = FString("SomeUserId");
TArray<FAccelByteModelsBulkStatItemInc> Data;
FAccelByteModelsBulkStatItemInc Data1;
Data1.statCode = FString("Kill");
Data1.inc = 5;
Data.Add(Data1);
FAccelByteModelsBulkStatItemInc Data2;
Data2.statCode = FString("Death");
Data2.inc = 2;
Data.Add(Data2);

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

Create Multiple Statistics for Multiple Players​

Use the following code to create multiple statistics for multiple players simultaneously.

TArray<FAccelByteModelsBulkUserStatItemInc> Data;
FAccelByteModelsBulkUserStatItemInc Data1;
Data1.statCode = FString("Kill");
Data1.inc = 5;
Data1.userId = FString("SomeUserId1");
Data.Add(Data1);
FAccelByteModelsBulkUserStatItemInc Data2;
Data2.statCode = FString("Kill");
Data2.inc = 3;
Data2.userId = FString("SomeUserId2");
Data.Add(Data2);

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

Retrieve a Player's Statistic by StatCodes or Tags​

Use the following code to retrieve a player's statistics by StatCodes or Tags.

FString UserId = FString("SomeUserId");
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::ServerStatistic.GetUserStatItems(UserId, StatCodes, Tags, THandler<FAccelByteModelsUserStatItemPagingSlicedResult>::CreateLambda([](const FAccelByteModelsUserStatItemPagingSlicedResult& Result)
{
    // Do something if GetUserStatItems has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserStatItems has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetUserStatItems, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve All Players' Statistics​

Use the following code to retrieve all players' statistics.

FString UserId = FString("SomeUserId");

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

Reset Multiple Statistics for a Player​

Use the following code to reset multiple statistics for a player to the default values as specified in your game namespace.

string userId = "SomeUserId";
        List<StatItemReset> resets = new List<StatItemReset>();
        resets.Add(new StatItemReset
        {
            statCode = "Kill"
        });
        resets.Add(new StatItemReset
        {
            statCode = "Death"
        });

        AccelByteServerPlugin.GetStatistic().ResetUserStatItems(userId, 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
            }
        });

Reset Multiple Statistics for Multiple Players​

Use the following code to reset multiple players' statistics to the default values as specified in your game namespace.

List<UserStatItemReset> resets = new List<UserStatItemReset>();
        resets.Add(new UserStatItemReset
        {
            userId  = "SomeUserId1",
            statCode = "Kill"
        });
        resets.Add(new UserStatItemReset
        {
            userId = "SomeUserId2",
            statCode = "Kill"
        });

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

Update Multiple Statistics for a Player​

Use the following code to update multiple statistics for a player using the updating strategy options.

string userId = "SomeUserId";
        List<StatItemUpdate> updates = new List<StatItemUpdate>();
        statItemUpdates.Add(new StatItemUpdate
        {
            statCode = "Kill",
            updateStrategy = StatisticUpdateStrategy.OVERRIDE,
            value = 5
        });
        statItemUpdates.Add(new StatItemUpdate
        {
            statCode = "Death",
            updateStrategy = StatisticUpdateStrategy.INCREMENT,
            value = 2
        });

        AccelByteServerPlugin.GetStatistic().UpdateUserStatItems(userid, statItemUpdates.ToArray(), result =>
        {
            if (result.IsError)
            {
                // Do something if UpdateUserStatItems has an error
                Debug.Log($"Error UpdateUserStatItems, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if UpdateUserStatItem has been successful
            }
        });

        string additionalKey = "SomeAdditionalKey"

        AccelByteServerPlugin.GetStatistic().UpdateUserStatItems(userid, additionalKey, updates.ToArray(), result =>
        {
            if (result.IsError)
            {
                // Do something if UpdateUserStatItems has an error
                Debug.Log($"Error UpdateUserStatItems, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if UpdateUserStatItems has been successful
            }
        });

Update Multiple Statistics for Multiple Players​

Use the following code to update multiple statistics for multiple players using the updating the strategy options.

List<UserStatItemUpdate> updates = new List<UserStatItemUpdate>();
        updates.Add(new UserStatItemUpdate
        {
            userId = "SomeUserId1"
            statCode = "Kill",
            updateStrategy = StatisticUpdateStrategy.OVERRIDE,
            value = 5,
            additionalKey = "SomeAdditionalKey1"
        });
        updates.Add(new UserStatItemUpdate
        {
            userId = "SomeUserId2",
            statCode = "Death",
            updateStrategy = StatisticUpdateStrategy.INCREMENT,
            value = 2,
            additionalKey = "SomeAdditionalKey2"
        });

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

Connecting Custom Services to Statistics using Server-side SDKs​

SDK Initialization​

Before using the Statistics service from the SDK, you will need to initialize your server-side SDK to make you authorized and able to perform create, read, update, and delete actions.

Golang SDK Initialization​

Before using the Statistics from the Golang SDK, you will need to initialize the SDK by following the steps below:

statConfigurationService := &social.StatConfigurationService{
  SocialServiceClient: factory.NewSocialClient(&repository.ConfigRepositoryImpl{}),
  TokenRepository:     &repository.TokenRepositoryImpl{},
}

Once completed, you can use the Golang SDK to create, read, update, or delete Statistics from your serverless app.

Python SDK Initialization​

Before using the Statistics service from the Python SDK, you will need to initialize the SDK by following the steps below:

Once completed, you can use the Python SDK to create, read, update, or delete Statistics from your serverless app.

.NET (C#) SDK Initialization​

Before using the Social service, you will need to set some permissions. Use the following .NET namespaces:

using AccelByte.Sdk.Api.Social.Model;
using AccelByte.Sdk.Api.Social.Operation;
using AccelByte.Sdk.Api.Social.Wrapper;

Java SDK Initialization​

Before using the Social service, you will need to set some permissions. Initialize the StatConfiguration wrapper from the Social service using the following code:

StatConfiguration wStatConfig = new StatConfiguration(sdk);

Once completed, you can use the SDK to create, read, update, or delete a player's statistics from your game client.

Create a Statistic Configuration​

Use the following function to create a statistic configuration:

stat, err := socialService.CreateStat(namespace, body)
if err != nil {
  return err
}

return nil

Delete a Statistic Configuration​

Use the following function to delete a statistic configuration:

err := socialService.DeleteStat(namespace, statCode)
if err != nil {
  return err
}

return nil

Retrieve a Statistic Configuration by Stat Code​

Use the following function to retrieve a statistic configuration:

stat, err := socialService.GetStat(namespace, statCode)
if err != nil {
  return err
}

return nil

Retrieve All Statistic Configurations​

Use the following function to retrieve all statistic configurations::

stats, err := socialService.GetStats(namespace, &limit, &offset)
if err != nil {
  return err
}

return nil

Search for a Statistic Configuration by Keyword​

Use the following function to search for a statistic configuration based on a keyword:

stats, err := socialService.QueryStats(namespace, keyword, &limit, &offset)
if err != nil {
  return err
}

return nil

Update a Statistic Configuration​

Use the following function to update a statistic configuration:

stat, err := socialService.UpdateStat(namespace, statCode, body)
if err != nil {
  return err
}

return nil