---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.4
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: vi/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/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 %}



## Khởi tạo {#init}

Để gọi các phương thức bảng xếp hạng trực tiếp, hãy truy cập `ysdk.leaderboards`.

{% note alert "Hạn chế" %}

Việc khởi tạo đối tượng `lb` bằng phương thức `ysdk.getLeaderboards()` đã lỗi thời.

{% cut "Các phương thức cũ" %}

```javascript
var lb;

ysdk.getLeaderboards()
  .then(_lb => lb = _lb);

  // Các phương thức bảng xếp hạng khi gọi qua cách cũ:
  // lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
  // lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
  // lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
  // lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()
```

{% endcut %}

{% endnote %}



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

Để 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.getDescription()`:

```javascript
getDescription(
  [leaderboardName](*key_name): string
)
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `leaderboardName` | Tên bảng xếp hạng. ||
|#

</div>


{% list tabs %}

* Yêu cầu mẫu

    ```javascript
    ysdk.leaderboards.getDescription('leaderboard2021')
      .then(res => console.log(res));
    ```

* Mẫu yêu cầu async/await ES2017

    ```javascript
    const work = async () => {
      const res = await ysdk.leaderboards.getDescription('leaderboard2021');
      console.log(res);
    }

    work();
    ```

{% endlist %}

#### Định dạng phản hồi

```javascript
{
  [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): integer
      },
      [type](*key_type): string
    }
  },
  [name](*key_name): string,
  [title](*key_title): {
    en: string,
    ru: string
  }
}
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `appID` | ID ứng dụng. ||
|| `default` | Nếu là `true`, thì đó là bảng xếp hạng chính. ||
|| `invert_sort_order` | Thứ tự sắp xếp:
* `false`: Các vị trí được sắp xếp theo thứ tự giảm dần.
* `true`: Các vị trí được sắp xếp theo thứ tự tăng dần. ||
|| `decimal_offset` | Độ dịch chuyển điểm. Ví dụ: với `decimal_offset: 2`, số 1234 sẽ được hiển thị là 12,34. ||
|| `type` | Loại kết quả trên bảng xếp hạng. Các tham số được chấp nhận: `numeric` (số), `time` (tính bằng giây). ||
|| `name` | Tên bảng xếp hạng. ||
|| `title` | Tên bản địa hóa. Các tham số mảng có thể: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`. ||
|#

</div>



## Điểm số mới {#set-score}

{% 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).

Để kiểm tra xem phương thức này có dùng được cho người dùng hay không, bạn có thể sử dụng phương thức `ysdk.isAvailableMethod('leaderboards.setScore')`. Phương thức này trả về `Promise<Boolean>`, trong đó giá trị boolean cho biết liệu phương thức có dùng được hay không.

Nếu bạn muốn lưu kết quả cho tất cả người dùng bất kể trạng thái đăng nhập của họ, bạn nên thêm bảng xếp hạng tùy chỉnh theo cách thủ công trong mã nguồn ứng dụng của mình. Bạn có thể tự do lựa chọn bất kỳ công nghệ nào cho mục đích này.

{% 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.setScore()`.

```javascript
setScore(
  [leaderboardName](*key_name): string,
  [score](*key_score): number,
  [extraData](*key_extraData)?: string
)
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `leaderboardName` | Tên bảng xếp hạng. ||
|| `score` | Điểm số. Chỉ chấp nhận loại dữ liệu `integer`. Giá trị không âm, có giá trị tối đa chỉ bị giới hạn bởi logic JavaScript. Nếu [loại bảng xếp hạng](*leaderboardtype) là `time`, các giá trị phải được truyền vào theo đơn vị mili giây. ||
|| `extraData` | Mô tả người dùng. Tham số tùy chọn. ||
|#

</div>

{% 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 %}


{% list tabs %}

* Yêu cầu mẫu

    ```javascript
    // Không có extraData.
    ysdk.leaderboards.setScore('leaderboard2021', 120);
    // Có extraData.
    ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
    ```

* Mẫu yêu cầu async/await ES2017

    ```javascript
    const work = async () => {
      // Không có extraData.
      await ysdk.leaderboards.setScore('leaderboard2021', 120);
      // Có extraData.
      await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
    }

    work();
    ```

{% endlist %}



## Nhận xếp hạng {#get-entry}

{% 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).

Để kiểm tra xem phương thức có dùng được cho người dùng hay không, bạn có thể sử dụng phương thức `ysdk.isAvailableMethod('leaderboards.getPlayerEntry')`. Phương thức này trả về `Promise<Boolean>`, trong đó giá trị boolean cho biết liệu phương thức có dùng được hay không.

Nếu bạn muốn lưu kết quả cho tất cả người dùng bất kể trạng thái đăng nhập của họ, bạn nên thêm bảng xếp hạng tùy chỉnh theo cách thủ công trong mã nguồn ứng dụng của mình. Bạn có thể tự do lựa chọn bất kỳ công nghệ nào cho mục đích này.

{% endnote %}

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

```javascript
getPlayerEntry(
  [leaderboardName](*key_name): string
)
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `leaderboardName` | Tên bảng xếp hạng. ||
|#

</div>

{% note info "Ghi chú" %}

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

{% endnote %}


{% list tabs %}

* Yêu cầu mẫu

    ```javascript
    ysdk.leaderboards.getPlayerEntry('leaderboard2021')
      .then(res => console.log(res))
      .catch(err => {
        if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
          // Lỗi này được trả về nếu bảng xếp hạng không có mục nhập cho người chơi.
        }
      });
    ```

* Mẫu yêu cầu async/await ES2017

    ```javascript
    const work = async () => {
      try {
        const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
        console.log(res);
      } catch (err) {
        if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
          // Lỗi này được trả về nếu bảng xếp hạng không có mục nhập cho người chơi.
        }
      }
    }

    work();
    ```

{% endlist %}

#### Định dạng phản hồi

```javascript
{
  [score](*key_score): integer,
  [extraData](*key_extraData): string,
  rank: integer,
  player: {
    [getAvatarSrc](*key_getAvatarSrc): (size: string) => string,
    [getAvatarSrcSet](*key_getAvatarSrcSet): (size: string) => string,
    lang: string,
    publicName: string,
    scopePermissions: {
      avatar: string,
      public_name: string
    },
    uniqueID: string,
  },
  formattedScore: string
}
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `score` | Điểm số. Chỉ chấp nhận loại dữ liệu `integer`. Giá trị không âm, có giá trị tối đa chỉ bị giới hạn bởi logic JavaScript. Nếu [loại bảng xếp hạng](*leaderboardtype) là `time`, các giá trị phải được truyền vào theo đơn vị mili giây. ||
|| `extraData` | Mô tả người dùng. Tham số tùy chọn. ||
|| `getAvatarSrc` | Trả về URL của ảnh người dùng. Các giá trị `size` được chấp nhận: `small`, `medium` và `large`. ||
|| `getAvatarSrcSet` | Trả về srcset ảnh của người dùng phù hợp với màn hình Retina. Các giá trị `size` được chấp nhận: `small`, `medium` và `large`. ||
|#

</div>



## Mục nhập bảng xếp hạng {#get-entries}

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

```javascript
getEntries(
  [leaderboardName](*key_name): string,
  {
    [includeUser](*key_includeUser): boolean,
    [quantityAround](*key_quantityAround): integer,
    [quantityTop](*key_quantityTop): integer
  }
)
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `leaderboardName` | Tên bảng xếp hạng. ||
|| `includeUser` | Xác định xem có bao gồm người dùng đã đăng nhập trong phản hồi hay không:
* `true`: Bao gồm trong phản hồi.
* `false` (giá trị mặc định): Không bao gồm. ||
|| `quantityAround` | Số lượng mục nhập cần trả về bên dưới và bên trên người dùng trong bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 10. Giá trị trả về mặc định là 5. ||
|| `quantityTop` | Số lượng mục nhập từ đầu bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 20. Giá trị trả về mặc định là 5. ||
|#

</div>

{% note info "Ghi chú" %}

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

{% endnote %}


{% list tabs %}

* Yêu cầu mẫu

    ```javascript
    // Sử dụng tất cả các giá trị mặc định.
    ysdk.leaderboards.getEntries('leaderboard2021')
      .then(res => console.log(res));
    // Yêu cầu 10 mục nhập hàng đầu.
    ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 })
      .then(res => console.log(res));
    // Yêu cầu 10 mục nhập hàng đầu và 3 mục nhập bên trên và bên dưới mục nhập của người dùng.
    ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
      .then(res => console.log(res));
    ```

* Mẫu yêu cầu async/await ES2017

    ```javascript
    const work = async () => {
      let res;
      // Sử dụng tất cả các giá trị mặc định.
      res = await ysdk.leaderboards.getEntries('leaderboard2021');
      console.log(res);
      // Yêu cầu 10 mục nhập hàng đầu.
      res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 });
      console.log(res);
      // Yêu cầu 10 mục nhập hàng đầu và 3 mục nhập bên trên và bên dưới mục nhập của người dùng.
      res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 });
      console.log(res);
    }

    work();
    ```

{% endlist %}

#### Định dạng phản hồi

```javascript
{
  [leaderboard](*key_leaderboard): {
    ...
  },
  [ranges](*key_ranges): [
    {
      [start](*key_start): integer,
      [size](*key_size): integer
    }
  ],
  [userRank](*key_userRank): integer,
  [entries](*key_entries): [
    {
      [score](*key_score): integer,
      [extraData](*key_extraData): string,
      rank: integer,
      player: {
        [getAvatarSrc](*key_getAvatarSrc): (size: string) => string,
        [getAvatarSrcSet](*key_getAvatarSrcSet): (size: string) => string,
        lang: string,
        publicName: string,
        scopePermissions: {
          avatar: string,
          public_name: string
        },
        uniqueID: string,
      },
    formattedScore: string
    },
    ...
  ]
}
```

<div class="table-25">

#|
|| **Tham số** | **Mô tả** ||
|| `leaderboard` | [Mô tả bảng xếp hạng](#description). ||
|| `ranges` | Khoảng xếp hạng trong phản hồi. ||
|| `start` | Vị trí trong bảng xếp hạng. Đánh số bắt đầu từ số không, vì vậy phần tử thứ 0 là vị trí đầu tiên. ||
|| `size` | Số lượng mục nhập được yêu cầu. Nếu không có đủ dữ liệu, số được trả về có thể không phải là số được yêu cầu. ||
|| `userRank` | Xếp hạng của người dùng. Trả về 0 nếu điểm số của người dùng không có trong bảng xếp hạng hoặc nếu yêu cầu dành cho các xếp hạng hàng đầu trong đó không có người dùng. ||
|| `entries` | Các mục nhập được yêu cầu. ||
|| `score` | Điểm số. Chỉ chấp nhận loại dữ liệu `integer`. Giá trị không âm, có giá trị tối đa chỉ bị giới hạn bởi logic JavaScript. Nếu [loại bảng xếp hạng](*leaderboardtype) là `time`, các giá trị phải được truyền vào theo đơn vị mili giây. ||
|| `extraData` | Mô tả người dùng. Tham số tùy chọn. ||
|| `getAvatarSrc` | Trả về URL của ảnh người dùng. Các giá trị `size` được chấp nhận: `small`, `medium` và `large`. ||
|| `getAvatarSrcSet` | Trả về srcset ảnh của người dùng phù hợp với màn hình Retina. Các giá trị `size` được chấp nhận: `small`, `medium` và `large`. ||
|#

</div>



## Giới hạn yêu cầu phương thức {#limits}

<div class="table-25">

#|
|| **Phương thức** | **Mô tả** | **Giới hạn** | **Đăng nhập của người dùng** ||
|| `ysdk.leaderboards.setScore()` | [Thiết lập điểm số mới cho người chơi](#set-score) | 60 yêu cầu mỗi phút | Bắt buộc ||
|| `ysdk.leaderboards.getPlayerEntry()` | [Trả về vị trí xếp hạng trên bảng xếp hạng cho một người dùng](#get-entry) | 60 yêu cầu trong năm phút | Bắt buộc ||
|| `ysdk.leaderboards.getEntries()` | [Trả về các vị trí xếp hạng trên bảng xếp hạng cho nhiều người dùng](#get-entries) | 20 yêu cầu trong năm phút | Tùy chọn ||
|#

</div>

Giới hạn cho các yêu cầu khác là 20 yêu cầu trong năm phút.



## Các vấn đề đã biết {#problems}

{% note tip "Lời khuyên" %}

Khi sử dụng các phương thức `ysdk.isAvailableMethod()` và `ysdk.leaderboards.setScore()` cùng nhau, người dùng đã đăng xuất không xuất hiện trên bảng xếp hạng và không thể thấy tiến trình của họ. Bạn có thể tạo một bảng xếp hạng khác có điểm số của tất cả người dùng và hiển thị bảng xếp hạng này cho mọi người. Bạn có thể tạo bảng xếp hạng tùy chỉnh trong mã nguồn ứng dụng bằng bất kỳ công nghệ nào bạn thích.

{% endnote %}

### Đối tượng đã tồn tại {#object-already-exists}

Xảy ra lỗi khi tìm cách tạo bảng xếp hạng mới có tên của một bảng xếp hạng cũ. Để tránh vấn đề này, hãy nhập tên bạn chưa sử dụng trước đây.

### Người dùng bị ẩn {#player-hidden}

Dòng chữ "Người dùng ẩn danh" hiển thị khi người chơi không cho phép sử dụng avatar và tên của họ. Quyền truy cập vào dữ liệu người dùng phụ thuộc vào cài đặt trong [hồ sơ](https://yandex.com/games/user) của họ. Xem thêm chi tiết trong phần [Dữ liệu người chơi](https://yandex.com/dev/games/doc/vi/sdk/sdk-player.md#getplayer).

### Lỗi 404 {#leaderboard-404}

Nếu gặp lỗi 404 khi cố gắng gọi các phương thức SDK cho bảng xếp hạng, hãy kiểm tra xem đã tạo bảng xếp hạng với tên tương ứng trong trường **Technical leaderboard name** trong console của nhà phát triển.



---

<!-- source: vi/_includes/concepts/troubleshooting/id-troubleshooting/support.md -->
{% note info "Ghi chú" %}

Nhân viên hỗ trợ sẽ giúp bạn đăng bài trò chơi đã hoàn thiện lên nền tảng trò chơi của Yandex. Để đặt các câu hỏi về việc phát triển và kiểm thử, các nhà phát triển khác sẽ trả lời chuyên sâu trong [Kênh Discord](https://discord.com/invite/wU4p3whr4T).

{% endnote %}
<!-- endsource: vi/_includes/concepts/troubleshooting/id-troubleshooting/support.md -->

<!-- source: vi/_includes/button-fos.md -->
Nếu bạn đang gặp phải vấn đề hoặc có câu hỏi liên quan đến việc sử dụng Yandex Games SDK, vui lòng liên hệ với bộ phận hỗ trợ:


<a href="https://yandex.com/chat/#/user/a4fa5c06-75db-9b38-6eea-b1673785f7d5">
  <span class="button">Viết trong mục trò chuyện</span>
</a>
<!-- endsource: vi/_includes/button-fos.md -->

[*key_name]: Tên bảng xếp hạng.

[*key_appID]: ID ứng dụng.

[*key_default]: Nếu là `true`, thì đó là bảng xếp hạng chính.

[*key_invert_sort_order]: Thứ tự sắp xếp:
* `false`: Điểm số được sắp xếp theo thứ tự giảm dần.
* `true`: Điểm số được sắp xếp theo thứ tự tăng dần.

[*key_decimal_offset]: Độ dịch chuyển điểm.
  Ví dụ: với `decimal_offset: 2`, số 1234 sẽ được hiển thị là 12,34.

[*key_type]: Loại kết quả trên bảng xếp hạng. Các tham số được chấp nhận: `numeric` (số), `time` (tính bằng giây).

[*key_title]: Tên bản địa hóa. Các tham số mảng có thể: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`.

[*key_score]: Điểm số. Chỉ chấp nhận loại dữ liệu `integer`. Số nguyên không được phép là số âm. Nếu loại bảng xếp hạng là `time`, các giá trị phải được truyền vào theo đơn vị mili giây.

[*leaderboardtype]: Loại kết quả trên bảng xếp hạng. Các tham số được chấp nhận: `numeric` (số), `time` (tính bằng giây).

[*key_extraData]: Mô tả người dùng. Tham số tùy chọn.

[*key_getAvatarSrc]: Trả về URL của ảnh người dùng. Các giá trị `size` được chấp nhận: `small`, `medium` và `large`.

[*key_getAvatarSrcSet]: Trả về srcset ảnh của người dùng phù hợp với màn hình Retina. Các giá trị `size` được chấp nhận: `small`, `medium` và `large`.

[*key_includeUser]: Xác định xem có bao gồm người dùng đã đăng nhập trong phản hồi hay không:
* `true`: Bao gồm trong phản hồi.
* `false` (giá trị mặc định): Không bao gồm.

[*key_quantityAround]: Số lượng mục nhập cần trả về bên dưới và bên trên người dùng trong bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 10. Giá trị trả về mặc định là 5.

[*key_quantityTop]: Số lượng mục nhập từ đầu bảng xếp hạng. Giá trị tối thiểu là 1. Giá trị tối đa là 20. Giá trị trả về mặc định là 5.

[*key_leaderboard]: [Mô tả bảng xếp hạng.](#description)

[*key_ranges]: Khoảng xếp hạng trong phản hồi.

[*key_start]: Vị trí trong bảng xếp hạng. Đánh số bắt đầu từ số không, vì vậy phần tử thứ 0 là vị trí đầu tiên.

[*key_size]: Số lượng mục nhập được yêu cầu. Nếu không có đủ dữ liệu, số được trả về có thể không phải là số được yêu cầu.

[*key_userRank]: Xếp hạng của người dùng. Trả về 0 nếu điểm số của người dùng không có trong bảng xếp hạng hoặc nếu yêu cầu dành cho các xếp hạng hàng đầu trong đó không có người dùng.

[*key_entries]: Các mục nhập được yêu cầu.