리더보드

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

아래 요청이 작동하려면 다음 사항을 확인하세요.

SDK를 활성화 및 구성했으며 해당 개체를 ysdk 변수를 통해 사용할 수 있어야 합니다.
개발자 대시보드에서 리더보드를 생성했습니다.

알림

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

초기화

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

제한

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

이전 방식

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()

리더보드 설명

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

getDescription(
  leaderboardName: string
)

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

요청 예시

샘플 ES2017 비동기/대기 요청

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

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

work();

응답 형식

{
  appID: string,
  dеfault: boolean,
  description: {
    invert_sort_order: boolean,
    score_format: {
      options: {
        decimal_offset: integer
      },
      type: string
    }
  },
  name: string,
  title: {
    en: string,
    ru: string
  }
}

파라미터	설명
`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`.

새 점수

알림

인증된 사용자만이 요청할 수 있습니다. 필요한 경우 인증을 사용하십시오.

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

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

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

setScore(
  leaderboardName: string,
  score: number,
  extraData?: string
)

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

참고

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

요청 예시

샘플 ES2017 비동기/대기 요청

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

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

work();

순위 가져오기

알림

인증된 사용자만 요청이 가능합니다. 필요한 경우 인증을 하십시오.

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

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

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

getPlayerEntry(
  leaderboardName: string
)

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

참고

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

요청 예시

샘플 ES2017 비동기/대기 요청

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

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

work();

응답 형식

{
  score: integer,
  extraData: string,
  rank: integer,
  player: {
    getAvatarSrc: (size: string) => string,
    getAvatarSrcSet: (size: string) => string,
    lang: string,
    publicName: string,
    scopePermissions: {
      avatar: string,
      public_name: string
    },
    uniqueID: string,
  },
  formattedScore: string
}

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

리더보드 항목

사용자 순위를 표시하려면 ysdk.leaderboards.getEntries()를 사용합니다:

getEntries(
  leaderboardName: string,
  {
    includeUser: boolean,
    quantityAround: integer,
    quantityTop: integer
  }
)

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

참고

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

요청 예시

샘플 ES2017 비동기/대기 요청

// 모든 기본값 사용
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));

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();

응답 형식

{
  leaderboard: {
    ...
  },
  ranges: [
    {
      start: integer,
      size: integer
    }
  ],
  userRank: integer,
  entries: [
    {
      score: integer,
      extraData: string,
      rank: integer,
      player: {
        getAvatarSrc: (size: string) => string,
        getAvatarSrcSet: (size: string) => string,
        lang: string,
        publicName: string,
        scopePermissions: {
          avatar: string,
          public_name: string
        },
        uniqueID: string,
      },
    formattedScore: string
    },
    ...
  ]
}

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

메소드 제한

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

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

리더보드 관련 문제

팁

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

객체가 이미 존재함

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

사용자 숨김

"사용자가 숨겨짐"이라는 문구는 플레이어가 자신의 아바타와 이름 사용을 허용하지 않은 경우 표시됩니다. 사용자 데이터에 대한 접근 권한은 프로필 설정에 따라 달라집니다. 자세한 내용은 플레이어 데이터 섹션을 참조하세요.

오류 404

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

참고

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

지원 서비스는 얀덱스 게임에서 완성 된 게임을 게시 할 수 있습니다. 개발 또는 테스트에 대한 질문이 있는 경우

Yandex Games SDK 사용과 관련하여 문제가 발생하거나 질문이 있는 경우 다음 방법으로 지원팀에 문의하세요.

채팅 상담

Was the article helpful?

게임 내 구매

비동기 멀티플레이어