Leaderboards

On the game page, you can display personalized leaderboards showing the results of top players and the position of the authorized user in the ranking.

For leaderboard requests to work, meet the following conditions:

In the game code, enable and configure the SDK so that its object is available via the ysdk variable.
In the Developer Console, create a leaderboard.

Alert

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

Initialization

To call leaderboard methods, access ysdk.leaderboards directly.

Alert

Initializing the lb object using the ysdk.getLeaderboards() method is deprecated.

Legacy methods

 1const ysdk = await YaGames.init();
 2
 3const lb = await ysdk.getLeaderboards();
 4
 5// Correspondence of leaderboard method calls between old and new approaches:
 6// lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
 7// lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
 8// lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
 9// lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()

Leaderboard description

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

Method signature:

 1interface ILeaderboardDescription {
 2    appID: string;
 3    default: boolean;
 4    description: {
 5        invert_sort_order: boolean;
 6        score_format: {
 7            options: {
 8                decimal_offset: number;
 9            };
10            type: 'numeric' | 'time';
11        };
12        sort_order: string;
13    };
14    name: string;
15    title: Record<Locale, string>;
16}
17
18function getDescription(
19    leaderboardName: string
20): Promise<ILeaderboardDescription> {}

Takes the technical leaderboard name leaderboardName as the only parameter. Returns an object with the leaderboard description, which includes the following fields:

Parameter	Type	Description
`appID`	`string`	Application ID.
`default`	`boolean`	If `true`, the leaderboard is the main one.
`invert_sort_order`	`boolean`	Sort direction: `false` — descending (users with the highest score will be at the top). `true` — ascending (users with the lowest score will be at the top).
`sort_order`	`string`	Sort direction in string format: `'DESC'` — descending. `'ASC'` — ascending.
`decimal_offset`	`number`	Size of the decimal part of the score. For example, with `decimal_offset: 2`, the number 1234 will be displayed as 12.34.
`type`	`'numeric'` \| `'time'`	Leaderboard result type. Available values: `numeric` (number), `time` (milliseconds).
`name`	`string`	Leaderboard name specified in the Console in the Technical leaderboard name field.
`title`	`Record<Locale, string>`	List of localized titles. Possible language codes are listed on the Languages and domains page.

Example

1const ysdk = await YaGames.init();
2
3const lb = await ysdk.leaderboards.getDescription('leaderboard2021');
4
5console.log(lb);

New score

Alert

The request is available only for authorized users. For how to check authorization status and invoke the login dialog, see User login.

Before sending the request, check method availability using ysdk.isAvailableMethod('leaderboards.setScore'). The method returns Promise<Boolean>.

To save results for all users regardless of authorization, we recommend implementing a custom leaderboard in your application code. Technology choice is not limited.

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

Method signature:

1function setScore(
2    leaderboardName: string,
3    score: number,
4    extraData?: string
5): Promise<void> {}

Takes three parameters:

Parameter	Type	Description
`leaderboardName`	`string`	Leaderboard name specified in the Console in the Technical leaderboard name field.
`score`	`number`	Result value. Cannot be negative, the maximum value is limited only by JavaScript logic. If the leaderboard type is `time`, the value must be passed in milliseconds.
`extraData`	`string`	User description. Optional parameter.

Note

Requests can be sent no more than once per second, otherwise they will be rejected with an error.

Example

1const ysdk = await YaGames.init();
2
3await ysdk.leaderboards.setScore('leaderboard2021', 120);
4
5await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');

Getting ranking

Alert

The request is available only for authorized users. For how to check authorization status and invoke the login dialog, see User login.

Before sending the request, check method availability using ysdk.isAvailableMethod('leaderboards.getPlayerEntry'). The method returns Promise<Boolean>.

To save results for all users regardless of authorization, we recommend implementing a custom leaderboard in your application code. Technology choice is not limited.

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

Method signature:

 1interface ILeaderboardEntry {
 2    extraData: string;
 3    rank: number;
 4    score: number;
 5    player: {
 6        publicName: string;
 7        uniqueID: string;
 8        getAvatarSrc: (size?: 'small' | 'medium' | 'large') => string;
 9        getAvatarSrcSet: (size?: 'small' | 'medium' | 'large') => string;
10    }
11}
12
13function getPlayerEntry(
14    leaderboardName: string
15): Promise<ILeaderboardEntry> {}

Takes the technical leaderboard name leaderboardName as the only parameter. Returns an object with the user's ranking, which includes the following fields:

Parameter	Type	Description
`score`	`number`	Result value.
`rank`	`number`	User's position in the leaderboard.
`extraData`	`string`	User description.
`publicName`	`string`	User name.
`uniqueID`	`string`	Unique user ID.
`getAvatarSrc`	`(size?: TSize) => string`	Returns the URL of the user's avatar in the specified size. Possible `size` values: `small`, `medium`, `large`.
`getAvatarSrcSet`	`(size?: TSize) => string`	Returns the srcset of the user's avatar, suitable for Retina displays. Possible `size` values: `small`, `medium`, `large`.

Note

Requests can be sent no more than 60 times in 5 minutes, otherwise they will be rejected with an error.

Example

 1const ysdk = await YaGames.init();
 2
 3try {
 4    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
 5
 6    console.log(res);
 7} catch (err) {
 8    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
 9        // Triggered if the player has no entry in the leaderboard.
10    }
11}

Leaderboard entries

To display user rankings, use the ysdk.leaderboards.getEntries() method.

Method signature:

 1interface ILeaderboardEntries {
 2    leaderboard: ILeaderboardDescription;
 3    ranges: {
 4        start: number;
 5        size: number;
 6    }[];
 7    userRank: number;
 8    entries: ILeaderboardEntry[];
 9}
10
11function getEntries(
12    leaderboardName: string,
13    options: {
14        includeUser?: boolean;
15        quantityAround?: number;
16        quantityTop?: number;
17    }
18): Promise<ILeaderboardEntries> {}

Takes the technical leaderboard name leaderboardName and optional options parameters:

Option	Type	Description
`includeUser`	`boolean`	Determines whether to include the authorized user in the response: `true` — include in the response. `false` (default) — do not include.
`quantityAround`	`number`	Number of entries below and above the user in the leaderboard to return. Minimum value is 1, maximum is 10. Default is 5.
`quantityTop`	`number`	Number of entries from the top of the leaderboard. Minimum value is 1, maximum is 20. Default is 5.

Returns an object with user rankings Promise<ILeaderboardEntries>, which includes the following fields:

Parameter	Type	Description
`leaderboard`	`ILeaderboardDescription`	Leaderboard description
`ranges`	`object[]`	Position ranges in the response.
`start`	`number`	Position in the leaderboard. Counting starts from zero, so 1st place is considered the zero element.
`size`	`number`	Number of requested entries. If there is not enough data, it may not match the response.
`userRank`	`number`	User's position in the leaderboard. If absent, or if the request is for the top without including the user, it equals 0.
`entries`	`ILeaderboardEntry[]`	Array of leaderboard entries. An entry is identical to the return value from the Getting ranking method.

Note

Requests can be sent no more than 20 times in 5 minutes, otherwise they will be rejected with an error.

Example

 1const ysdk = await YaGames.init();
 2
 3// Getting top 10 players and 3 entries around the user.
 4const entries = await ysdk.leaderboards.getEntries('leaderboard2021', {
 5    quantityTop: 10,
 6    includeUser: true,
 7    quantityAround: 3
 8});
 9
10console.log(entries);

Method limits

Method	Description	Limit	User authorization
`ysdk.leaderboards.setScore()`	Set a new player result	1 request per 1 second	Required
`ysdk.leaderboards.getPlayerEntry()`	Display one user's rating	60 requests per 5 minutes	Required
`ysdk.leaderboards.getEntries()`	Get multiple users' rating	20 requests per 5 minutes	Optional

Limit for other requests: 20 requests in 5 minutes.

Troubleshooting

Tip

When using the combination of ysdk.isAvailableMethod() and ysdk.leaderboards.setScore() methods, unauthorized users are not included in the leaderboard and cannot see their progress. To save results for all players, we recommend creating a custom leaderboard in your application code. Technology choice is not limited.

Object already exists

The error occurs when trying to create a new leaderboard with the name of an old one. Enter a name that hasn't been used before.

User is hidden

The label "User is hidden" is displayed if the player hasn't allowed the use of their avatar and name. Access to user data depends on the settings in their profile. For more details, see Initialization.

Error 404

If a 404 error occurs when calling SDK methods for the leaderboard, check that a leaderboard with the corresponding name has been created in the Developer Console in the 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-app purchases

Asynchronous multiplayer