Лидерборды

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

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

Внимание

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

Для работы с лидербордами используется объект lb.

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

Чтобы инициализировать объект lb, используйте метод ysdk.getLeaderboards():

var lb;

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

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

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

getLeaderboardDescription(
  leaderboardName: string
)

Параметр

Описание

leaderboardName

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

 
ysdk.getLeaderboards()
  .then(lb => lb.getLeaderboardDescription('leaderboard2021'))
  .then(res => console.log(res));

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  const res = await lb.getLeaderboardDescription('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.setLeaderboardScore'), который возвращает Promise<Boolean>, где логическое значение указывает на доступность метода.

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

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

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

Параметр

Описание

leaderboardName

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

score

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

extraData

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

Примечание

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

ysdk.getLeaderboards()
  .then(lb => {
    // Без extraData.
    lb.setLeaderboardScore('leaderboard2021', 120);
    // С extraData.
    lb.setLeaderboardScore('leaderboard2021', 120, 'My favourite player!');
  });

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  // Без extraData.
  await lb.setLeaderboardScore('leaderboard2021', 120);
  // С extraData.
  await lb.setLeaderboardScore('leaderboard2021', 120, 'My favourite player!');
}

work();

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

Внимание

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

Чтобы проверить доступность метода для пользователя, вы можете использовать метод ysdk.isAvailableMethod('leaderboards.getLeaderboardPlayerEntry'), который возвращает Promise<Boolean>, где логическое значение указывает на доступность метода.

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

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

getLeaderboardPlayerEntry(
  leaderboardName: string
)

Параметр

Описание

leaderboardName

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

Примечание

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

ysdk.getLeaderboards()
  .then(lb => lb.getLeaderboardPlayerEntry('leaderboard2021'))
  .then(res => console.log(res))
  .catch(err => {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // Срабатывает, если у игрока нет записи в лидерборде.
    }
  });

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  try {
    const res = await lb.getLeaderboardPlayerEntry('leaderboard2021');
  } catch (err) {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
      // Срабатывает, если у игрока нет записи в лидерборде.
    }
  }
  console.log(res);
}

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.

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

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

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

Параметр

Описание

leaderboardName

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

includeUser

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

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

quantityAround

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

quantityTop

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

Примечание

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

ysdk.getLeaderboards()
  .then(lb => {
    // С использованием всех значений по умолчанию.
    lb.getLeaderboardEntries('leaderboard2021')
      .then(res => console.log(res));
    // Получение 10 топов.
    lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10 })
      .then(res => console.log(res));
    // Получение 10 топов и 3 записей возле пользователя.
    lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10, includeUser: true, quantityAround: 3 })
      .then(res => console.log(res));
  });

const work = async () => {
  const lb = await ysdk.getLeaderboards();
  let res;
  // С использованием всех значений по умолчанию.
  res = await lb.getLeaderboardEntries('leaderboard2021');
  console.log(res);
  // Получение 10 топов.
  res = await lb.getLeaderboardEntries('leaderboard2021', { quantityTop: 10 });
  console.log(res);
  // Получение 10 топов и 3 записей возле пользователя.
  res = await lb.getLeaderboardEntries('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.

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

Метод

Описание

Лимит

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

lb.setLeaderboardScore()

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

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

Обязательна

lb.getLeaderboardPlayerEntry()

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

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

Обязательна

lb.getLeaderboardEntries()

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

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

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

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

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

Совет

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

Object already exists

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

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

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

Убедитесь, что при показе окна с запросом доступа вы запрашиваете данные пользователя ysdk.getPlayer({ scopes: true }). Если вы используете параметр scopes: false, игра не запросит имя и аватар пользователя.

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

В случае, если игрок очистит кеш и куки, зайдет в режиме инкогнито или через другой браузер, то у него снова можно запросить авторизацию и разрешение. О том, как вызвать диалоговое окно, можно прочитать в статье Данные игрока.

Ошибка 404

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

Примечание

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

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

Написать в чат
Предыдущая
Внутриигровые покупки
Следующая
Оценка игры