Use statistic cycles for tracking player progress in specified time frames

Last updated on April 1, 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.

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 > Statistics > Cycles.

   

2. In the Statistic Cycles, click Add Cycle. The Add New Cycle form will be displayed.

   

   

3. In the Add New Cycle form, fill in the following:

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

      

  note

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

4. Click Add to complete and save the configuration.

Adding stat code to cycle

1. In the AGS Admin Portal, go to Game Management > Statistic > Cycles.

   

2. In the Cycle Lists, select the Cycle Configuration you want to add the Statcode to, and click View. The Cycle Configuration details page will be displayed.

   

3. In the Cycle Configuration details page, add a Statcode by clicking the Add Stat Code button. The Add Statcode modal will be displayed.

   

4. In the Add Statcode modal, fill in the Statcode you want to add.

   

5. Click Add. The Statcode will be added to the Statcode List.

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.

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