Skip to main content

Leaderboards

You can display personalized leaderboards on the game page with the results of the best players and the position of the authorized user in the rating.

To make the queries described below work, make sure that the following conditions are met:

  • you have connected and configured the SDK and its object is available through the variable ysdk;

  • in the developer console, a leaderboard has been created with the corresponding name in the Technical name of the leaderboard field.

info

If there is no leaderboard with the corresponding name in the console, the queries will return a 404 error.

Leaderboard description​

To get the description of the leaderboard by its name, use the ysdk.leaderboards.get_description() method:

ysdk.leaderboards.get_description(
    leaderboard_name: string,
    callback: function
)

callback — function — the handler of the called method. It looks like this:

function(self, description: table|nil): nil
  • description: table — the description of the leaderboard. Contains properties: 
    description: {
      app_id: string,
      dеfault: boolean,
      invert_sort_order: boolean,
      decimal_offset: integer,
      type: string,
      name: string,
      title: {
        en: string,
        ru: string
      }
    }

Example​

function display_leaderboard()
  ysdk.leaderboards.get_description("highscores",
    function (self, description)
      if description then
        print(
          description.name,
          description.title.en
        )
    end
  end)
end

New result ​

info

The request is available only for authorized users. If necessary, use authorization.

To set a new result for a player, use the ysdk.leaderboards.set_score() method:

ysdk.leaderboards.set_score(
    leaderboard_name: string,
    score: integer,
    extraData: string|nil
)
info

The request can be sent no more than once per second. Otherwise, it will be rejected with an error.

Getting a rating ​

info

The request is available only for authorized users. If necessary, use authorization.

To get the user's rating, use the ysdk.leaderboards.get_player_entry() method:

ysdk.leaderboards.get_player_entry(
    leaderboard_name: string,
    callback: function
)

callback: function — the handler of the called method. It looks like this:

function(self, player_entry: table|nil): nil
  • player_entry: table — the user's rating. Contains properties: 
    player_entry: {
      score: integer,
      extraData: string,
      rank: integer,
      avatar_src: {
        small: string,
        medium: string,
        large: string,
      },
      avatar_srcset: {
        small: string,
        medium: string,
        large: string,
      },
      lang: string,
      public_name: string,
      unique_id: string,
      formatted_score: string
    }

Example​

function display_high_score()
  ysdk.leaderboards.get_player_entry("highscores",
    function (self, player_entry)
      if player_entry then
        print("highscore: " .. player_entry.score)
      end
    end)
end

Leaderboard records ​

To display the user rating, use the ysdk.leaderboards.get_entries() method:

ysdk.leaderboards.get_entries(
    leaderboardName: string,
    callback: function,
    options: {
        include_user: boolean|nil,
        quantity_around: number|nil,
        quantity_top: number|nil
    }
)

callback: function — the handler of the called method. It looks like this:

function(self, entries: table|nil): nil
  • entries: table — the user rating. Contains properties: 
    entries: {
      leaderboard: {
        ...
      },
      ranges: [
        {
          start: integer,
          size: integer
        }
      ],
      userRank: integer,
      entries: [
        {
          score: integer,
          extraData: string,
          rank: integer,
          avatar_src: {
            small: string,
            medium: string,
            large: string,
          },
          avatar_srcset: {
            small: string,
            medium: string,
            large: string,
          },
          lang: string,
          public_name: string,
          unique_id: string,
          formatted_score: string
        },
        ...
      ]
    }