---
metadata:
  - name: generator
    content: Diplodoc Platform v5.55.2
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/hi/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/ko/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/ru/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/tr/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/vi/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/zh/sdk/defold/leaderboard.md
  - href: vi/sdk/defold/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/vi/llms.txt

# Bảng xếp hạng

Bạn có thể hiển thị bảng xếp hạng tùy chỉnh theo cá nhân trên trang trò chơi hiển thị kết quả của những người chơi hàng đầu và vị trí của người dùng trong bảng xếp hạng.

Để các yêu cầu bên dưới hoạt động, hãy đảm bảo rằng:
* Bạn [đã bật và đặt cấu hình SDK](https://yandex.com/dev/games/doc/vi/sdk/sdk-about.md#use)đồng thời đối tượng SDK có sẵn thông qua biến `ysdk`.
* Bạn [đã tạo](https://yandex.com/dev/games/doc/vi/concepts/leaderboards.md) bảng xếp hạng trong Bảng điều khiển trò chơi.

{% note alert "Chú ý" %}

Khi ứng dụng của bạn yêu cầu bảng xếp hạng, hãy đảm bảo rằng tên bảng xếp hạng trong yêu cầu khớp với tên bảng xếp hạng trong **Technical leaderboard name** trong Bảng điều khiển trò chơi. Nếu không, yêu cầu sẽ trả về lỗi 404.

{% endnote %}

## Mô tả bảng xếp hạng

Để nhận mô tả về bảng xếp hạng theo tên, hãy sử dụng phương thức `ysdk.leaderboards.get_description()`:

```lua
ysdk.leaderboards.get_description(
    leaderboard_name: string,
    callback: function
)
```

`callback: function` — bộ xử lý của phương thức được gọi. Có dạng:

```lua
function(self, description: table|nil): nil
```

- `description: table` — mô tả bảng xếp hạng. Bao gồm các thuộc tính:

```lua
description: {
  app_id: string,
  default: boolean,
  invert_sort_order: boolean,
  decimal_offset: integer,
  type: string,
  name: string,
  title: {
    en: string,
    ru: string
  }
}
```

**Ví dụ**

```lua
function display_leaderboard()
  ysdk.leaderboards.get_description("highscores",
    function (self, description)
      if description then
        print(
          description.name,
          description.title.en
        )
    end
  end)
end
```

## Điểm số mới

{% note alert "Chú ý" %}

Yêu cầu chỉ dành cho người dùng được cho phép. Nếu cần, hãy yêu cầu [sự cho phép](https://yandex.com/dev/games/doc/vi/sdk/sdk-player.md#auth).

{% endnote %}

Để thiết lập điểm số mới cho người chơi, hãy sử dụng phương thức `ysdk.leaderboards.set_score()`:

```lua
ysdk.leaderboards.set_score(
    leaderboard_name: string,
    score: integer,
    extraData: string|nil
)
```

{% note info "Ghi chú" %}

Giới hạn số lượng yêu cầu là 60 lần mỗi phút. Nếu không, yêu cầu sẽ bị từ chối cùng với lỗi.

{% endnote %}

## Nhận xếp hạng

{% note alert "Chú ý" %}

Yêu cầu chỉ dành cho người dùng được cho phép. Nếu cần, hãy yêu cầu [sự cho phép](https://yandex.com/dev/games/doc/vi/sdk/sdk-player.md#auth).

{% endnote %}

Để nhận xếp hạng của người dùng, hãy sử dụng phương thức `ysdk.leaderboards.get_player_entry()`:

```lua
ysdk.leaderboards.get_player_entry(
    leaderboard_name: string,
    callback: function
)
```

`callback: function` — trình xử lý của phương thức được gọi. Có dạng:

```lua
function(self, player_entry: table|nil): nil
```

- `player_entry: table` — xếp hạng của người dùng. Bao gồm các thuộc tính:

```lua
player_entry: {
  score: integer,
  extraData: string,
  rank: integer,
  avatar_src: {
    small: string,
    medium: string,
    large: string,
  },
  avatar_srcset: {
    small: string,
    medium: string,
    large: string,
  },
  lang: string,
  public_name: string,
  unique_id: string,
  formatted_score: string
}
```

**Ví dụ**

```lua
function display_high_score()
  ysdk.leaderboards.get_player_entry("highscores",
    function (self, player_entry)
      if player_entry then
        print("highscore: " .. player_entry.score)
      end
    end)
end
```

## Mục nhập bảng xếp hạn

Để hiển thị xếp hạng của người dùng, hãy sử dụng phương thức `ysdk.leaderboards.get_entries()`:

```lua
ysdk.leaderboards.get_entries(
    leaderboardName: string,
    callback: function,
    options: {
        include_user: boolean|nil,
        quantity_around: number|nil,
        quantity_top: number|nil
    }
)
```

`callback: function`— trình xử lý phương thức được gọi. Có dạng:

```lua
function(self, entries: table|nil): nil
```

`entries: table` — bảng xếp hạng người dùng. Bao gồm các thuộc tính:

```lua
entries: {
  leaderboard: {
    ...
  },
  ranges: [
    {
      start: integer,
      size: integer
    }
  ],
  userRank: integer,
  entries: [
    {
      score: integer,
      extraData: string,
      rank: integer,
      avatar_src: {
        small: string,
        medium: string,
        large: string,
      },
      avatar_srcset: {
        small: string,
        medium: string,
        large: string,
      },
      lang: string,
      public_name: string,
      unique_id: string,
      formatted_score: string
    },
    ...
  ]
}
```

---


<!-- source: vi/_includes/button-git-defold.md -->
<a href="https://github.com/yandex-games-plugins/defold">
  <span class="button">Kho lưu trữ</span>
</a>
<!-- endsource: vi/_includes/button-git-defold.md -->