--- metadata: - name: generator content: Diplodoc Platform v5.55.2 alternate: - https://yandex.com/dev/games/doc/en/sdk/sdk-leaderboard.md - https://yandex.com/dev/games/doc/hi/sdk/sdk-leaderboard.md - https://yandex.com/dev/games/doc/ko/sdk/sdk-leaderboard.md - https://yandex.com/dev/games/doc/ru/sdk/sdk-leaderboard.md - https://yandex.com/dev/games/doc/tr/sdk/sdk-leaderboard.md - https://yandex.com/dev/games/doc/vi/sdk/sdk-leaderboard.md - https://yandex.com/dev/games/doc/zh/sdk/sdk-leaderboard.md - href: en/sdk/sdk-leaderboard.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/en/llms.txt # 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](https://yandex.com/dev/games/doc/en/sdk/sdk-about.md#use) so that its object is available via the `ysdk` variable. - In the Developer Console, [create](https://yandex.com/dev/games/doc/en/concepts/leaderboards.md) a leaderboard. {% note alert %} If there is no leaderboard with the corresponding name in the **Technical leaderboard name** field in the [Console](https://games.yandex.com/console){.external}, requests will return a 404 error. {% endnote %} ## Initialization {#init} To call leaderboard methods, access `ysdk.leaderboards` directly. {% note alert %} Initializing the `lb` object using the `ysdk.getLeaderboards()` method is deprecated. {% cut "Legacy methods" %} ```javascript showLineNumbers const ysdk = await YaGames.init(); const lb = await ysdk.getLeaderboards(); // Correspondence of leaderboard method calls between old and new approaches: // lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription() // lb.setLeaderboardScore() → ysdk.leaderboards.setScore() // lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry() // lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries() ``` {% endcut %} {% endnote %} ## Leaderboard description {#description} To get a leaderboard description by its name, use the `ysdk.leaderboards.getDescription()` method. **Method signature** ```typescript showLineNumbers interface ILeaderboardDescription { [appID](*key_appID): string; [default](*key_default): boolean; description: { [invert_sort_order](*key_invert_sort_order): boolean; score_format: { options: { [decimal_offset](*key_decimal_offset): number; }; [type](*key_type): 'numeric' | 'time'; }; [sort_order](*key_sort_order): string; }; [name](*key_name): string; [title](*key_title): Record; } function getDescription( [leaderboardName](*key_name): string ): Promise {} ``` 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` | List of localized titles. Possible language codes are listed on the [Languages and domains](https://yandex.com/dev/games/doc/en/concepts/languages-and-domains.md) page. || |#
#### Example {#description-example} ```javascript showLineNumbers const ysdk = await YaGames.init(); const lb = await ysdk.leaderboards.getDescription('leaderboard2021'); console.log(lb); ``` ## New score {#set-score} {% note alert %} The request is available only for authorized users. For how to check authorization status and invoke the login dialog, see [User authorization](https://yandex.com/dev/games/doc/en/sdk/sdk-player.md#auth). Before sending the request, check method availability using `ysdk.isAvailableMethod('leaderboards.setScore')`. The method returns `Promise`. To save results for all users regardless of authorization, we recommend implementing a custom leaderboard in your application code. Technology choice is not limited. {% endnote %} To set a new score for a player, use the `ysdk.leaderboards.setScore()` method. **Method signature** ```typescript showLineNumbers function setScore( [leaderboardName](*key_name): string, [score](*key_score): number, [extraData](*key_extraData)?: string ): Promise {} ``` Accepts 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](*key_type) is `time`, the value must be passed in milliseconds. || || `extraData` | `string` | User description. Optional parameter. || |#
{% note info %} Requests can be sent no more than once per second, otherwise they will be rejected with an error. {% endnote %} #### Example {#set-score-example} ```javascript showLineNumbers const ysdk = await YaGames.init(); await ysdk.leaderboards.setScore('leaderboard2021', 120); await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!'); ``` ## Getting ranking {#get-entry} {% note alert %} The request is available only for authorized users. For how to check authorization status and invoke the login dialog, see [User authorization](https://yandex.com/dev/games/doc/en/sdk/sdk-player.md#auth). Before sending the request, check method availability using `ysdk.isAvailableMethod('leaderboards.getPlayerEntry')`. The method returns `Promise`. To save results for all users regardless of authorization, we recommend implementing a custom leaderboard in your application code. Technology choice is not limited. {% endnote %} To get a user's ranking, use the `ysdk.leaderboards.getPlayerEntry()` method. **Method signature** ```typescript showLineNumbers interface ILeaderboardEntry { [extraData](*key_extraData): string; [rank](*key_userRank): number; [score](*key_score): number; player: { [publicName](*key_publicName): string; [uniqueID](*key_uniqueID): string; [getAvatarSrc](*key_getAvatarSrc): (size?: 'small' | 'medium' | 'large') => string; [getAvatarSrcSet](*key_getAvatarSrcSet): (size?: 'small' | 'medium' | 'large') => string; } } function getPlayerEntry( [leaderboardName](*key_name): string ): Promise {} ``` 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 info %} Requests can be sent no more than 60 times in 5 minutes, otherwise they will be rejected with an error. {% endnote %} #### Example {#get-entry-example} ```javascript showLineNumbers const ysdk = await YaGames.init(); try { const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021'); console.log(res); } catch (err) { if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') { // Triggered if the player has no entry in the leaderboard. } } ``` ## Leaderboard entries {#get-entries} To display user rankings, use the `ysdk.leaderboards.getEntries()` method. **Method signature** ```typescript showLineNumbers interface ILeaderboardEntries { [leaderboard](*key_leaderboard): ILeaderboardDescription; [ranges](*key_ranges): { [start](*key_start): number; [size](*key_size): number; }[]; [userRank](*key_userRank): number; [entries](*key_entries): ILeaderboardEntry[]; } function getEntries( [leaderboardName](*key_name): string, options: { [includeUser](*key_includeUser)?: boolean; [quantityAround](*key_quantityAround)?: number; [quantityTop](*key_quantityTop)?: number; } ): Promise {} ``` 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`, which includes the following fields:
#| || **Parameter** | **Type** | **Description** || || `leaderboard` | `ILeaderboardDescription` | [Leaderboard description](#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](#get-entry) method. || |#
{% note info %} Requests can be sent no more than 20 times in 5 minutes, otherwise they will be rejected with an error. {% endnote %} #### Example {#get-entries-example} ```javascript showLineNumbers const ysdk = await YaGames.init(); // Getting top 10 players and 3 entries around the user. const entries = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 }); console.log(entries); ``` ## Method limits {#limits}
#| || **Method** | **Description** | **Limit** | **User authorization** || || `ysdk.leaderboards.setScore()` | [Set a new player result](#set-score) | 1 request per 1 second | Required || || `ysdk.leaderboards.getPlayerEntry()` | [Display one user's rating](#get-entry) | 60 requests per 5 minutes | Required || || `ysdk.leaderboards.getEntries()` | [Get multiple users' rating](#get-entries) | 20 requests per 5 minutes | Optional || |#
Limit for other requests: 20 requests in 5 minutes. ## Troubleshooting {#faq} {% note 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. {% endnote %} ### Object already exists {#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 {#player-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](https://yandex.com/games/user){.external}. For more details, see [Initialization](https://yandex.com/dev/games/doc/en/sdk/sdk-player.md#getplayer). ### Error 404 {#leaderboard-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](https://games.yandex.com/console){.external} in the **Technical leaderboard name** field. --- {% note info %} 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](https://discord.com/invite/wU4p3whr4T){.external}. {% endnote %} If you are facing an issue or have a question regarding the use of Yandex Games SDK, please contact support: Write to chat [*key_name]: Leaderboard name specified in the Console in the **Technical leaderboard name** field. [*key_appID]: Application ID. [*key_default]: If true, the leaderboard is the primary one. [*key_invert_sort_order]: Sort direction: - `false` — descending (users with the highest scores will be in the top positions). - `true` — ascending (users with the lowest scores will be in the top positions). [*key_sort_order]: Sort direction in string format: - `'DESC'` — descending (users with the highest scores will be in the top positions). - `'ASC'` — ascending (users with the lowest scores will be in the top positions). [*key_decimal_offset]: Decimal part size of the score. For example, with decimal_offset: 2, the number 1234 will be displayed as 12.34. [*key_type]: Leaderboard result type. Available values: `numeric` (number), `time` (milliseconds). [*key_title]: List of localized names. Possible language codes are listed on the [{#T}](https://yandex.com/dev/games/doc/en/concepts/languages-and-domains.md) page. [*key_score]: Score value. Cannot be negative, maximum value is limited only by JavaScript logic. [*key_extraData]: User description. [*key_userRank]: User's position in the leaderboard. [*key_publicName]: User's name. [*key_uniqueID]: User's unique ID. [*key_getAvatarSrc]: Returns the URL of the user's avatar. Possible `size` values: `small`, `medium`, `large`. [*key_getAvatarSrcSet]: Returns the srcset of the user's avatar, suitable for Retina displays. Possible `size` values: `small`, `medium`, `large`. [*key_includeUser]: Determines whether to include the authorized user in the response: - `true` — include in the response. - `false` (default) — do not include. [*key_quantityAround]: Number of entries below and above the user in the leaderboard to return. Minimum value is 1, maximum is 10. Default is 5. [*key_quantityTop]: Number of entries from the top of the leaderboard. Minimum value is 1, maximum is 20. Default is 5. [*key_leaderboard]: [{#T}](#description). [*key_ranges]: Position ranges in the response. [*key_start]: Position in the ranking. Counting starts from zero, so 1st place is considered the zero element. [*key_size]: Number of requested entries. May not match the response if there is insufficient data. [*key_entries]: Array of ranking entries. An entry is identical to the return value from the [{#T}](#get-entry) method.