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:

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}

Repository