Leaderboards

You can display personalized leaderboards on a game page showing the top players' results and a logged-in user's place in the rankings.

For the requests below to work, make sure that:

You have the SDK connected and configured and the SDK object is available via the ysdk variable.
A leaderboard is created in the developer dashboard.

Attention.

If there's no leaderboard in the dashboard with the corresponding name in the Technical leaderboard name field, requests will return a 404 error.

You can use the lb object to manage leaderboards.

Initialization

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

var lb;

ysdk.getLeaderboards()
  .then(_lb => lb = _lb);
Copied to clipboard

Leaderboard description

To get a description of a leaderboard by name, use getLeaderboardDescription:

getLeaderboardDescription(
  leaderboardName: string
)
Copied to clipboard


Parameter	Description
`leaderboardName`	Leaderboard name.

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

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

work();
Copied to clipboard

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`	Application ID.
`default`	If `true`, then it is the primary leaderboard.
`invert_sort_order`	Sort order: `false`: rankings are sorted in descending order. `true`: rankings are sorted in ascending order.
`decimal_offset`	Length of the decimal portion of a score. For example, when `decimal_offset: 2` 1234 will be displayed as 12.34.
`type`	Leaderboard result type. Available parameters: `numeric` (number), `time` (seconds).
`name`	Leaderboard name.
`title`	Localized names. Legal array parameters: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`.


Parameter	Description
`appID`	Application ID.
`default`	If `true`, then it is the primary leaderboard.
`invert_sort_order`	Sort order: `false`: rankings are sorted in descending order. `true`: rankings are sorted in ascending order.
`decimal_offset`	Length of the decimal portion of a score. For example, when `decimal_offset: 2` 1234 will be displayed as 12.34.
`type`	Leaderboard result type. Available parameters: `numeric` (number), `time` (seconds).
`name`	Leaderboard name.
`title`	Localized names. Legal array parameters: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`.

New score

Attention.

The request is only available to logged-in users. If required, 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.

To set a new score for a player, use setLeaderboardScore():

setLeaderboardScore(
  leaderboardName: string,
  score: number,
  extraData?: string
)
      
Copied to clipboard


Parameter	Description
`leaderboardName`	Leaderboard name.
`score`	Score. Only the `integer` type is accepted. Must be greater than 0. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional.


Parameter	Description
`leaderboardName`	Leaderboard name.
`score`	Score. Only the `integer` type is accepted. Must be greater than 0. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional.

Note.

Requests can't be sent more often than once per second. Otherwise, they will be rejected with an error.

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

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  // Without extraData
  await lb.setLeaderboardScore('leaderboard2021', 120);
  // With extraData
  await lb.setLeaderboardScore('leaderboard2021', 120, 'My favorite player!');
}

work();
Copied to clipboard

Getting a ranking

Attention.

The request is only available to logged-in users. If required, 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 getLeaderboardPlayerEntry:

getLeaderboardPlayerEntry(
  leaderboardName: string
)
Copied to clipboard


Parameter	Description
`leaderboardName`	Leaderboard name.

ysdk.getLeaderboards()
  .then(lb => lb.getLeaderboardPlayerEntry('leaderboard2021'))
  .then(res => console.log(res))
  .catch(err => {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // Triggers if the leaderboard doesn't contain an entry for the player
    }
  });
Copied to clipboard

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  try {
    const res = await lb.getLeaderboardPlayerEntry('leaderboard2021');
  } catch (err) {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // Triggers if the leaderboard doesn't contain an entry for the player
    }
  }
  console.log(res);
}

work();
Copied to clipboard

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. Must be greater than 0. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional.
`getAvatarSrc`	Returns the URL of a user's photo. Available values for `size`: `small`, `medium`, and `large`.
`getAvatarSrcSet`	Returns a srcset of a user's photo that is suitable for Retina displays. Available values for `size`: `small`, `medium`, and `large`.


Parameter	Description
`score`	Score. Only the `integer` type is accepted. Must be greater than 0. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional.
`getAvatarSrc`	Returns the URL of a user's photo. Available values for `size`: `small`, `medium`, and `large`.
`getAvatarSrcSet`	Returns a srcset of a user's photo that is suitable for Retina displays. Available values for `size`: `small`, `medium`, and `large`.

Leaderboard entries

To display user rankings, use getLeaderboardEntries:

getLeaderboardEntries(
  leaderboardName: string,
  {
    includeUser: boolean,
    quantityAround: integer,
    quantityTop: integer
  }
)
Copied to clipboard


Parameter	Description
`leaderboardName`	Leaderboard name.
`includeUser`	Defines whether to include the logged-in user in the response: `true`: include in the response. `false` (default): 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 is 5.
`quantityTop`	Number of entries from the top of the leaderboard. The minimum value is 1, the maximum value is 20. The default is 5.


Parameter	Description
`leaderboardName`	Leaderboard name.
`includeUser`	Defines whether to include the logged-in user in the response: `true`: include in the response. `false` (default): 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 is 5.
`quantityTop`	Number of entries from the top of the leaderboard. The minimum value is 1, the maximum value is 20. The default is 5.

ysdk.getLeaderboards()
  .then(lb => {
    // Using all defaults
    lb.getLeaderboardEntries('leaderboard2021')
      .then(res => console.log(res));
    // Getting the top 10
    lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10 })
      .then(res => console.log(res));
    // Returning the top 10 and 3 entries on either side of the user
    lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
      .then(res => console.log(res));
  });
Copied to clipboard

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  let res;
  // Using all defaults
  res = await lb.getLeaderboardEntries('leaderboard2021');
  console.log(res);
  // Getting the top 10
  res = await lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10 });
  console.log(res);
  // Returning the top 10 and 3 entries on either side of the user
  res = await lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 });
  console.log(res);
}

work();
Copied to clipboard

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. The count starts at 0, so 1st 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 none or if the request is for the top of the table without including the user.
`entries`	Requested entries.
`score`	Score. Only the `integer` type is accepted. Must be greater than 0. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional.
`getAvatarSrc`	Returns the URL of a user's photo. Available values for `size`: `small`, `medium`, and `large`.
`getAvatarSrcSet`	Returns a srcset of a user's photo that is suitable for Retina displays. Available values for `size`: `small`, `medium`, and `large`.


Parameter	Description
`leaderboard`	Leaderboard description.
`ranges`	Ranking ranges in the response.
`start`	Placement in the rankings. The count starts at 0, so 1st 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 none or if the request is for the top of the table without including the user.
`entries`	Requested entries.
`score`	Score. Only the `integer` type is accepted. Must be greater than 0. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional.
`getAvatarSrc`	Returns the URL of a user's photo. Available values for `size`: `small`, `medium`, and `large`.
`getAvatarSrcSet`	Returns a srcset of a user's photo that is suitable for Retina displays. Available values for `size`: `small`, `medium`, and `large`.

Support

Note. Our support team can help publish finished games or WebApp on Yandex Games. Other developers in the Telegram community will gladly answer any practical questions about development and testing.

If you're experiencing problems with the Yandex Games SDK or want to ask a question, please contact support:

Write to chat

Send an email