Лидерборды
Вы можете показывать на странице игры персонализированные лидерборды (таблицы лидеров) с результатами лучших игроков и местом в рейтинге авторизованного пользователя.
Чтобы у вас заработали описанные ниже запросы, проверьте, что выполнены условия:
- вы подключили и настроили SDK и его объект доступен через переменную
ysdk
; - в Консоли разработчика создан лидерборд.
Внимание
Если в Консоли нет лидерборда с соответствующим именем в поле Техническое название лидерборда, запросы будут выдавать ошибку 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
)
Параметр |
Описание |
|
Имя лидерборда. |
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
}
}
Параметр |
Описание |
|
Идентификатор приложения. |
|
Если |
|
Направление сортировки:
|
|
Размер десятичной части счета. Например, при |
|
Тип результата лидерборда. Доступные параметры: |
|
Имя лидерборда. |
|
Локализованные названия. Возможные параметры массива: |
Новый результат
Внимание
Запрос доступен только для авторизованных пользователей. При необходимости воспользуйтесь авторизацией.
Чтобы проверить доступность метода для пользователя, вы можете использовать метод ysdk.isAvailableMethod('leaderboards.setScore')
, который возвращает Promise<Boolean>
, где логическое значение указывает на доступность метода.
Чтобы результаты сохранялись для всех пользователей вне зависимости от авторизации, рекомендуем прописать кастомный лидерборд самостоятельно в коде приложения. Выбор технологии не ограничен.
Чтобы установить игроку новый результат, используйте метод ysdk.leaderboards.setScore()
:
setScore(
leaderboardName: string,
score: number,
extraData?: string
)
Параметр |
Описание |
|
Имя лидерборда. |
|
Значение результата. Принимается только тип |
|
Описание пользователя. Необязательный параметр. |
Примечание
Запрос можно отправлять не чаще, чем 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
)
Параметр |
Описание |
|
Имя лидерборда. |
Примечание
Запрос можно отправлять не чаще, чем 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
}
Параметр |
Описание |
|
Значение результата. Принимается только тип |
|
Описание пользователя. Необязательный параметр. |
|
Возвращает URL портрета пользователя. Возможные значения |
|
Возвращает srcset портрета пользователя, который подходит для дисплеев Retina. Возможные значения |
Записи лидерборда
Чтобы вывести рейтинг пользователей, используйте метод ysdk.leaderboards.getEntries()
:
getEntries(
leaderboardName: string,
{
includeUser: boolean,
quantityAround: integer,
quantityTop: integer
}
)
Параметр |
Описание |
|
Имя лидерборда. |
|
Определяет, включать ли авторизованного пользователя в ответ:
|
|
Количество записей ниже и выше пользователя по лидерборду, которое нужно вернуть. Минимальное значение — 1, максимальное — 10. По умолчанию возвращается 5. |
|
Количество записей из топа лидерборда. Минимальное значение — 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
},
...
]
}
Параметр |
Описание |
|
|
|
Интервалы мест в ответе. |
|
Место в рейтинге. Счет ведется с нуля, поэтому 1-е место считается нулевым элементом. |
|
Количество запрошенных записей. Если данных не хватает, то может не соответствовать ответу. |
|
Место пользователя в рейтинге. Если отсутствует, либо запрос на топ без включения пользователя, то равен 0. |
|
Результаты по запросу. |
|
Значение результата. Принимается только тип |
|
Описание пользователя. Необязательный параметр. |
|
Возвращает URL портрета пользователя. Возможные значения |
|
Возвращает srcset портрета пользователя, который подходит для дисплеев Retina. Возможные значения |
Ограничения методов
Метод |
Описание |
Лимит |
Авторизация пользователей |
|
1 запрос за 1 секунду |
Обязательна |
|
|
60 запросов за 5 минут |
Обязательна |
|
|
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.
Результаты по запросу.