Лидерборды

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

Чтобы запросы к лидербордам работали, выполните условия:

в коде игры подключите и настройте SDK, чтобы его объект был доступен через переменную ysdk;
в Консоли разработчика создайте лидерборд.

Внимание

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

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

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

Внимание

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

Старые методы

1const ysdk = await YaGames.init();
2
3const lb = await ysdk.getLeaderboards();
4
5// Соответствие вызова методов лидерборда старым и новым способами:
6// lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
7// lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
8// lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
9// lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()

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

Чтобы получить описание лидерборда по его имени, используйте метод ysdk.leaderboards.getDescription().

Сигнатура метода:

 1interface ILeaderboardDescription {
 2    appID: string;
 3    default: boolean;
 4    description: {
 5        invert_sort_order: boolean;
 6        score_format: {
 7            options: {
 8                decimal_offset: number;
 9            };
10            type: 'numeric' | 'time';
11        };
12        sort_order: string;
13    };
14    name: string;
15    title: Record<Locale, string>;
16}
17
18function getDescription(
19    leaderboardName: string
20): Promise<ILeaderboardDescription> {}

Принимает единственным параметром техническое название лидерборда leaderboardName. Возвращает объект с описанием лидерборда, который включает поля:

Параметр	Тип	Описание
`appID`	`string`	Идентификатор приложения.
`default`	`boolean`	Если `true`, то лидерборд является основным.
`invert_sort_order`	`boolean`	Направление сортировки: `false` — по убыванию (на первых местах будут пользователи с наибольшим счетом); `true` — по возрастанию (на первых местах будут пользователи с наименьшим счетом).
`sort_order`	`string`	Направление сортировки в строковом формате: `'DESC'` — по убыванию; `'ASC'` — по возрастанию.
`decimal_offset`	`number`	Размер десятичной части счета. Например, при `decimal_offset: 2` число 1234 будет отображаться как 12.34.
`type`	`'numeric'` \| `'time'`	Тип результата лидерборда. Доступные значения: `numeric` (число), `time` (миллисекунды).
`name`	`string`	Имя лидерборда, указанное в Консоли в поле Техническое название лидерборда.
`title`	`Record<Locale, string>`	Список локализованных названий. Возможные коды языков перечислены на странице Языки и домены.

Пример

1const ysdk = await YaGames.init();
2
3const lb = await ysdk.leaderboards.getDescription('leaderboard2021');
4
5console.log(lb);

Новый результат

Внимание

Запрос доступен только для авторизованных пользователей. Как проверить статус авторизации и вызвать диалог входа, см. в разделе Авторизация пользователя.

Перед отправкой запроса проверьте доступность метода с помощью ysdk.isAvailableMethod('leaderboards.setScore'). Метод возвращает Promise<Boolean>.

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

Чтобы установить игроку новый результат, используйте метод ysdk.leaderboards.setScore().

Сигнатура метода:

1function setScore(
2    leaderboardName: string,
3    score: number,
4    extraData?: string
5): Promise<void> {}

Принимает три параметра:

Параметр	Тип	Описание
`leaderboardName`	`string`	Имя лидерборда, указанное в Консоли в поле Техническое название лидерборда.
`score`	`number`	Значение результата. Не может быть отрицательным, максимальное значение ограничено только логикой JavaScript. Если тип лидерборда — `time`, то значение необходимо передавать в миллисекундах.
`extraData`	`string`	Описание пользователя. Необязательный параметр.

Примечание

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

Пример

1const ysdk = await YaGames.init();
2
3await ysdk.leaderboards.setScore('leaderboard2021', 120);
4
5await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');

Получение рейтинга

Внимание

Перед отправкой запроса проверьте доступность метода с помощью ysdk.isAvailableMethod('leaderboards.getPlayerEntry'). Метод возвращает Promise<Boolean>.

Чтобы получить рейтинг пользователя, используйте метод ysdk.leaderboards.getPlayerEntry().

Сигнатура метода:

 1interface ILeaderboardEntry {
 2    extraData: string;
 3    rank: number;
 4    score: number;
 5    player: {
 6        publicName: string;
 7        uniqueID: string;
 8        getAvatarSrc: (size?: 'small' | 'medium' | 'large') => string;
 9        getAvatarSrcSet: (size?: 'small' | 'medium' | 'large') => string;
10    }
11}
12
13function getPlayerEntry(
14    leaderboardName: string
15): Promise<ILeaderboardEntry> {}

Принимает единственным параметром техническое название лидерборда leaderboardName. Возвращает объект с рейтингом пользователя, который включает поля:

Параметр	Тип	Описание
`score`	`number`	Значение результата.
`rank`	`number`	Позиция пользователя в лидерборде.
`extraData`	`string`	Описание пользователя.
`publicName`	`string`	Имя пользователя.
`uniqueID`	`string`	Уникальный идентификатор пользователя.
`getAvatarSrc`	`(size?: TSize) => string`	Возвращает URL портрета пользователя в заданном размере. Возможные значения `size`: `small`, `medium`, `large`.
`getAvatarSrcSet`	`(size?: TSize) => string`	Возвращает srcset портрета пользователя, который подходит для дисплеев Retina. Возможные значения `size`: `small`, `medium`, `large`.

Примечание

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

Пример

 1const ysdk = await YaGames.init();
 2
 3try {
 4    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
 5
 6    console.log(res);
 7} catch (err) {
 8    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
 9        // Срабатывает, если у игрока нет записи в лидерборде.
10    }
11}

Записи лидерборда

Чтобы вывести рейтинг пользователей, используйте метод ysdk.leaderboards.getEntries().

Сигнатура метода:

 1interface ILeaderboardEntries {
 2    leaderboard: ILeaderboardDescription;
 3    ranges: {
 4        start: number;
 5        size: number;
 6    }[];
 7    userRank: number;
 8    entries: ILeaderboardEntry[];
 9}
10
11function getEntries(
12    leaderboardName: string,
13    options: {
14        includeUser?: boolean;
15        quantityAround?: number;
16        quantityTop?: number;
17    }
18): Promise<ILeaderboardEntries> {}

Принимает техническое название лидерборда leaderboardName и опциональные параметры options:

Опция	Тип	Описание
`includeUser`	`boolean`	Определяет, включать ли авторизованного пользователя в ответ: `true` — включать в ответ. `false` (по умолчанию) — не включать.
`quantityAround`	`number`	Количество записей ниже и выше пользователя по лидерборду, которое нужно вернуть. Минимальное значение — 1, максимальное — 10. По умолчанию возвращается 5.
`quantityTop`	`number`	Количество записей из топа лидерборда. Минимальное значение — 1, максимальное — 20. По умолчанию возвращается 5.

Возвращает объект с рейтингом пользователей Promise<ILeaderboardEntries>, который включает поля:

Параметр	Тип	Описание
`leaderboard`	`ILeaderboardDescription`	Описание лидерборда
`ranges`	`object[]`	Интервалы мест в ответе.
`start`	`number`	Место в рейтинге. Счет ведется с нуля, поэтому 1-е место считается нулевым элементом.
`size`	`number`	Количество запрошенных записей. Если данных не хватает, то может не соответствовать ответу.
`userRank`	`number`	Место пользователя в рейтинге. Если отсутствует, либо запрос на топ без включения пользователя, то равен 0.
`entries`	`ILeaderboardEntry[]`	Массив записей рейтинга. Запись идентична возвращаемому значению из метода Получение рейтинга.

Примечание

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

Пример

 1const ysdk = await YaGames.init();
 2
 3// Получение 10 топ-игроков и 3 записей возле пользователя.
 4const entries = await ysdk.leaderboards.getEntries('leaderboard2021', {
 5    quantityTop: 10,
 6    includeUser: true,
 7    quantityAround: 3
 8});
 9
10console.log(entries);

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

Метод	Описание	Лимит	Авторизация пользователей
`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 Яндекс Игр вы столкнулись с проблемой или у вас появился вопрос, обратитесь в службу поддержки:

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

Была ли статья полезна?

Инап-покупки

Асинхронный мультиплеер