Last Updated: 9/22/2021, 7:52:24 AM

# Leaderboards

# Overview

The AccelByte Leaderboard Service enables you to keep track of players’ scores and ranking in the game by collecting data from the Statistics service such as the number of matches played, the 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, a 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 type of leaderboard is explained in greater detail below.

# Leaderboard Cycles

  • The Daily Leaderboard collects players' daily scores and ranking once the leaderboard has been created. When the leaderboard has been generated, 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 Season 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 season 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.

# How It Works

# Single Leaderboard

# Leaderboard Started

The leaderboard will start from the defined start time. At that time the leaderboard will retrieve the player’s current statistic scores, which will become the initial scores for the all-time leaderboard. If the leaderboard data also includes a daily, weekly, monthly, or seasonal suffix, it will also map to the statistic code.

leaderboard

# Update a Player’s Statistic Score

The leaderboard consumes statistic events to collect a player’s latest score. Then, players' delta score will be added to the existing score in related leaderboards such as daily, weekly, monthly, or seasonal, and the all-time leaderboard score will be replaced with the latest score.

leaderboard

# Reset a Leaderboard

A leaderboard will be reset based on its reset time that was calculated when the leaderboard started or when it is restarted.

leaderboard

# Character Leaderboard

# Update Character Leaderboard

When a player levels up or enters a new arena, the game client sends their score data to the Statistics service. There, the character event will be published with additional data, such as the character’s name and skills. On the other end, the Leaderboard service will fetch the character score data from Kafka and save the new score and rank data in its internal database.

leaderboard

# Get Character Leaderboard

A game client call retrieves the leaderboard data from the Leaderboard service. It will return all related leaderboard data, including additional information such as character names and skills.

leaderboard

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage the leaderboard in the Admin Portal. For a full list of permissions that impact leaderboards management, see the Leaderboards tab of the permissions reference.

Usage Resource Action
List All Leaderboards By Given Namespace ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Create New Leaderboard ADMIN:NAMESPACE:{namespace}:LEADERBOARD Create
Get Leaderboard By Leaderboardcode ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Get All Time Leaderboard Ranking Data ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Get Current Month Leaderboard Ranking Data ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Get Current Season Leaderboard Ranking Data ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Get Today Leaderboard Ranking Data ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Get User Ranking ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read
Delete User Ranking ADMIN:NAMESPACE:{namespace}:LEADERBOARD:USER Update
Get Current Week Leaderboard Ranking Data ADMIN:NAMESPACE:{namespace}:LEADERBOARD Read

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing Leaderboards in the Admin Portal

# Create a New Leaderboard Configuration

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.

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

    leaderboard

  2. Fill in the required fields.

    • Input the Leaderboard Code with the appropriate format.
    • Input the Stat Code 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:00AM.
    • 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 config.

    When you’re done, click the Add button to create your new leaderboard.

    leaderboard

    The new leaderboard will appear in the Leaderboard List.

    leaderboard

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

    leaderboard

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

    leaderboard

# Delete or Archive a Leaderboard

  1. In the AccelByte Admin Portal, go to the Game Management section and open the Leaderboard page.

    leaderboard

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

    leaderboard

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

  4. Click the Delete button to delete the leaderboard.

# View Archived Leaderboard Data

  1. In the AccelByte Admin Portal, go to the Game Management section and open the Leaderboard page.

    leaderboard

  2. On the Leaderboard page, open the Snapshots tab.

    leaderboard

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

    leaderboard

  4. The archived data appears

    leaderboard

# Implementing Leaderboards using the SDK

# Get Rankings

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

# Get User Ranking

Get a specific player’s ranking using their User ID and the desired leaderboard code.

# Managing Leaderboards using the API

# Create a New Leaderboard Configuration

  1. Use the Create New Leaderboard POST - ​/leaderboard​/v1​/admin​/namespaces​/{namespace}​/leaderboards (opens new window) endpoint.
  2. Input the Namespace field with the game namespace.
  3. Fill out the Request Body:
  • Input the Reset Time for a Daily leaderboard. For other types of leaderboards, this field can be left blank.
  • Define the order of the leaderboard in the Descending fields. Input this field with true if you want the leaderboard to appear in descending order.
  • Input the iconURL field with your leaderboard icon URL.
  • Input the Leaderboard Code. The code must be in lowercase and can contain a maximum of 32 characters.
  • Input the Reset Date and Reset Time for a Monthly leaderboard. Input the Reset Date field with a number from 1 to 31. The default value is 1. For other types of leaderboards, these fields can be left blank.
  • Input the Name of the leaderboard.
  • If you want to create a Seasonal leaderboard, you need to input the Season Period with the number of days that will pass before the leaderboard is reset. This value must be greater than 31 days.
  • Input the Start Time of the leaderboard with RFC3339 standard format, e.g. 2020-10-02T15:00:00.05Z.
  • Input the Stat Code with the related statistic code that you’ve created. This will be the statistic the leaderboard draws from.
  • Input the Reset Day and Reset Time for a Weekly leaderboard. For other types of leaderboards, this field can be left blank.

Upon successful request, a new leaderboard config will be created.

NOTE

  • The reset time must be in hours:minutes in 24-hour format, e.g. 01:30, 10:30, 15:30, 23:15. The default value is 00:00.
  • The reset day must be in numerical order starting from 0 for Sunday to 6 for Saturday. The default value is 0.

# Get Leaderboard Rankings

You can get the leaderboard ranking data for all-time monthly seasonal and daily leaderboards by using their respective endpoint. But, if needed you can get all leaderboards by a particular namespace using the respective endpoint. Follow the steps below to make a request:

  1. Input the Namespace field with the game namespace.
  2. Input the Leaderboard Code. The code must be in lowercase and can contain a maximum of 32 characters.
  3. If you want to paginate the displayed daya data, input the limit with the number of lines of data to be returned, and offset with the start position of the queried data.

Upon successful request, you will retrieve the ranking data for the desired leaderboard. Here is the response example of the successful request:

# Delete a User Ranking

To keep your leaderboards clean and fair, you can remove players who cheat. Follow the steps below to remove players from the leaderboard.

  1. Use the Delete User Ranking: DELETE - ​/leaderboard​/v1​/admin​/namespaces​/{namespace}​/leaderboards​/{leaderboardCode}​/users​/{userId} endpoint.
  2. Input the Game Namespace.
  3. Input the Leaderboard Code.
  4. Input the User ID of the player you want to remove from the leaderboard. To remove multiple players, separate each player’s user ID with a comma.

Upon successful request, you will remove the player from the leaderboard. The success response code is 204 with no content

  • Leaderboards rely on player statistics to work, so check out our guide on our Statistics service.
  • In addition to Leaderboards, Achievements can also be a great way to increase player engagement.