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

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

Чтобы инициализировать объект 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.
    });

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

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

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

Чтобы проверить, авторизован ли игрок на Яндексе, используйте метод объекта 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.

Потеря прогресса на 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 надежным.