Use statistic cycles for tracking player progress in specified time frames

Last updated on October 24, 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.

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. Weekly cycle configuration
     • 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.

   

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

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