Use statistic cycles for tracking player progress in specified time frames

Last updated on February 11, 2025

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.

Prerequisites

You must have:

• access to the AGS Admin Portal.
• access to AGS statistics API documentation.
• statistics code configurations that will be added to the Statistic Cycle.

Create 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. On the Admin Portal sidebar, go to Progression & Inventory > Statistics > Cycles.

   

2. On the Statistics Cycles page, click on the + Add Cycle button. The Add New Cycle form appears.

   

3. Fill in the required information:

   

   • The Name of the cycle.

   • The Description of the cycle.

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

   • The Cycle Type for the Cycle Configuration. Every Cycle Type has a different configuration for reset time as follows:

     • For Daily, define the hour (UTC) Reset Time.

       

     • For Weekly, define the Reset Day and the hour (UTC) of the Reset Time.

       

     • For Monthly, define the Reset Date and the hour (UTC) of the Reset Time.

       

     • For Annually, define the Reset Date and the hour (UTC) of the Reset Time.

       

     • For Seasonal, define the Season Duration by number of days and the hour (UTC) of the Reset Time.

       

   note

   For the incremental statistics cycle, the default value as the initial value (after reset) is used instead of 0.

4. Click Add to save the new cycle.

Add stat code to cycle

note

You can use the cycles in the new Leaderboard to create a time-based leaderboard if you select the Statcode that is added to a specific cycle.

To add stat codes to a statistics cycle, follow these steps:

1. On the Admin Portal sidebar, go to Progression & Inventory > Statistics > Cycles.

   

2. From the cycles list, find the cycle you want to update and click on its ID to open its details page.

   

3. On the cycle's details page, scroll down to the Statcode List section. Then, click on the + Stat Code button. The Add Statcode form appears.

   

4. On the form, search and select the stat code you want to add. To add another stat code, click on + Add More Statcode. You can add as many as necessary for the cycle and optionally set the Min/Max value for each of the stat code in this cycle.

   

   1. Statistic cycle min/max value range should be between statistic config min/max value.
   2. Statistic config default value should be between stat cycle min/max value and statistic config min/max value.
   3. For more details about the statistics cycle Min/Max behavior can be found below.

5. Click Add. The new stat codes are added to the Statcode List.

Cycle minimum and maximum capping behavior

Setting a minimum and maximum value for a cycle affects how updates work for both user statistics and user statistic cycles. This behavior can be configured in the existing statistic settings.

To enable or disable this configuration, follow these steps:

1. In the Admin Portal, go to Game Management > Statistic > Configuration.
2. Select an existing Statistic Configuration to edit. Ensure the configuration is in the INIT status and assigned to a cycle with Min/Max limits.
3. On the Statistic Configuration page, toggle the Cap Cycle Override option to enable or disable the behavior.

Enabled Cap Cycle Override

When Cap Cycle Override is active, the following behavior applies:

• When Statistic cycle maximum is less than Statistic configuration maximum:

  • Incremental Updates:
    • User Statistic:
      • Can be incremented until it reaches the lowest cycle maximum value tied to the statistic configuration.
      • Once the cycle resets, the User Statistic can continue to update.
      • Updates cannot exceed the statistic configuration maximum value.
    • User Statistic Cycle:
      • Can be incremented until it reaches the cycle maximum value.
      • Updates will stop if any other cycle tied to the same statistic configuration reaches its cycle maximum value first.
  • Min, Max, and Override Updates
    • Both User Statistic and User Statistic Cycle update until they hit their maximum limits.

• When Statistic cycle minimum is greater than Statistic configuration minimum

  • Incremental Updates:
    • User Statistic:
      • Can be decremented until it reaches the greatest cycle minimum value tied to the Statistic configuration
      • Once the cycle resets, the User Statistic can continue to update.
      • Updates cannot go below the statistic configuration minimum value.
    • User Statistic Cycle:
      • Can be decremented until it reaches the cycle minimum value.
      • Updates will stop if any other cycle tied to the same statistic configuration reaches its cycle minimum value first.
  • Min, Max, and Override Updates:
    • Both User Statistic and User Statistic Cycle update until they hit their minimum limits.

• When Statistic cycle maximum and minimum is the same as or equal to Statistic configuration maximum and minimum

  • Applies to all update strategies:
    • User Statistic: Follows the configuration's maximum and minimum.
    • User Statistic Cycle: Follows the cycle's maximum and minimum.

Each update strategy behaves differently when applying Min/Max limits.

Update strategies explained with example

Scenario: Updating a user statistic tied to multiple cycles with Min/Max values configured.

• Statistic Configuration
  • Min: 0
  • Default: 30
  • Max: 500
• Daily Statistic Cycle
  • Min: 15
  • Max: 150
• Weekly Statistic Cycle
  • Min: 5
  • Max: 250

Using this configuration, here's how the update strategies will behave:

Incremental updates

Incremental updates cap the statistic or cycle value at its defined Min/Max limits. If an increment exceeds these limits, it will be capped at the nearest boundary (minimum or maximum). Any remaining value from this capping will be redistributed to other related statistics or cycles. As a result, the updated values will reflect the adjusted increments instead of the original request.

Min, Max and Override

When an update request using Min, Max, or Override update strategy causes a user statistic to exceed the cycle or statistics configuration's Min/Max limits, the value will be capped without redistributing the remaining value. Each user statistic or user statistic cycle will be calculated independently until it reaches their limits.

• Max update strategy
• Min update strategy
  
• Override update strategy
  

Disabled Cap Cycle Override

When Cap Cycle Override is disabled, each statistic and cycle is calculated independently based on its configured Min/Max limits. There is no dependency between cycles or the statistic configuration limits.

Cycle status

After the statistic cycle configuration is successfully created, it will have one of several status states based on the cycle configuration. Understanding the status is essential so that you can utilize the feature better.

Status	Meaning
INIT	The Cycle is not started and/or there is no active Statistic Configuration registered in this configuration
ACTIVE	The Cycle is running and/or there is an active Statistic Configuration registered in this configuration
STOPPED	The Cycle is finished or manually triggered to be stopped by accessing Stop Cycle endpoint

Use the statistic cycle from the game

Get a list of statistic cycles

You can get a detailed list of all available statistic cycles in your namespace.

Unreal

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 is successful
     })
    , FErrorHandler::CreateLambda([&](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetListStatCycleConfigs has an error
     })
    , Offset
    , Limit);

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 a specific statistic cycle in your namespace. This will help players to focus on a specific statistic cycle.

Unreal

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 is successful
     })
    , FErrorHandler::CreateLambda([&](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetStatCycleConfig has an error
     }));

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 get a list of user statistics using a statistic cycle ID. This will help players to 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 empty, or remove StatCodes.

Unreal

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 is successful
     })
    , FErrorHandler::CreateLambda([&](int32 ErrorCode, FString ErrorMessage)
     {
         // Do something if GetUserStatCycleItems has an error
     })
    , Offset
    , Limit);

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);