Using statistic cycles for tracking player progress in specified time frames
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.
In the Admin Portal, Go to Game Management section, expand Statistic and click Cycles.
In the Statistic Cycles, click on the Add Cycle button.
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
- Get Cycle List Unity
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);
Statistic statistic = MultiRegistry.GetApiClient().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}");
}
else
{
// Do something if GetListStatCycleConfigs has been 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
- Cycle ID Unity
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
}));
Statistic statistic = MultiRegistry.GetApiClient().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}");
}
else
{
// Do something if GetStatCycleConfig has been 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
- User Statistic Items Unity
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);
Statistic statistic = MultiRegistry.GetApiClient().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}");
}
else
{
// Do something if GetListUserStatCycleItem has been successful
}
}
, Offset
, Limit
, StatCodes);