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

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

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

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

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

1const ysdk = await YaGames.init();
2
3try {
4    const player = await ysdk.getPlayer();
5} catch (e) {
6    // Ошибка при инициализации объекта Player.
7}

При инициализации объекта Player передаются:

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

Подробнее об этих параметрах читайте в разделе Данные профиля пользователя.

Доступ к данным пользователя зависит от настроек в его профиле. Если игрок запретил доступ к персональным данным, в ответе будет только идентификатор.

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

 1const ysdk = await YaGames.init();
 2
 3try {
 4    const player = await ysdk.getPlayer({ signed: true });
 5
 6    // Используйте player.signature для авторизации на своем сервере.
 7    const authData = await fetch('https://your.game.server/auth', {
 8        method: 'POST',
 9        headers: { 'Content-Type': 'text/plain' },
10        body: player.signature
11    });
12} catch (e) {
13    // Ошибка при инициализации объекта Player или авторизации.
14}

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

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

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

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

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

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

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

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

 1const ysdk = await YaGames.init();
 2
 3try {
 4    let player = await ysdk.getPlayer();
 5
 6    // Игрок не авторизован.
 7    if (!player.isAuthorized()) {
 8        try {
 9            // Открытие окна авторизации.
10            await ysdk.auth.openAuthDialog();
11
12            const authorizedPlayer = await ysdk.getPlayer();
13
14            player = authorizedPlayer;
15        } catch (e) {
16            // Ошибка при авторизации игрока или повторной инициализации объекта Player.
17        }
18    }
19    // Игрок успешно авторизован.
20} catch (err) {
21    // Ошибка при инициализации объекта Player.
22}

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

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

player.setData(data, flush)

Сохраняет данные пользователя. Максимальный размер данных на игрока — 200 KБ.

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

function setData(data: object, flush: boolean) => Promise<void> {}

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

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

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

Пример

 1const ysdk = await YaGames.init();
 2
 3const player = await ysdk.getPlayer();
 4
 5await player.setData({
 6    achievements: ['trophy1', 'trophy2', 'trophy3'],
 7})
 8
 9console.log('data is set');

player.getData(keys)

Асинхронно возвращает внутриигровые данные пользователя, сохраненные в базе данных Яндекса.

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

function getData(keys?: Array<string>) => Promise<object> {}

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

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

player.setStats(stats)

Сохраняет численные данные пользователя. Максимальный размер численных данных на игрока — 10 КБ.

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

function setStats(stats?: object) => Promise<void> {}

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

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

player.incrementStats(increments)

Изменяет численные данные пользователя. Максимальный размер численных данных на игрока — 10 КБ.

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

function incrementStats(increments: object) => Promise<object> {}

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

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

player.getStats(keys)

Асинхронно возвращает численные данные пользователя.

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

function getStats(keys?: Array<string>) => Promise<object> {}

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

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

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

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

player.getUniqueID()

Возвращает постоянный уникальный идентификатор пользователя.

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

function getUniqueID() => string {}

player.getIDsPerGame()

Метод возвращает массив объектов с указанием идентификаторов пользователя во всех играх разработчика, в которых пользователь явно дал согласие на передачу персональных данных.

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

function getIDsPerGame() => Promise<Array<{ appID: number, userID: string }>> {}

player.getName()

Возвращает имя пользователя.

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

function getName() => string {}

player.getPhoto()

Возвращает URL аватара пользователя в зависимости от размера запрашиваемого изображения.

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

function getPhoto(size: 'small' | 'medium' | 'large') => string {}

player.getPayingStatus()

Возвращает значение, зависящее от частоты и объема покупок пользователя.

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

function getPayingStatus() => EPayingStatus {}

EPayingStatus принимает одно из значений:

Пример

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

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

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

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

1const ysdk = await YaGames.init();
2
3const safeStorage = await ysdk.getStorage();
4
5safeStorage.setItem('key', 'safe storage is working');
6console.log(safeStorage.getItem('key'));

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

1const ysdk = await YaGames.init();
2
3const safeStorage = await ysdk.getStorage();
4
5Object.defineProperty(window, 'localStorage', { get: () => safeStorage });
6
7localStorage.setItem('key', 'safe storage is working');
8console.log(localStorage.getItem('key'));

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

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