Данные игрока

Вы можете сохранять данные состояния игры (пройденные уровни, опыт, внутриигровые покупки и т. д.) на сервере Яндекса или передавать их на свой сервер. Также вы можете персонализировать игру, используя некоторые данные из профиля пользователя на Яндексе, например, имя.

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

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

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

var player;

ysdk.getPlayer().then(_player => {
        player = _player;
    }).catch(err => {
        // Ошибка при инициализации объекта Player.
    });

При инициализации объекта Player:

• Передается идентификатор пользователя.

• У авторизованных игроков запрашивается доступ к:

  • аватару и имени;
  • данным о покупках на платформе (только для пользователей из РФ и при наличии покупок в игре).

  Доступ запрашивается из разрешений, которые пользователь выставил в своем профиле.

• У неавторизованных игроков из РФ запрашивается доступ к данным о покупках на платформе (только для игр с покупками).

Если вам достаточно знать идентификатор, а имя и аватар пользователя не нужны, используйте опциональный параметр scopes: false.

Настройки запросов доступа:

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

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

var player;

ysdk.getPlayer({ signed: true }).then(_player => {
        player = _player;

        // Используйте player.signature для авторизации на своем сервере.
        fetch('https://your.game.server?auth', {
            method: 'POST',
            headers: { 'Content-Type': 'text/plain' },
            body: player.signature
        });
    }).catch(err => {
        // Ошибка при инициализации объекта Player.
    });

Параметр signature передаваемого на сервер запроса содержит данные пользователя из профиля на Яндексе и подпись. Представляет собой две строки в кодировке base64:

<подпись>.<данные профиля>

Подробнее см. в разделе Защита от накруток.

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

Проверка авторизации

Чтобы проверить, авторизован ли игрок на Яндексе, используйте метод объекта Player — player.getMode(). Метод возвращает строку lite в случае, если игрок не авторизован в Яндексе.

Вызов диалогового окна авторизации

Если игрок не авторизован, вы можете использовать метод ysdk.auth.openAuthDialog(), чтобы вызвать окно авторизации.

var player;

function initPlayer() {
    return ysdk.getPlayer().then(_player => {
            player = _player;

            return player;
        });
}

initPlayer().then(_player => {
        if (_player.getMode() === 'lite') {
            // Игрок не авторизован.
            ysdk.auth.openAuthDialog().then(() => {
                    // Игрок успешно авторизован.
                    initPlayer().catch(err => {
                        // Ошибка при инициализации объекта Player.
                    });
                }).catch(() => {
                    // Игрок не авторизован.
                });
        }
    }).catch(err => {
        // Ошибка при инициализации объекта Player.
    });

Внутриигровые данные

Для работы с внутриигровыми данными пользователя используйте методы объекта Player:

• player.setData(data, flush) — сохраняет данные пользователя. Максимальный размер данных не должен превышать 200 KБ.

  • data — object — объект, содержащий пары ключ-значение.
  • flush — boolean — определяет очередность отправки данных. При значении «true» данные будут отправлены на сервер немедленно; «false» (значение по умолчанию) — запрос на отправку данных будет поставлен в очередь.

  Метод возвращает Promise, который показывает, удалось сохранить данные или нет.

  При значении параметра flush: false возвращаемый результат показывает только валидность данных (сама отправка поставлена в очередь и будет осуществлена позже). При этом метод player.getData() вернет данные, установленные последним вызовом player.setData(), даже если они еще не были отправлены.

  player.setData({
          achievements: ['trophy1', 'trophy2', 'trophy3'],
      }).then(() => {
          console.log('data is set');
      });
  

• player.getData(keys) — асинхронно возвращает внутриигровые данные пользователя, сохраненные в базе данных Яндекса.

  • keys — array<string> — список ключей, которые необходимо вернуть. Если параметр keys отсутствует, то метод возвращает все внутриигровые данные пользователя.

  Метод возвращает Promise<Object>, где объект содержит пары ключ-значение.

• player.setStats(stats) — сохраняет численные данные пользователя. Максимальный размер данных не должен превышать 10 КБ.

  • stats — object — объект, содержащий пары ключ-значение, где каждое значение должно быть числом.

  Метод возвращает Promise, который показывает, удалось сохранить данные или нет.

  Совет

  Используйте данный метод для часто изменяемых числовых значений (баллы, очки опыта, внутриигровая валюта) вместо player.setData().

• player.incrementStats(increments) — изменяет внутриигровые данные пользователя. Максимальный размер данных не должен превышать 10 КБ.

  • increments — object — объект, который содержит пары ключ-значение, где каждое значение должно быть числом.

  Метод возвращает Promise<Object>, где объект содержит измененные и добавленные пары ключ-значение.

• player.getStats(keys) — асинхронно возвращает численные данные пользователя.

  • keys — array<string> — список ключей, которые необходимо вернуть. Если параметр keys отсутствует, то метод возвращает все внутриигровые данные пользователя.

  Метод возвращает Promise<Object>, где объект содержит пары ключ-значение.

Данные профиля пользователя

Чтобы получить данные из профиля пользователя на Яндексе, используйте методы объекта Player:

• player.getUniqueID() — возвращает постоянный уникальный идентификатор пользователя (тип: string).

  Примечание

  Используемый ранее метод player.getID() объявлен устаревшим, но некоторое время он продолжит работать с предупреждением в консоли ошибок.

  Значения player.getID() и player.getUniqueID() в общем случае не совпадают для одного объекта Player, но для некоторых пользователей могут быть одинаковыми. Если значения различаются и игра ранее самостоятельно привязывала к значению player.getID() какие-либо данные, необходимо произвести миграцию этих данных, привязав их к значению player.getUniqueID(). Чтобы выполнить миграцию сразу для всех пользователей, напишите в службу поддержки.

• player.getIDsPerGame() — возвращает Promise<Array>, где указаны идентификаторы пользователя во всех играх разработчика, в которых от пользователя было получено явное согласие на передачу персональных данных. Например:

  [
      { appID: 103915, userID: "tOpLpSh7i8QG8Voh/SuPbeS4NKTj1OxATCTKQF92H4c=" },
      { appID: 103993, userID: "bviQCIAAuVmNMP66bZzC4x+4oSFzRKpteZ/euP/Jwv4=" }
  ]
  

  Внимание

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

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

• player.getName() — возвращает имя пользователя (тип: string).

• player.getPhoto(size) — возвращает URL аватара пользователя (тип: string).

  • size — string — требуемый размер. Возможные значения: small, medium, large.

• player.getPayingStatus() — возвращает четыре возможных значения (тип: string), зависящих от частоты и объема покупок пользователя:

  • paying — пользователь купил портальную валюту на сумму более 500 рублей за последний месяц.
  • partially_paying — у пользователя была хотя бы одна покупка портальной валюты реальными деньгами за последний год.
  • not_paying — пользователь не делал покупок портальной валюты реальными деньгами за последний год.
  • unknown — пользователь не из РФ или он не разрешил передачу такой информации разработчику.

  Пример использования:

  const ysdk = await YaGames.init(); // Инициализируем SDK.
  const player = await ysdk.getPlayer(); // Получаем игрока.
  const payingStatus = player.getPayingStatus(); // Получаем статус платежной активности пользователя на платформе.
  
  if (payingStatus === 'paying' || payingStatus === 'partially_paying') {
      // Предложить in-app товар на старте или вместо рекламы.
  }
  

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

Потеря прогресса на iOS

Если игра интегрируется через iframe, хранилище localStorage может часто сбрасываться на новых версиях iOS, из-за чего игроки будут терять прогресс. Чтобы этого избежать, используйте хранилище safeStorage, у которого такой же интерфейс, как у localStorage:

ysdk.getStorage().then(safeStorage => {
        safeStorage.setItem('key', 'safe storage is working');
        console.log(safeStorage.getItem('key'))
    })

Чтобы не менять код вручную, переопределите localStorage глобально.

ysdk.getStorage().then(safeStorage => Object.defineProperty(window, 'localStorage', { get: () => safeStorage }))
    .then(() => {
        localStorage.setItem('key', 'safe storage is working');
        console.log(localStorage.getItem('key'))
    })

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

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