Leaderboards

Last updated on 20 April, 2023 1:23 AM

Overview

AccelByte Gaming Services (AGS) Starter Leaderboard service enables you to keep track of players’ scores and ranking in your game by collecting data from the AccelByte Gaming Services (AGS) Starter Statistics service, such as the number of matches played, a player’s matchmaking rating, and their experience points. The Leaderboard service will use this data to calculate each player’s rank. This service supports multiple leaderboards in one game, including a daily leaderboard for day to day player activities, weekly leaderboard for a weekly player recap, a monthly leaderboard to record player activities every month, a seasonal leaderboard for seasonal player activities such as holiday events, and also an all-time leaderboard to record and player activities for all time. Each cycle of the leaderboard is explained in greater detail below.

Leaderboard Cycles

• The Daily Leaderboard collects players' daily scores and rankings. Players can start playing the game and the leaderboard service will collect their score and ranking until the daily reset time. Players have to keep playing to maintain their position on the daily leaderboard.
• The Weekly Leaderboard is similar to the Daily Leaderboard, but player scores and rankings will be updated every week. Players have to keep playing to maintain their position on the weekly leaderboard.
  The Monthly Leaderboard is also similar to the Daily and Weekly Leaderboards. The player's score and ranking will be updated every month.
• The All-Time Leaderboard doesn't have any time constraint; it will record the player’s score and ranking as long as the leaderboard exists in-game. As player scores continue to accumulate this leaderboard will be updated.
• The Seasonal Leaderboard runs for a specific period of time that is set when the leaderboard is created. For example, if an event is running on the 1st of May between 00:30 AM and 2:30 AM, the seasonal leaderboard will only record the rank and score of players who took part in that particular event. Once the event is over, the leaderboard will be reset.

Prerequisites

Before you create a leaderboard config, make sure you have created a statistic configuration in the same game namespace. Statistics configs are used to update a player's leaderboard rank.

Manage Leaderboards in the Admin Portal

Create a New Leaderboard

1. In the Leaderboard menu of the Admin Portal, click the Create Leaderboard button.

   

2. Fill in the required fields.

   

   • Input the Leaderboard Code with the appropriate format.

   • Input the StatCode with the related statistic code that you’ve created. This will be the statistic that the leaderboard draws from.

   • Input the Start Date with RFC3339 standard format, e.g., 2020-10-02T15:00:00.05Z.

   • Input the Daily reset time for a daily leaderboard.

   • Input a day and time for the Weekly reset time for a weekly leaderboard.

   • Input the day and time for the Monthly reset time for a monthly leaderboard. For example, if you input 1st in the date field and 12:00 AM in the time field, the reset time will be the first day of the month at 12:00 AM.

   • If you select the Seasonal option, you must input the number of days it will take for the leaderboard to reset in the Season Period Days field.

   • Choose the Order of the Leaderboard.

   • Select an Icon for your leaderboard.

     When you’re done, click the Add button to create your new leaderboard and the new leaderboard will appear in the Leaderboard List.

NOTE

After creating the leaderboard, make sure that the configuration is correct as you will not be able to edit the leaderboard once it starts.

Get Leaderboard Rankings

1. In the Leaderboard List of the Admin Portal, choose the leaderboard you want to see ranking data for by clicking on the Action column and selecting View.

   

2. In this example, we choose to see the all-time leaderboard rankings. You can view the rankings for all cycles of leaderboards.

   

Delete or Archive a Leaderboard

1. In the Leaderboard List tab, choose the leaderboard that you want to delete. Then click Delete in the Action menu next to that leaderboard.

   

2. The Delete Leaderboard form appears. Select the Take a Snapshot Before Deletion box if you want to archive the first 1000 records of the leaderboard and type DELETE in the available fields.

![leaderboard](/img/service-guides/engagement/leaderboards/delete-or-archive-a-leaderboard/2.png "Leaderboard")

3. Click the Delete button to delete the leaderboard.

View Archived Leaderboard Data

1. Go to the Leaderboard page and open the Snapshots tab.

   

2. In the Snapshot tab, you can see all of the archived leaderboards. To open a leaderboard, click View in the leaderboard’s Action menu.

3. Here you can check and see the list of the leaderboard that you already deleted before.

   

Implement Leaderboards using the Client SDKs

Get Rankings

Retrieve all player rankings using a specific leaderboard code. The data is presented in descending order.

Unreal Engine

FString LeaderboardCode = FString("SomeLeaderboardCode");
EAccelByteLeaderboardTimeFrame TimeFrame = EAccelByteLeaderboardTimeFrame::ALL_TIME;
int32 Offset = 0;
int32 Limit = 99;

FRegistry::Leaderboard.GetRankings(LeaderboardCode, TimeFrame, Offset, Limit, THandler<FAccelByteModelsLeaderboardRankingResult>::CreateLambda([](const FAccelByteModelsLeaderboardRankingResult& Result)
{
    // Do something if GetRankings has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetRankings has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetRankings, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string leaderboardCode = "SomeLeaderboardCode";
       LeaderboardTimeFrame timeFrame= LeaderboardTimeFrame.ALL_TIME;
       int offset = 0;
       int limit = 99;

       AccelBytePlugin.GetLeaderboard().GetRankings(leaderboardCode, timeFrame, offset, limit, result =>
       {
           if (result.IsError)
           {
               // Do something if GetRankings has an error
               Debug.Log($"Error GetRankings, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
           }
           else
           {
               // Do something if GetRankings has been successful
           }
       });

Retrieve a Player Ranking

Use the following code to retrieve a specific player’s ranking using their User ID and the desired leaderboard code.

Unreal Engine

FString UserId = FString("SomeUserId");
FString LeaderboardCode = FString("SomeLeaderboardCode");

FRegistry::Leaderboard.GetUserRanking(UserId, LeaderboardCode, THandler<FAccelByteModelsUserRankingData>::CreateLambda([](const FAccelByteModelsUserRankingData& Result)
{
    // Do something if GetUserRanking has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if GetUserRanking has an error
    UE_LOG(LogTemp, Log, TEXT("Error GetUserRanking, Error Code: %d Error Meessage: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string userId = "SomeUserId";
        string leaderboardCode = "SomeLeaderboardCode";

        AccelBytePlugin.GetLeaderboard().GetUserRanking(userId, leaderboardCode, result =>
        {
            if (result.IsError)
            {
                // Do something if GetUserRanking has an error
                Debug.Log($"Error GetUserRanking, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if GetUserRanking has been successful
            }
        });