Leaderboards
On the game page, you can show personalized leaderboards with the results of the best players and the authorized user's place in the ranking.
To make the requests described below work for you, check that the following conditions are met:
- You've enabled and configured the SDK, and its object is available via the
ysdkvariable. - You've created a leaderboard in the Games Console.
Alert
If there is no leaderboard with the corresponding name in the Technical leaderboard name field in the Console, requests will return a 404 error.
Leaderboard description
To get a description of a leaderboard by its name, use the ysdk.leaderboards.get_description() method:
1ysdk.leaderboards.get_description(
2 leaderboard_name: string,
3 callback: function
4)
callback: function — the handler for the invoked method. It looks like:
function(self, description: table|nil): nil
description: table— description of the leaderboard. Contains properties:
1description: {
2 app_id: string,
3 default: boolean,
4 invert_sort_order: boolean,
5 decimal_offset: integer,
6 type: string,
7 name: string,
8 title: {
9 en: string,
10 ru: string
11 }
12}
Example
1function display_leaderboard()
2 ysdk.leaderboards.get_description("highscores",
3 function (self, description)
4 if description then
5 print(
6 description.name,
7 description.title.en
8 )
9 end
10 end)
11end
New score
Alert
The request is available only for authorized users. If necessary, use authorization.
To set a new score for a player, use the ysdk.leaderboards.set_score() method:
1ysdk.leaderboards.set_score(
2 leaderboard_name: string,
3 score: integer,
4 extraData: string|nil
5)
Note
You can send a request no more than once per 1 second; otherwise, it will be rejected with an error.
Getting a ranking
Alert
The request is available only for authorized users. If necessary, use authorization.
To get a user's ranking, use the ysdk.leaderboards.get_player_entry() method:
1ysdk.leaderboards.get_player_entry(
2 leaderboard_name: string,
3 callback: function
4)
callback: function — handler of the invoked method. It looks like:
function(self, player_entry: table|nil): nil
player_entry: table— user rating. Contains properties:
1player_entry: {
2 score: integer,
3 extraData: string,
4 rank: integer,
5 avatar_src: {
6 small: string,
7 medium: string,
8 large: string
9 },
10 avatar_srcset: {
11 small: string,
12 medium: string,
13 large: string
14 },
15 lang: string,
16 public_name: string,
17 unique_id: string,
18 formatted_score: string
19}
Example
1function display_high_score()
2 ysdk.leaderboards.get_player_entry("highscores",
3 function (self, player_entry)
4 if player_entry then
5 print("highscore: " .. player_entry.score)
6 end
7 end)
8end
Leaderboard entries
To display users' ratings, use the ysdk.leaderboards.get_entries() method:
1ysdk.leaderboards.get_entries(
2 leaderboardName: string,
3 callback: function,
4 options: {
5 include_user: boolean|nil,
6 quantity_around: number|nil,
7 quantity_top: number|nil
8 }
9)
callback: function — the handler of the called method. It looks like:
function(self, entries: table|nil): nil
entries: table — users' leaderboard. Contains properties:
1entries: {
2 leaderboard: {
3 ...
4 },
5 ranges: [
6 {
7 start: integer,
8 size: integer
9 }
10 ],
11 userRank: integer,
12 entries: [
13 {
14 score: integer,
15 extraData: string,
16 rank: integer,
17 avatar_src: {
18 small: string,
19 medium: string,
20 large: string
21 },
22 avatar_srcset: {
23 small: string,
24 medium: string,
25 large: string
26 },
27 lang: string,
28 public_name: string,
29 unique_id: string,
30 formatted_score: string
31 },
32 ...
33 ]
34}