Leaderboards

Initialization
Leaderboard description
New score
Getting a ranking
Leaderboard entries

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

If there's no leaderboard with its name in the Technical leaderboard name field in the Games Console, requests return 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`: Scores are sorted in descending order. `true`: Scores 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.

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 integer must not be a negative number. If the leaderboard type is `time`, the values must be passed in milliseconds.
`extraData`	User description. Optional parameter.

Note

Requests can't be sent more often than once per second. 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.

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') {
      // Triggers if the leaderboard doesn't contain 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') {
      // Triggers if the leaderboard doesn't contain 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 integer must not be a negative number. 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.

Sample request

Sample ES2017 async/await request

ysdk.getLeaderboards()
  .then(lb => {
    // Using all defaults
    lb.getLeaderboardEntries('leaderboard2021')
      .then(res => console.log(res));
    // Returning 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));
  });

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();

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 integer must not be a negative number. 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`.

Note

Our support team can help publish finished games or WebApps 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

Leaderboards

InitializationInitialization

Leaderboard descriptionLeaderboard description

Response formatResponse format

New scoreNew score

Getting a rankingGetting a ranking

Response formatResponse format

Leaderboard entriesLeaderboard entries

Response formatResponse format

Was the article helpful?

Initialization

Leaderboard description

Response format

New score

Getting a ranking

Response format

Leaderboard entries

Response format