Skip to main content
Version: v3

Leaderboard Introduction

tip

Setting up leaderboards in your game can promote fun competitions among players and encourage players to interact more with your game.

TapSDK Leaderboard provides the following functions:

  • Automatically calculate rankings: When the players’ scores are updated, the latest rankings of the players will be automatically re-calculated.
  • Get the top players: Get a given number of top players from the current leaderboard.
  • Get the ranking of the current player: Get the ranking of the current player no matter if they are on the top of the leaderboard.
  • Get the players with similar rankings as the current player: This can be used to find opponents or friends whose levels are close to the current player.
  • Reset data: You can determine whether the leaderboard should be reset periodically automatically or manually only. For example, the leaderboard can be automatically reset after a season is over, in which each season lasts for a day, a week, or a month. You may also manually reset the leaderboard while you are testing your game or when there is an error with the data.
  • Easily update the data: You can choose among three modes for updating a player’s score on the leaderboard: better, last, and sum. better will keep the best score of the player, last will keep the latest score, and sum will add up all the scores generated by the player.

Creating a Leaderboard​

note

We recommend that you create the leaderboards in advance on TapTap Developer Center. The client can then update a leaderboard by providing its name (statisticName).

Each leaderboard consists of a name (statisticName) and the scores of its members (statisticValue). You can specify its order, update strategy, and reset interval as well.

Name​

statisticName is the name of the leaderboard, which should be unique within your game. The name cannot be modified after a leaderboard has been created. It can only contain letters, numbers, and underscores, and has to start with a letter.

Member Type​

memberType is the type of the members on the leaderboard. You can choose one of the following types:

  • User: The value will be _User. Each member will correspond to the objectId of a user in the built-in account system (the _User class). If you plan to update the scores on the leaderboard from the client (for the current players only), this would be your only choice.
  • Object: The value will be the name of a class other than _User in the Data Storage service. Each member will correspond to the objectId of an object in the class. For example, if you have a class named Weapon, you can enter Weapon for memberType to form a leaderboard for weapons.
  • Entity: The value will be _Entity. Each member will be a string provided by you. The string can only contain letters, numbers, and underscores.

Note:

  • When retrieving data from the leaderboard, you can specify certain parameters to get more data associated with the users or objects.
  • If you selected “Object” or “Entity” as the type, you will only be able to update the leaderboard with your Master Key on the server side.
  • If “Only Master Key is allowed to update the score” is checked on the dashboard (unchecked by default), you will only be able to update the leaderboard with your Master Key on the server side even if you selected “User” as the type. From the perspective of anti-cheating, we recommend that you enable this option.

Uploading Scores​

statisticValue contains the scores (in numbers) generated by the players on the client. It could be points, kills, times, etc.

Order​

  • descending: Rand scores in descending order. In most of the games, the higher score a player achieves, the higher ranking this player gets.
  • ascending: Rand scores in ascending order. For example, in some racing games, the less time a player spends to complete a task, the higher ranking this player gets.

Update Strategy​

updateStrategy is the strategy for updating players’ scores. Each leaderboard can have one of the following strategies:

  • better: Keep the best score of each player. When the descending order is selected, the largest score will be kept; when the ascending order is selected, the smallest score will be kept.
  • last: Keep the latest score of each player. This means that a player’s latest score will overwrite their past scores.
  • sum: The final score of each player is the sum of all the scores they got. Each time a player gets a new score, the score will be added to the existing score.

Resetting Data​

The leaderboard can be reset at any time. Once reset, the leaderboard will become empty. A use case for resetting is to clear the leaderboard once a season is over. Resetting a leaderboard will remove all the scores from it and the version (Version) of the leaderboard will be updated by adding 1. All the new requests from the clients for updating scores will be written to the newer version of the leaderboard.

versionChangeInterval is the interval for resetting data. It can be one of the following:

  • day: Reset at 00:00 every day.
  • week: Reset at 00:00 every Monday.
  • month: Reset at 00:00 on the 1st of every month.
  • never: Do not reset automatically, which means that only manual resets will happen.

Retrieving History Data​

Once the leaderboard is reset, clients can only retrieve the latest and the previous version of the leaderboard with the SDK. If you did not check “Keep the previous version” on the dashboard (unchecked by default) before you reset the leaderboard, the client SDK will only be able to retrieve the current version of the leaderboard. If the interval for resetting data is set to never, there will be an additional restriction: you can only retrieve the previous version within 7 days after you reset the leaderboard. After 7 days, you cannot retrieve the previous version anymore. To illustrate:

  • With month selected as the interval, assuming it’s currently March, the version becomes 3 after the leaderboard has been reset on March 1st. You will be able to retrieve version 2 for February but not version 1 for January.
  • With never selected as the interval, assuming the version becomes 3 after you manually reset the leaderboard. You will be able to retrieve version 2 within 7 days. After that, you won’t be able to retrieve version 2 anymore.

Although the previous versions cannot be retrieved by the client SDK, you can still retrieve the archived CSV files containing them with the REST API. Each leaderboard can have at most 60 archived versions. After exceeding the limit, the older versions will be deleted. If you need to keep the previous versions of the leaderboard for a longer time, please download them promptly so you can back them up to your own places.