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.

To manage leaderboards, use the lb object.

Initialization

To initialize the lb object, use the ysdk.getLeaderboards() method:

var lb;

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

Leaderboard description

To get a description of a leaderboard by its name, use the getLeaderboardDescription() method:

getLeaderboardDescription(
  leaderboardName: string
)

Parameter	Description
`leaderboardName`	Leaderboard name.

Sample request

Sample ES2017 async/await request

ysdk.getLeaderboards()
  .then(lb => lb.getLeaderboardDescription('leaderboard2021'))
  .then(res => console.log(res));

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  const res = await lb.getLeaderboardDescription('leaderboard2021');
  console.log(res);
}

work();

Response format

{
  appID: string,
  dеfault: 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.setLeaderboardScore') 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 setLeaderboardScore() method.

setLeaderboardScore(
  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

ysdk.getLeaderboards()
  .then(lb => {
    // Without extraData.
    lb.setLeaderboardScore('leaderboard2021', 120);
    // With extraData.
    lb.setLeaderboardScore('leaderboard2021', 120, 'My favourite player!');
  });

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  // Without extraData.
  await lb.setLeaderboardScore('leaderboard2021', 120);
  // With extraData.
  await lb.setLeaderboardScore('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.getLeaderboardPlayerEntry') method. It returns Promise<Boolean>, where the boolean value indicates whether the method is available.

To get a user's ranking, use the getLeaderboardPlayerEntry() method:

getLeaderboardPlayerEntry(
  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.getLeaderboards()
  .then(lb => lb.getLeaderboardPlayerEntry('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 () => {
  const lb = await ysdk.getLeaderboards();
  try {
    const res = await lb.getLeaderboardPlayerEntry('leaderboard2021');
  } catch (err) {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // This error is thrown if the leaderboard doesn't have an entry for the player.
    }
  }
  console.log(res);
}

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 getLeaderboardEntries() method:

getLeaderboardEntries(
  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

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

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  let res;
  // Using all defaults.
  res = await lb.getLeaderboardEntries('leaderboard2021');
  console.log(res);
  // Requesting the top 10 entries.
  res = await lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10 });
  console.log(res);
  // Requesting the top 10 entries and 3 entries above and below the user's entry.
  res = await lb.getLeaderboardEntries('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
`lb.setLeaderboardScore()`	Sets a new score for a player	60 requests per minute	Required
`lb.getLeaderboardPlayerEntry()`	Returns leaderboard ranking for a single user	60 requests in five minutes	Required
`lb.getLeaderboardEntries()`	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 lb.setLeaderboardScore() 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 "User is hidden" label appears if your app didn't request access to the user's name and profile picture from their Yandex account at login. This can also happen if the user declined to allow access to these details.

Make sure you request user data ysdk.getPlayer({ scopes: true }) when showing the access request window. If you use the scopes: false parameter, the game app doesn't request the user's name and profile picture.

If the user denied access, the app can't request it again in the current browser session.

If the player clears their cache and cookies, opens their browser in incognito mode, or uses a different browser, your app may prompt them to log in and grant access again. To learn how to invoke this dialog box, see Player data.

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

Game Rating