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:

You've enabled and configured the SDK, and its object is available via the ysdk variable.
You've created a leaderboard in the Games Console.

Alert

When your app requests a leaderboard, make sure that the leaderboard name in the request matches its name in the Technical leaderboard name field in the Games Console. Otherwise, the request returns a 404 error.

Initialization

To call leaderboard methods directly, use ysdk.leaderboards.

Alert

Initializing the lb object via ysdk.getLeaderboards() is deprecated.

Legacy methods

var lb;

ysdk.getLeaderboards()
  .then(_lb => lb = _lb);

  // Leaderboard methods when called via the legacy approach:
  // lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
  // lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
  // lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
  // lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()

Leaderboard description

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

getDescription(
  leaderboardName: string
)

Parameter	Description
`leaderboardName`	Leaderboard name.

Sample request

Sample ES2017 async/await request

ysdk.leaderboards.getDescription('leaderboard2021')
  .then(res => console.log(res));

const work = async () => {
  const res = await ysdk.leaderboards.getDescription('leaderboard2021');
  console.log(res);
}

work();

Response format

{
  appID: string,
  default: boolean,
  description: {
    invert_sort_order: boolean,
    score_format: {
      options: {
        decimal_offset: integer
      },
      type: string
    }
  },
  name: string,
  title: {
    en: string,
    ru: string
  }
}

Parameter	Description
`appID`	App ID.
`default`	If `true`, then it is the primary leaderboard.
`invert_sort_order`	Sort order: `false`: Places are sorted in descending order. `true`: Places are sorted in ascending order.
`decimal_offset`	Score offset. For example, with `decimal_offset: 2`, the number 1234 is displayed as 12.34.
`type`	Leaderboard result type. Acceptable parameters: `numeric` (a number), `time` (in seconds).
`name`	Leaderboard name.
`title`	Localized names. Possible array parameters: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`.

New score

Alert

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

To check whether the method is available for the user, you can use the ysdk.isAvailableMethod('leaderboards.setScore') method. It returns Promise<Boolean>, where the boolean value indicates whether the method is available.

If you want the results to be saved for all users regardless of their login status, we recommend that you add a custom leaderboard manually in your app source code. You are free to choose any technology for this purpose.

To set a new score for a player, use the ysdk.leaderboards.setScore() method.

setScore(
  leaderboardName: string,
  score: number,
  extraData?: string
)

Parameter	Description
`leaderboardName`	Leaderboard name.
`score`	Score. Only the `integer` type is accepted. The value is non-negative, with the maximum limited only by the JavaScript logic. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional parameter.

Note

The number of requests is limited to 60 times per minute. Otherwise, they will be rejected with an error.

Sample request

Sample ES2017 async/await request

// Without extraData.
ysdk.leaderboards.setScore('leaderboard2021', 120);
// With extraData.
ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');

const work = async () => {
  // Without extraData.
  await ysdk.leaderboards.setScore('leaderboard2021', 120);
  // With extraData.
  await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
}

work();

Getting a ranking

Alert

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

To check whether the method is available for the user, you can use the ysdk.isAvailableMethod('leaderboards.getPlayerEntry') method. It returns Promise<Boolean>, where the boolean value indicates whether the method is available.

To get a user's ranking, use the ysdk.leaderboards.getPlayerEntry() method:

getPlayerEntry(
  leaderboardName: string
)

Parameter	Description
`leaderboardName`	Leaderboard name.

Note

The number of requests is limited to 60 times in five minutes. Otherwise, they will be rejected with an error.

Sample request

Sample ES2017 async/await request

ysdk.leaderboards.getPlayerEntry('leaderboard2021')
  .then(res => console.log(res))
  .catch(err => {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // This error is thrown if the leaderboard doesn't have an entry for the player.
    }
  });

const work = async () => {
  try {
    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
    console.log(res);
  } catch (err) {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // This error is thrown if the leaderboard doesn't have an entry for the player.
    }
  }
}

work();

Response format

{
  score: integer,
  extraData: string,
  rank: integer,
  player: {
    getAvatarSrc: (size: string) => string,
    getAvatarSrcSet: (size: string) => string,
    lang: string,
    publicName: string,
    scopePermissions: {
      avatar: string,
      public_name: string
    },
    uniqueID: string,
  },
  formattedScore: string
}

Parameter	Description
`score`	Score. Only the `integer` type is accepted. The value is non-negative, with the maximum limited only by the JavaScript logic. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional parameter.
`getAvatarSrc`	Returns the URL of a user's photo. Acceptable `size` values: `small`, `medium`, and `large`.
`getAvatarSrcSet`	Returns a srcset of a user's photo that is suitable for Retina displays. Acceptable `size` values: `small`, `medium`, and `large`.

Leaderboard entries

To display users' ratings, use the ysdk.leaderboards.getEntries() method:

getEntries(
  leaderboardName: string,
  {
    includeUser: boolean,
    quantityAround: integer,
    quantityTop: integer
  }
)

Parameter	Description
`leaderboardName`	Leaderboard name.
`includeUser`	Defines whether to include the logged-in user in the response: `true`: Include in the response. `false` (default value): Do not include.
`quantityAround`	Number of entries to return below and above the user in the leaderboard. The minimum value is 1. The maximum value is 10. The default return value is 5.
`quantityTop`	Number of entries from the top of the leaderboard. The minimum value is 1. The maximum value is 20. The default return value is 5.

Note

The number of requests is limited to 20 times in five minutes. Otherwise, they will be rejected with an error.

Sample request

Sample ES2017 async/await request

// Using all defaults.
ysdk.leaderboards.getEntries('leaderboard2021')
  .then(res => console.log(res));
// Requesting the top 10 entries.
ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 })
  .then(res => console.log(res));
// Requesting the top 10 entries and 3 entries above and below the user's entry.
ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
  .then(res => console.log(res));

const work = async () => {
  let res;
  // Using all defaults.
  res = await ysdk.leaderboards.getEntries('leaderboard2021');
  console.log(res);
  // Requesting the top 10 entries.
  res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 });
  console.log(res);
  // Requesting the top 10 entries and 3 entries above and below the user's entry.
  res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 });
  console.log(res);
}

work();

Response format

{
  leaderboard: {
    ...
  },
  ranges: [
    {
      start: integer,
      size: integer
    }
  ],
  userRank: integer,
  entries: [
    {
      score: integer,
      extraData: string,
      rank: integer,
      player: {
        getAvatarSrc: (size: string) => string,
        getAvatarSrcSet: (size: string) => string,
        lang: string,
        publicName: string,
        scopePermissions: {
          avatar: string,
          public_name: string
        },
        uniqueID: string,
      },
    formattedScore: string
    },
    ...
  ]
}

Parameter	Description
`leaderboard`	Leaderboard description.
`ranges`	Ranking ranges in the response.
`start`	Placement in the rankings. Numbering starts from zero, so the first place is considered the 0th element.
`size`	Number of entries requested. If there isn't enough data, the number returned may not be the number requested.
`userRank`	User's rank. Returns 0 if the user's score isn't in the rankings or if the request is for the top rankings without including the user.
`entries`	Requested entries.
`score`	Score. Only the `integer` type is accepted. The value is non-negative, with the maximum limited only by the JavaScript logic. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional parameter.
`getAvatarSrc`	Returns the URL of a user's photo. Acceptable `size` values: `small`, `medium`, and `large`.
`getAvatarSrcSet`	Returns a srcset of a user's photo that is suitable for Retina displays. Acceptable `size` values: `small`, `medium`, and `large`.

Method requests limits

Method	Description	Limit	User login
`ysdk.leaderboards.setScore()`	Sets a new score for a player	60 requests per minute	Required
`ysdk.leaderboards.getPlayerEntry()`	Returns leaderboard ranking for a single user	60 requests in five minutes	Required
`ysdk.leaderboards.getEntries()`	Returns leaderboard rankings for multiple users	20 requests in five minutes	Optional

The limit for other requests is 20 requests in five minutes.

Known issues

Tip

When using the ysdk.isAvailableMethod() and ysdk.leaderboards.setScore() methods together, logged-out users do not appear on the leaderboard and cannot see their progress. It makes sense to create another leaderboard with the scores of all your users and display this leaderboard to everyone. You can create custom leaderboards in your app source code using any technology you like.

Object already exists

An error occurs when trying to create a new leaderboard named as an old one. To avoid this, enter a name you haven't used previously.

User is hidden

The label "User is hidden" appears when a player hasn't allowed the use of their avatar and name. Access to user data depends on their profile settings. For details, see the Player data section.

Error 404

If you encounter a 404 error when trying to call SDK methods for the leaderboard, please make sure that a leaderboard with the corresponding name is created in the developer console under Technical leaderboard name field.

Note

Our support team can help publish finished games on Yandex Games. If you have any questions about development or testing, ask them in the Discord channel.

If you are facing an issue or have a question regarding the use of Yandex Games SDK, please contact support:

Write to chat

Was the article helpful?

In-game purchases

Asynchronous multiplayer