Using statistic cycles for tracking player progress in specified time frames

Last updated on April 23, 2024

Overview

The statistics service offered in AccelByte Gaming Services (AGS) allows you to track various player attributes and track them within a specific time frame with a statistic cycle. After the cycle ends, the progress will be reset so players can start to compete again. For example, you could track the weekly kill counts, or track how many specific items the player collects this season.

Furthermore, you could also integrate the statistic cycle with other services such as the new Leaderboard, allowing you to rank players based on the selected statistic and the cycle it belongs to.

Goals

• Provide an understanding of statistic cycles and how to configure them.
• Explain how to use statistic cycles using AccelByte SDK, including how to utilize multiple supported update functionalities.

Prerequisites

• Access to the AGS Admin Portal.
• Access to the AccelByte Unreal or Unity SDK
• Access to AGS statistics API documentation.
• Statistics code configuration that will be used on the StatCode list under cycle configuration.

Creating statistics cycles

It is very important for a game to persistently track user attributes within a specific time frame to increase competition among players. You can set up a statistic cycle configuration from the AGS Admin Portal to track users' attributes for a specific time frame by following the guide below.

1. In the Admin Portal, Go to Game Management section, expand Statistic and click Cycles.

   

2. In the Statistic Cycles, click on the Add Cycle button.

   

3. The Add New Cycle form will be displayed.

   

From the form above you will be required to:

• Fill in the Name of the cycle.

• Fill in the Description of the cycle.

• Define the Start Date and End Date of the cycle. The End Date is optional, and will run indefinitely if the value is empty.

• Select the Cycle Type for the Cycle Configuration. Every Cycle Type will have a different configuration for reset time:

  • For Daily:

    • Define the hour (UTC) Reset Time for the daily cycle.

    

  • For Weekly:

    • Define the Reset Day for the weekly cycle.

    • Define the hour (UTC) of the Reset Time for the weekly cycle.

      

  • For Monthly:

    • Define the Reset Date for the monthly cycle

    • Define the hour (UTC) of the Reset Time for the monthly cycle.

      

  • For Annually:

    • Define the Reset Date for the annual cycle.

    • Define the hour (UTC) of the Reset Time for the annual cycle.

      

  • For Seasonal:

    • Define the Season Duration by number of days for the seasonal cycle.

    • Define the hour (UTC) of the Reset Time for the seasonal cycle.

      

After the statistic cycle is successfully created, it will have one of several status states based on the cycle configuration:

• Init is the status after cycle is created.
• Active is the status when the cycle date is started.
• Stopped is the status when the cycle is finished and manually triggered to be stopped by accessing Stop Cycle endpoint.

Use the statistics from the game

Once the statistic cycle is configured in the AGS Admin Portal, you can use it from the game directly using the example explained in this section. You can manage your player statistics using the game client or game server.

The mechanism behind the calculation process

By default, the statistic cycle will not contain any statistic cycle item on the start of the cycle. The statistic cycle will also remove all player statistic cycle items on each reset. So, to add the player statistic cycle item to the current cycle, you need to update the player statistics through our API, which could be through your game codes. Then, the statistic cycle will update its statistic cycle item value based on the statistics update method:

• OVERRIDE: The update will replace the existing value of your player statistic cycle item data with the latest one from statistic.
• INCREMENT: The update will add to or subtract from the existing statistic cycle item value with the new value, depending on if the new value is (+) or (-).
• MAX: This will only update the statistics cycle item if the new value is higher than the existing one.
• MIN: This will only update the statistics cycle item if the new value is lower than the existing one.

For the incremental statistic cycle, we will use the default statistics value as the initial value (after reset) instead of 0.

Furthermore, in the next part of the document, you will learn how to use the client SDKs to manage the statistic cycles for players. We will divide each endpoint into two use cases to help game developers use the endpoints in both Unreal Engine and Unity.

Get a list of statistic cycles

You can get a list of available statistic cycles in your namespace. The list will provide you with detailed information on all statistic cycles.

Get Cycle List Unreal Engine

Unreal Engine

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

EAccelByteCycle TheCycle = EAccelByteCycle::DAILY;
int32 Offset = 0; //Optional
int32 Limit = 20; //Optional

ApiClient->Statistic.GetListStatCycleConfigs(TheCycle,
    THandler<FAccelByteModelsStatCycleConfigPagingResult>::CreateLambda([&](const FAccelByteModelsStatCycleConfigPagingResult& Response)
     {
         // Do something if GetListStatCycleConfigs has been successful
     })
    , FErrorHandler::CreateLambda([&](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetListStatCycleConfigs has an error
     })
    , Offset
    , Limit);

Get Cycle List Unity

Unity

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

StatisticCycleType type = StatisticCycleType.None;
StatisticCycleStatus status = StatisticCycleStatus.None;
int offset = 0; //Optional
int limit = 20; //Optional

statistic.GetListStatCycleConfigs(result =>
{
    if (result.IsError)
    {
        // Do something if GetListStatCycleConfigs has an error
        Debug.Log($"Error GetListStatCycleConfigs, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if GetListStatCycleConfigs is successful
}, type, status, offset, limit);

Get a statistic cycle by cycle ID

You can also get one specific statistic cycle in your namespace. This will help players to focus on one statistic cycle.

Cycle ID Unreal Engine

Unreal Engine

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString StatisticCycleId = "Your Cycle Id";

ApiClient->Statistic.GetStatCycleConfig(StatisticCycleId,
    THandler<FAccelByteModelsStatCycleConfig>::CreateLambda([&](const FAccelByteModelsStatCycleConfig& Response)
     {
         // Do something if GetStatCycleConfig has been successful
     })
    , FErrorHandler::CreateLambda([&](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetStatCycleConfig has an error
     }));

Cycle ID Unity

Unity

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

string cycleId = "Your Cycle Id";

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

Get user statistic items related to the statistic cycle

You can also get a list of user statistics using a statistic cycle ID. This will help players focus on a list of statistic items that are tied to a cycle. To get all the statistics that belong to the user, you can make StatCodes to be empty, or remove StatCodes.

User Statistic Items Unreal Engine

Unreal Engine

FApiClientPtr ApiClient = FMultiRegistry::GetApiClient();

FString StatisticCycleId = "Your Cycle Id";
int32 Offset = 0; //Optional
int32 Limit = 20; //Optional
TArray<FString> StatCodes = {"Your StatCode 1", "Your StatCode 2" }; //Optional

ApiClient->Statistic.GetUserStatCycleItems(StatisticCycleId,
    THandler<FAccelByteModelsUserStatCycleItemPagingSlicedResult>::CreateLambda([&](const FAccelByteModelsUserStatCycleItemPagingSlicedResult& Response)
     {
         // Do something if GetUserStatCycleItems has been successful
     })
    , FErrorHandler::CreateLambda([&](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetUserStatCycleItems has an error
     })
    , Offset
    , Limit);

User Statistic Items Unity

Unity

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

string cycleId = "Your Cycle Id";
int offset = 0; //Optional
int limit = 20; //Optional
string[] statCodes = { "Your StatCode 1", "Your StatCode 2" }; //Optional

statistic.GetListUserStatCycleItem(cycleId, result =>
{
    if (result.IsError)
    {
        // Do something if GetListUserStatCycleItem has an error
        Debug.Log($"Error GetListUserStatCycleItem, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }
    
    // Do something if GetListUserStatCycleItem is successful
}, offset, limit, statCodes);