---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.4
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/hi/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/ko/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/ru/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/tr/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/vi/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/zh/sdk/construct-3/leaderboards.md
  - href: en/sdk/construct-3/leaderboards.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

<!-- source: en/_includes/script-common.md -->
<!-- source: en/_includes/script/index-js.md -->

<!-- endsource: en/_includes/script/index-js.md -->

<!-- source: en/_includes/script/requirements-js.md -->

<!-- endsource: en/_includes/script/requirements-js.md -->

<!-- source: en/_includes/script/image-modal-js.md -->

<!-- endsource: en/_includes/script/image-modal-js.md -->
<!-- endsource: en/_includes/script-common.md -->

You can display personalized leaderboards on the game page with the best players' results and the authorized user's position in the ranking.

To make the requests described below work, make sure you have created a [leaderboard](https://yandex.com/dev/games/doc/en/sdk/sdk-leaderboard.md) in the Developer Console.



## Submitting a score {#set-score}

{% note info %}

This request is only available to authorized users. It's recommended to use authorization in advance and use leaderboards only if the user has provided personal data.

![](../../_images/construct-3/leaderboards/player-pre-auth.webp)

{% endnote %}

Use the **Set leaderboard score** action to submit a new score to the leaderboard with the following parameters:

#|
|| **Parameter** | **Type** | **Description** ||
|| **Name** | `string` | Technical name of the leaderboard. ||
|| **Score** | `number` | The player's score in the leaderboard. ||
|| **Additional data** | `string` | Optional metadata sent with the score. ||
|#

For example, submitting a score to the leaderboard might look like this:

![](../../_images/construct-3/leaderboards/set-score.webp)

{% note info %}

The request can be sent no more than once per second, otherwise it will be rejected with an error.

It's recommended to use score submission with a [delayed event](https://yandex.com/dev/games/doc/en/sdk/construct-3/throttle-debounce.md).

![](../../_images/construct-3/leaderboards/debounce.webp)

{% endnote %}



## Leaderboard entries {#get-leaderboard}

To start working with the leaderboard, use the **Fetch leaderboard** action together with the trigger conditions **Leaderboard is successfully fetched** and **Failure to fetch leaderboard**. The action and conditions accept the following parameters:

#|
|| **Parameter** | **Type** | **Description** ||
|| **Name** | `string` | Technical name of the leaderboard. ||
|| **Top positions** | `number` | Number of requested entries from the top of the leaderboard. ||
|| **Request player position** | `boolean` | Determines whether the user's position will be requested. ||
|| **Positions around the player's position** | `number` | Number of requested entries below and above the user in the table. ||
|#

The plugin will request leaderboard data through the Yandex Games SDK, after which a cycle will begin on a successful request. This process takes some time.

It's recommended to leave some loading indication on the screen while the process is running.

{% note warning %}

Make sure this cycle is not called constantly. It's recommended to use it inside functions or triggers.

{% endnote %}

![](../../_images/construct-3/leaderboards/request-leaderboard.webp)

Inside the cycle, you will have access to expressions from the **Leaderboards** list.

![](../../_images/construct-3/leaderboards/expressions.webp)


---


<!-- source: en/_includes/button-git.md -->
<a href="https://github.com/yandex-games-plugins/construct3">
  <span class="button">Repository</span>
</a>
<!-- endsource: en/_includes/button-git.md -->