Leaderboards

You can display personalized leaderboards on the game page showing the top players' results and the user's position in the ranking.

For the requests below to work, make sure that:

Alert

If there is no leaderboard with the corresponding name in the Technical leaderboard name field in the console, requests will result in a 404 error.

Leaderboard description

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

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

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:
description: {
  app_id: string,
  default: 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 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:

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

Note

The request can only be sent once per 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:

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

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

function(self, player_entry: table|nil): nil
  • player_entry: table — user 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 entries

To display users' ratings, 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:

function(self, entries: table|nil): nil

entries: table — users' leaderboard. 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
    },
    ...
  ]
}
Repository
Previous
Events
Next
Desktop shortcut