---
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: ko/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/ko/llms.txt

# 리더보드

게임 페이지에 상위 플레이어의 결과와 로그인한 사용자의 순위 내 위치를 보여주는 맞춤형 리더보드를 표시할 수 있습니다.

아래 요청이 작동하려면 다음 사항을 확인하세요.
* [SDK를 활성화 및 구성](https://yandex.com/dev/games/doc/ko/sdk/sdk-about.md#use)했으며 해당 개체를 `ysdk` 변수를 통해 사용할 수 있어야 합니다.
* 개발자 대시보드에서 리더보드를 [생성](https://yandex.com/dev/games/doc/ko/concepts/leaderboards.md)했습니다.

{% note alert "알림" %}

개발자 대시보드의 **기술 리더보드 이름** 필드에 해당 이름이 있는 리더보드가 없는 경우 요청은 404 오류를 반환합니다.

{% endnote %}



## 초기화 {#init}

리더보드 메서드를 직접 호출하려면 `ysdk.leaderboards`를 사용하세요.

{% note alert "제한" %}

`ysdk.getLeaderboards()` 메서드를 사용해 `lb` 객체를 초기화하는 방식은 더 이상 사용되지 않습니다.

{% cut "이전 방식" %}

```javascript
var lb;

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

  // 리더보드 메서드 (구 방식 호출 시):
  // lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
  // lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
  // lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
  // lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()
```

{% endcut %}

{% endnote %}



## 리더보드 설명 {#description}

이름별로 리더보드에 대한 설명을 가져오려면 `ysdk.leaderboards.getDescription()`을 사용합니다.

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

<div class="table-25">

#|
|| **파라미터** | **설명** ||
|| `leaderboardName` | 리더보드 이름. ||
|#

</div>


{% list tabs %}

* 요청 예시

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

* 샘플 ES2017 비동기/대기 요청

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

    work();
    ```

{% endlist %}

#### 응답 형식

```javascript
{
  [appID](*key_appID): string,
  [dеfault](*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">

#|
|| **파라미터** | **설명** ||
|| `appID` | 앱 ID. ||
|| `default` | `true`이면 기본 리더보드입니다. ||
|| `invert_sort_order` | 정렬 순서:
* `false`: 순위가 내림차순으로 정렬됩니다.
* `true`: 순위가 오름차순으로 정렬됩니다. ||
|| `decimal_offset` | 점수 오프셋. 예를 들어, `decimal_offset: 2`인 경우 1234는 12.34로 표시됩니다. ||
|| `type` | 리더보드 결과 유형. 사용 가능한 파라미터: `numeric`(숫자), `time`(초). ||
|| `name` | 리더보드 이름. ||
|| `title` | 현지화된 이름. 법적 배열 파라미터: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`. ||
|#

</div>



## 새 점수 {#set-score}

{% note alert "알림" %}

인증된 사용자만이 요청할 수 있습니다. 필요한 경우 [인증](https://yandex.com/dev/games/doc/ko/sdk/sdk-player.md#auth)을 사용하십시오.

사용자에 대한 메서드의 가용성을 확인하려면 `ysdk.isAvailableMethod('leaderboards.setScore')` 메서드를 사용할 수 있습니다. 이는 `Promise<Boolean>`을 반환하며 논리값은 해당 메서드의 가용성을 나타냅니다.

모든 사용자에 대한 결과를 인증 여부에 상관없이 저장하려면 응용프로그램 코드에서 사용자 지정 리더보드를 직접 정의하는 것이 좋습니다. 기술 선택에 제한이 없습니다.

{% endnote %}

플레이어의 점수를 새로 설정하려면 `ysdk.leaderboards.setScore()`를 사용합니다:

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

<div class="table-25">

#|
|| **파라미터** | **설명** ||
|| `leaderboardName` | 리더보드 이름. ||
|| `score` | 점수. `integer` 타입만 허용됩니다. 0보다 커야 합니다. [리더보드 유형](*leaderboardtype)이 `time`인 경우 값을 밀리초 단위로 전달해야 합니다. ||
|| `extraData` | 사용자 설명. 선택 사항입니다. ||
|#

</div>

{% note info "참고" %}

요청은 초당 한 번 이상 전송할 수 없습니다. 그렇지 않으면 오류와 함께 요청이 거부됩니다.

{% endnote %}


{% list tabs %}

* 요청 예시

    ```javascript
    // extraData 없이
    ysdk.leaderboards.setScore('leaderboard2021', 120);
    // extraData 포함
    ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
    ```

* 샘플 ES2017 비동기/대기 요청

    ```javascript
    const work = async () => {
      // extraData 없이
      await ysdk.leaderboards.setScore('leaderboard2021', 120);
      // extraData 사용
      await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
    }

    work();
    ```

{% endlist %}



## 순위 가져오기 {#get-entry}

{% note alert "알림" %}

인증된 사용자만 요청이 가능합니다. 필요한 경우 [인증](https://yandex.com/dev/games/doc/ko/sdk/sdk-player.md#auth)을 하십시오.

사용자의 메소드 가용성을 확인하려면 `ysdk.isAvailableMethod('leaderboards.getPlayerEntry')` 메소드를 사용할 수 있습니다. 이 메소드는 `Promise<Boolean>`을 반환하며, 논리값은 메소드의 가용성을 나타냅니다.

인증 여부와 관계 없이 모든 사용자의 결과를 저장하려면 앱 코드에 사용자 정의 리더보드를 직접 작성하는 것이 좋습니다. 기술 선택에 제한이 없습니다.

{% endnote %}


사용자의 순위를 가져오려면 `ysdk.leaderboards.getPlayerEntry()`를 사용합니다.

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

<div class="table-25">

#|
|| **파라미터** | **설명** ||
|| `leaderboardName` | 리더보드 이름. ||
|#

</div>

{% note info "참고" %}

1분당 60회 이상의 요청을 보내지 마십시오. 그렇지 않으면 오류로 거부됩니다.

{% endnote %}


{% list tabs %}

* 요청 예시

    ```javascript
    ysdk.leaderboards.getPlayerEntry('leaderboard2021')
      .then(res => console.log(res))
      .catch(err => {
        if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
          // 리더보드에 해당 플레이어의 항목이 없는 경우 트리거됩니다.
        }
      });
    ```

* 샘플 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') {
          // 리더보드에 해당 플레이어의 항목이 없는 경우 트리거됩니다.
        }
      }
    }

    work();
    ```

{% endlist %}

#### 응답 형식

```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">

#|
|| **파라미터** | **설명** ||
|| `score` | 점수. `integer` 타입만 허용됩니다. 0보다 커야 합니다. [리더보드 유형](*leaderboardtype)이 `time`인 경우 값을 밀리초 단위로 전달해야 합니다. ||
|| `extraData` | 사용자 설명. 선택 사항입니다. ||
|| `getAvatarSrc` | 사용자 사진의 URL을 반환합니다. `size`에 사용 가능한 값은 다음과 같습니다. `small`, `medium`, `large`. ||
|| `getAvatarSrcSet` | Retina 디스플레이에 적합한 사용자 사진의 srcset을 반환합니다. `size`에 사용 가능한 값은 다음과 같습니다. `small`, `medium`, `large`. ||
|#

</div>



## 리더보드 항목 {#get-entries}

사용자 순위를 표시하려면 `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">

#|
|| **파라미터** | **설명** ||
|| `leaderboardName` | 리더보드 이름. ||
|| `includeUser` | 로그인한 사용자를 응답에 포함할지 여부를 정의합니다.
* `true`: 응답에 포함합니다.
* `false`(기본값): 포함하지 않습니다. ||
|| `quantityAround` | 리더보드에서 사용자 아래 및 위에 반환할 항목 수입니다. 최소값은 1, 최대값은 10입니다. 기본값은 5입니다. ||
|| `quantityTop` | 리더보드 상단의 항목 수입니다. 최소값은 1, 최대값은 20입니다. 기본값은 5입니다. ||
|#

</div>

{% note info "참고" %}

1분당 60회 이상의 요청을 보내지 마십시오. 그렇지 않으면 오류로 거부됩니다.

{% endnote %}


{% list tabs %}

* 요청 예시

    ```javascript
    // 모든 기본값 사용
    ysdk.leaderboards.getEntries('leaderboard2021')
      .then(res => console.log(res));
    // 상위 10개 반환
    ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 })
      .then(res => console.log(res));
    // 상위 10개 항목과 사용자 양쪽의 3개 항목 반환하기
    ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
      .then(res => console.log(res));
    ```

* 샘플 ES2017 비동기/대기 요청

    ```javascript
    const work = async () => {
      let res;
      // 모든 기본값 사용
      res = await ysdk.leaderboards.getEntries('leaderboard2021');
      console.log(res);
      // 상위 10개 가져오기
      res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10 });
      console.log(res);
      // 상위 10개 항목과 사용자 양쪽의 3개 항목 반환하기
      res = await ysdk.leaderboards.getEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 });
      console.log(res);
    }

    work();
    ```

{% endlist %}

#### 응답 형식

```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">

#|
|| **파라미터** | **설명** ||
|| `leaderboard` | [리더보드 설명](#description). ||
|| `ranges` | 응답의 순위 범위. ||
|| `start` | 순위 내 위치. 카운트는 0부터 시작하므로 1위는 0번째 요소로 간주됩니다. ||
|| `size` | 요청된 항목 수입니다. 데이터가 충분하지 않으면 반환되는 숫자가 요청된 숫자가 아닐 수 있습니다. ||
|| `userRank` | 사용자의 순위. 없는 경우 또는 사용자를 포함하지 않고 테이블의 맨 위에 대한 요청인 경우 0을 반환합니다. ||
|| `entries` | 요청된 항목. ||
|| `score` | 점수. `integer` 타입만 허용됩니다. 0보다 커야 합니다. [리더보드 유형](*leaderboardtype)이 `time`인 경우 값을 밀리초 단위로 전달해야 합니다. ||
|| `extraData` | 사용자 설명. 선택 사항입니다. ||
|| `getAvatarSrc` | 사용자 사진의 URL을 반환합니다. `size`에 사용 가능한 값은 다음과 같습니다. `small`, `medium`, `large`. ||
|| `getAvatarSrcSet` | Retina 디스플레이에 적합한 사용자 사진의 srcset을 반환합니다. `size`에 사용 가능한 값은 다음과 같습니다. `small`, `medium`, `large`. ||
|#

</div>



## 메소드 제한 {#limits}

<div class="table-25">

#|
|| **메소드** | **설명** | **제한** | **사용자 인증** ||
|| `ysdk.leaderboards.setScore()` | [플레이어의 새로운 점수 설정](#set-score) | 초당 1 요청 | 필수 ||
|| `ysdk.leaderboards.getPlayerEntry()` | [단일 사용자의 순위 표시](#get-entry) | 5분마다 60 요청 | 필수 ||
|| `ysdk.leaderboards.getEntries()` | [여러 사용자의 순위 가져오기](#get-entries) | 5분마다 20 요청 | 선택 ||
|#

</div>

기타 요청 제한: 5분당 20 요청.



## 리더보드 관련 문제 {#problems}

{% note tip "팁" %}

`ysdk.isAvailableMethod()`와 `ysdk.leaderboards.setScore()` 메소드를 함께 사용할 때, 비인가된 사용자는 리더보드에 표시되지 않고 진행 상황을 확인할 수 없습니다. 모든 사용자의 결과를 저장하고 이를 모든 사용자에게 표시하는 사용자 지정 리더보드를 만드는 것이 좋습니다. 응용 프로그램 코드에서 직접 사용자 지정 리더보드를 만들고 기술 선택에 제한이 없습니다.

{% endnote %}

### 객체가 이미 존재함 {#object-already-exists}

기존 이름으로 새 리더보드를 만들려고 할 때 발생하는 오류입니다. 이전에 사용되지 않았던 이름을 입력하십시오.

### 사용자 숨김 {#player-hidden}

"사용자가 숨겨짐"이라는 문구는 플레이어가 자신의 아바타와 이름 사용을 허용하지 않은 경우 표시됩니다. 사용자 데이터에 대한 접근 권한은 [프로필](https://yandex.com/games/user) 설정에 따라 달라집니다. 자세한 내용은 [플레이어 데이터](https://yandex.com/dev/games/doc/ko/sdk/sdk-player.md#getplayer) 섹션을 참조하세요.

### 오류 404 {#leaderboard-404}

리더보드의 SDK 메소드를 호출할 때 404 오류가 발생하면, 개발자 콘솔에서 필드 **Technical leaderboard name**에 해당 이름을 가진 리더보드가 생성되었는지 확인하십시오.

---

<!-- source: ko/_includes/concepts/troubleshooting/id-troubleshooting/support.md -->
{% note info "참고" %}

지원팀은 완성된 게임을 Yandex Games에 게시하는 데 도움을 드릴 수 있습니다. 개발이나 테스트에 대해 궁금한 점이 있다면, [Discord 채널](https://discord.com/invite/wU4p3whr4T)에서 질문해 주세요.

{% endnote %}


지원 서비스는 얀덱스 게임에서 완성 된 게임을 게시 할 수 있습니다. 개발 또는 테스트에 대한 질문이 있는 경우
<!-- endsource: ko/_includes/concepts/troubleshooting/id-troubleshooting/support.md -->

<!-- source: ko/_includes/button-fos.md -->
Yandex Games SDK 사용과 관련하여 문제가 발생하거나 질문이 있는 경우 다음 방법으로 지원팀에 문의하세요.


<a href="https://yandex.com/chat/#/user/a4fa5c06-75db-9b38-6eea-b1673785f7d5">
  <span class="button">채팅 상담</span>
</a>
<!-- endsource: ko/_includes/button-fos.md -->

[*key_appID]: 애플리케이션 ID.

[*key_default]: `true`이면 기본 리더보드입니다.

[*key_invert_sort_order]: 정렬 순서:
* `false`: 순위가 내림차순으로 정렬됩니다.
* `true`: 순위가 오름차순으로 정렬됩니다.

[*key_decimal_offset]: 점수 오프셋.
예를 들어, `decimal_offset: 2`인 경우 1234는 12.34로 표시됩니다.

[*key_type]: 리더보드 결과 유형. 사용 가능한 파라미터: `numeric`(숫자), `time`(초).

[*key_title]: 현지화된 이름. 법적 배열 파라미터: `ru`, `en`, `be`, `uk`, `kk`, `uz`, `tr`.

[*key_score]: 점수. `integer` 타입만 허용됩니다. 0보다 커야 합니다. 리더보드 유형이 `time`인 경우 값을 밀리초 단위로 전달해야 합니다.

[*key_extraData]: 사용자 설명. 선택 사항입니다.

[*leaderboardtype]: 리더보드 결과 유형. 사용 가능한 파라미터: `numeric`(숫자), `time`(초).

[*key_getAvatarSrc]: 사용자 사진의 URL을 반환합니다. `size`에 사용 가능한 값은 다음과 같습니다. `small`, `medium`, `large`.

[*key_getAvatarSrcSet]: Retina 디스플레이에 적합한 사용자 사진의 srcset을 반환합니다. `size`에 사용 가능한 값은 다음과 같습니다. `small`, `medium`, `large`.

[*key_includeUser]: 로그인한 사용자를 응답에 포함할지 여부를 정의합니다.
* `true`: 응답에 포함합니다.
* `false`(기본값): 포함하지 않습니다.

[*key_quantityAround]: 리더보드에서 사용자 아래 및 위에 반환할 항목 수입니다. 최소값은 1입니다. 최대값은 10입니다. 기본값은 5입니다.

[*key_quantityTop]: 리더보드 상단의 항목 수입니다. 최소값은 1, 최대값은 20입니다. 기본값은 5입니다.

[*key_leaderboard]: [리더보드 설명.](#description)

[*key_ranges]: 응답의 순위 범위.

[*key_start]: 순위 내 위치. 카운트는 0부터 시작하므로 1위는 0번째 요소로 간주됩니다.

[*key_size]: 요청된 항목 수입니다. 데이터가 충분하지 않으면 반환되는 숫자가 요청된 숫자가 아닐 수 있습니다.

[*key_userRank]: 사용자의 순위. 없는 경우 또는 사용자를 포함하지 않고 테이블의 맨 위에 대한 요청인 경우 0을 반환합니다.

[*key_entries]: 요청된 항목.

[*key_name]: 리더보드 이름.