Лидерборды

Вы можете показывать на странице игры персонализированные лидерборды (таблицы лидеров) с результатами лучших игроков и местом в рейтинге авторизованного пользователя.

Чтобы у вас заработали описанные ниже запросы, проверьте, что выполнены условия:

Внимание

Если в Консоли нет лидерборда с соответствующим именем в поле Техническое название лидерборда, запросы будут выдавать ошибку 404.

Инициализация

Для вызова методов лидерборда напрямую обращайтесь к ysdk.leaderboards.

Внимание

Инициализация объекта lb с помощью метода ysdk.getLeaderboards() устарела.

Старые методы
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

Имя лидерборда.

 
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

Идентификатор приложения.

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. Не может быть отрицательным, максимальное значение ограничено только логикой JavaScript. Если тип лидерборда — time, то значения необходимо передавать в миллисекундах.

extraData

Описание пользователя. Необязательный параметр.

Примечание

Запрос можно отправлять не чаще, чем 1 раз за 1 секунду. В противном случае он будет отклонен с ошибкой.

// Без 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

Имя лидерборда.

Примечание

Запрос можно отправлять не чаще, чем 60 раз за 5 минут. В противном случае он будет отклонен с ошибкой.

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. Не может быть отрицательным, максимальное значение ограничено только логикой JavaScript. Если тип лидерборда — time, то значения необходимо передавать в миллисекундах.

extraData

Описание пользователя. Необязательный параметр.

getAvatarSrc

Возвращает URL портрета пользователя. Возможные значения size: small, medium и large.

getAvatarSrcSet

Возвращает srcset портрета пользователя, который подходит для дисплеев Retina. Возможные значения 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.

Примечание

Запрос можно отправлять не чаще, чем 20 раз за 5 минут. В противном случае он будет отклонен с ошибкой.

// С использованием всех значений по умолчанию.
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

Место в рейтинге. Счет ведется с нуля, поэтому 1-е место считается нулевым элементом.

size

Количество запрошенных записей. Если данных не хватает, то может не соответствовать ответу.

userRank

Место пользователя в рейтинге. Если отсутствует, либо запрос на топ без включения пользователя, то равен 0.

entries

Результаты по запросу.

score

Значение результата. Принимается только тип integer. Не может быть отрицательным, максимальное значение ограничено только логикой JavaScript. Если тип лидерборда — time, то значения необходимо передавать в миллисекундах.

extraData

Описание пользователя. Необязательный параметр.

getAvatarSrc

Возвращает URL портрета пользователя. Возможные значения size: small, medium и large.

getAvatarSrcSet

Возвращает srcset портрета пользователя, который подходит для дисплеев Retina. Возможные значения size: small, medium и large.

Ограничения методов

Метод

Описание

Лимит

Авторизация пользователей

ysdk.leaderboards.setScore()

Установить новый результат игрока

1 запрос за 1 секунду

Обязательна

ysdk.leaderboards.getPlayerEntry()

Вывести рейтинг одного пользователя

60 запросов за 5 минут

Обязательна

ysdk.leaderboards.getEntries()

Получить рейтинг нескольких пользователей

20 запросов за 5 минут

Необязательна

Лимит на остальные запросы: 20 запросов за 5 минут.

Проблемы, связанные с лидербордами

Совет

При использовании сочетания методов ysdk.isAvailableMethod() и ysdk.leaderboards.setScore() неавторизованные пользователи не попадают в лидерборд и не видят свой прогресс. Мы рекомендуем сделать отдельную таблицу лидеров, сохранять туда результаты любых пользователей и отображать ее результаты для всех. Вы можете создать кастомные лидерборды самостоятельно в коде приложения, выбор технологии не ограничен.

Object already exists

Ошибка возникает при попытке создать новый лидерборд с именем старого. Введите имя, которое раньше не использовалось.

Пользователь скрыт

Надпись «Пользователь скрыт» отображается, если игрок не разрешил использовать свои аватар и имя. Доступ к данным пользователя зависит от настроек в его профиле. Подробнее см. в разделе Инициализация.

Ошибка 404

Если при попытке вызвать методы SDK для лидерборда возникает ошибка 404, проверьте, что в Консоли разработчика создан лидерборд с соответствующим именем в поле Техническое название лидерборда.

Примечание

Сотрудники службы поддержки помогают разместить готовую игру на платформе Яндекс Игр. На прикладные вопросы о разработке и тестировании предметно ответят другие разработчики в Сообществе в Телеграме.

Если при использовании SDK Яндекс Игр вы столкнулись с проблемой или у вас появился вопрос, обратитесь в службу поддержки:

Написать в чат

Имя лидерборда.

Идентификатор приложения.

Если true, то лидерборд является основным.

Направление сортировки:

  • false — места отсортированы по убыванию;
  • true — места отсортированы по возрастанию.

Размер десятичной части счета. Например, при decimal_offset: 2 число 1234 будет отображаться как 12.34.

Тип результата лидерборда. Доступные параметры: numeric (число), time (секунды).

Локализованные названия. Возможные параметры массива: ru, en, be, uk, kk, uz, tr.

Значение результата. Принимается только тип integer. Не может быть отрицательным. Если тип лидерборда — time, то значения необходимо передавать в миллисекундах.

Тип результата лидерборда. Доступные параметры: numeric (число), time (секунды).

Описание пользователя. Необязательный параметр.

Возвращает URL портрета пользователя. Возможные значения size: small, medium и large.

Возвращает srcset портрета пользователя, который подходит для дисплеев Retina. Возможные значения size: small, medium и large.

Определяет, включать ли авторизованного пользователя в ответ:

  • true — включать в ответ;
  • false (по умолчанию) — не включать.

Количество записей ниже и выше пользователя по лидерборду, которое нужно вернуть. Минимальное значение — 1, максимальное — 10. По умолчанию возвращается 5.

Количество записей из топа лидерборда. Минимальное значение — 1, максимальное — 20. По умолчанию возвращается 5.

Описание лидерборда.

Интервалы мест в ответе.

Место в рейтинге. Счет ведется с нуля, поэтому 1-е место считается нулевым элементом.

Количество запрошенных записей. Если данных не хватает, то может не соответствовать ответу.

Место пользователя в рейтинге. Если отсутствует, либо запрос на топ без включения пользователя, то равен 0.

Результаты по запросу.

Предыдущая
Инап-покупки
Следующая
Асинхронный мультиплеер