Награды API

Интеграция наград через SDK. Методы работы.

Список методов

Действия:

• gp.rewards.give() - выдать награду.
• gp.rewards.accept() - принять награду и начислить бонусы.

Свойства:

• gp.rewards.list - список наград.
• gp.rewards.givenList - список выданных наград.
• gp.rewards.getReward() - получить информацию о награде по ID или тегу.

Проверки:

• gp.rewards.has() - проверить выдана ли награда.
• gp.rewards.hasAccepted() - проверить получена ли награда.
• gp.rewards.hasUnaccepted() - проверить есть ли выданная, но не полученная награда.

События:

• gp.rewards.on('give') - подписаться на выдачу награды.
• gp.rewards.on('error:give') - подписаться на ошибку при выдаче награды.
• gp.rewards.on('accept') - подписаться на принятие награды.
• gp.rewards.on('error:accept') - подписаться на ошибку при принятии награды.

Типы:

• Reward - поля награды.
• PlayerReward - поля награды игрока.

Правила работы с наградами

Порядок работы с наградами:

• Выдать награду игроку. Вручную или через триггеры.
• Принять награду. Автоматически или вручную, например при клике на кнопку "получить".
• Автоматически начисляются бонусы.
• Сохранить игрока.

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

Вы можете обозначить разные типы наград для себя, например: одноразовые и постоянные.

Пример одноразовой награды:

• Награда за вход
• Стартовый набор
• Премиум сундук
• Награда за достижение

Такие награды можно принимать сразу или оставить на ручное действие игрока.

tip

Награды при принятии начисляются автоматически. Однако, если вы хотите добавить нестандартные изменения переменных, то вы можете сделать их, завязавшись на событие accepted.

Например, вам нужно:

• Добавить предмет в инвентарь
• Изменить данные в JSON структуре
• Совершить другие манипуляции, не относящиеся к игроку или не поддерживаемые панелью управления.

Пример постоянной награды:

• Уникальный меч / скин / автомобиль
• VIP статус / отключение рекламы
• DLC / уровни / острова и другой разблокируемый контент

Постоянные награды не обязательно принимать. Как только награда была выдана - она будет всегда видна пользователю.

Правила проведения одноразовой награды с автоматическим принятием

Базовое

// 1. Выдаем награду
await gp.rewards.give({ tag: 'STARTER_PACK' });

// 2. Сработает автопринятие награды
// 3. Начислится награда

// 4. Сохраняем игрока на сервере
await gp.player.sync();

С изменением нестандартных данных

На примере добавления в инвентарь зелий здоровья и маны:

// 1. Подписываемся на принятие награды
gp.rewards.on('accept', ({ reward }) => {
    switch (reward.tag) {
        case 'STARTER_PACK': {
            // 2. Если нужно начисляем дополнительные награды
            inventory.push({ item: 'HP_POTION', amount: 100 });
            inventory.push({ item: 'MP_POTION', amount: 100 });

            gp.player.set('inventory', JSON.stringify(inventory));
            break;
        }
    }

    // 3. Если нужно обновляем интерфейс, чтобы отобразить изменения переменных
    myGame.refreshUI();
});

// 4. Выдаем награду
await gp.rewards.give({ tag: 'STARTER_PACK' });

// 5. Сработает автопринятие награды
// 6. Начислится награда
// 7. Вызовется событие accept

// 8. Сохраняем игрока на сервере
await gp.player.sync();

Допринятие наград при запуске игры

Иногда может быть такое, что игрок не успел принять награды и сохранить прогресс, например:

• Закрыл / перезагрузил вкладку, браузер или приложение
• Выключил / сломалось устройство
• Игра крашнулась

При заходе их нужно допринять.

Все непринятые награды с автопринятием SDK автоматически принимает при старте.

info

Важно. Мы не знаем в какой момент игра полностью загружена и вы готовы обработать начисления. Поэтому вызовите метод начала игры gp.gameStart(), когда вы будете готовы к принятию наград. После вызова начала игры мы начислим награды, а вы заблаговременно можете подписаться на событие принятия наград.

Если у награды нет автопринятия - вы можете вручную допринять нужные вам награды при старте игры:

// Если нужна ручная обработка награды,
// то нужно !! сначала !! подписаться на событие принятия
gp.rewards.on('accept', ({ reward }) => {
    // Действия при получении награды
});

const rewardsToAcceptOnStartup = [
    'STARTER_PACK',
    'LEVEL_10',
    'LEVEL_20',
    //...
];

rewardsToAcceptOnStartup.forEach((rewardTag) => {
    const { reward, playerReward } = gp.reward.getReward(reward.tag);

    // Такой награды не существует
    if (!reward) {
        return;
    }

    // Получаем количество непринятых наград
    const unacceptedRewardsLeft = playerReward.countTotal - playerReward.countAccepted;

    // Принимаем награды
    for (let i = 0; i < unacceptedRewardsLeft; i++) {
        gp.reward.accept(reward.id);
    }
});

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

// 1. Выдаем награду
await gp.rewards.give({ tag: 'NOOB_SKIN' });

// 2. В нужный момент проверяется наличие награды
if (gp.rewards.has('NOOB_SKIN')) {
    // сделать что-нибудь при наличии скина нубика
}

Действия

Выдать награду

Чтобы выдать награду игроку, вам необходимо передать ID или тег награды.

// По ID
gp.rewards.give({ id: 123 });
// По Тегу
gp.rewards.give({ tag: 'STARTER_PACK' });

Вы можете выдать награду с отложенным сохранением. Она сохранится вместе с сохранением игрока.

gp.rewards.give({ id: 123, lazy: true });

Метод возвращает награду и награду игрока:

const { reward, playerReward } = await gp.rewards.give({ id: 123 });

Принять награду

После выдачи награды, ее можно принять и начислить изменения переменных.

// Принятие по ID
gp.rewards.accept({ id: 123 });

// Принятие по тегу
gp.rewards.accept({ tag: 'STARTER_PACK' });

Метод возвращает награду и награду игрока:

const { reward, playerReward } = await gp.rewards.accept({ id: 123 });

Свойства

Список наград

Вам доступен весь список наград сразу при запуске игры. См. поля награды.

gp.rewards.list.forEach((reward) => {
    // reward.id
    // reward.tag
    // reward.name
    // reward.description
    // reward.isAutoAccept
    // reward.mutations
});

Список выданных наград

Вам доступен весь список наград сразу при готовности игрока. См. поля награды игрока.

gp.rewards.givenList.forEach((playerReward) => {
    // playerReward.rewardId
    // playerReward.countTotal
    // playerReward.countAccepted
});

Получение информации о награде

Метод возвращает награду и награду игрока:

// По ID
const { reward, playerReward } = gp.rewards.getReward(123);
// По Тегу
const { reward, playerReward } = gp.rewards.getReward('STARTER_PACK');

// Награды может не существовать, убедитесь, что она есть
if (reward) {
    console.info(reward.id, playerReward.countTotal);
}

Проверки

Награда выдана

gp.rewards.has(idOrTag)

// По ID
const hasReward = gp.rewards.has(123);
// По Тегу
const hasReward = gp.rewards.has('STARTER_PACK');

// Проверка
if (hasReward) {
    // есть награда STARTER_PACK
}

Награда принята

gp.rewards.hasAccepted(idOrTag)

// По ID
const hasAcceptedReward = gp.rewards.hasAccepted(123);
// По Тегу
const hasAcceptedReward = gp.rewards.hasAccepted('STARTER_PACK');

// Проверка
if (hasAcceptedReward) {
    // награда STARTER_PACK принята
}

Награда выдана, но не получена

gp.rewards.hasUnaccepted(idOrTag)

// По ID
const hasUnacceptedReward = gp.rewards.hasUnaccepted(123);
// По Тегу
const hasUnacceptedReward = gp.rewards.hasUnaccepted('STARTER_PACK');

// Проверка
if (hasUnacceptedReward) {
    // награда STARTER_PACK получена, но не принята
}

События

Награда выдана

Коллбек возвращает награду и награду игрока:

gp.rewards.on('give', ({ reward, playerReward }) => {
    // доступны награда и награда игрока
});

Не удалось выдать награду

Коллбек возвращает ошибку. См. коды ошибок:

gp.rewards.on('error:give', (err) => {
    // обработать ошибки
});

Награда принята

Коллбек возвращает награду и награду игрока:

gp.rewards.on('accept', ({ reward, playerReward }) => {
    // доступны награда и награда игрока
});

Не удалось принять награду

Коллбек возвращает ошибку. См. коды ошибок:

gp.rewards.on('error:accept', (err) => {
    // обработать ошибки
});

Типы

Поля награды

Поле	Тип	Описание	Пример
id	number	ID награды	115
tag	string	Тег для помощи при выборе. Вы можете использовать его вместо ID	VIP
name	string	Название, переведенное на язык пользователя	VIP Статус
description	string	Описание, переведенное на язык пользователя	Без рекламы, награда x2
icon	string	Ссылка на иконку размером 256x256	Пример ссылки
iconSmall	string	Ссылка на иконку размером 64x64	Пример ссылки
mutations	DataMutation[]	Список изменений переменных	[]
isAutoAccept	boolean	Автопринятие награды	true

Поля награды игрока

Поле	Тип	Описание	Пример
rewardId	number	ID Награды	115
countTotal	number	Количество выданных наград	23
countAccepted	number	Количество принятых наград	12

Поля мутации данных

DataMutation

Поле	Тип	Описание	Пример
type	MutationType	Тип мутации	PLAYER_FIELD
key	string	Ключ переменной для мутации	score
action	MutationAction	Тип действия в мутации	ADD
value	number / string / boolean	Изменяемое значение	100

Пример структуры:

const mutation: DataMutation = {
    type: MutationType.PLAYER_FIELD,
    key: 'score',
    action: MutationAction.ADD,
    value: 100,
};

// Будет эквивалентно записи:
gp.player.add('score', 100);

Типы мутации данных

MutationType

Тип	Описание
PLAYER_FIELD	Мутация полей игрока

Типы действий при мутации данных

MutationAction

Тип	Описание
ADD	Добавление значения к полю
REMOVE	Вычитание из поля / удаление поля
SET	Установка значения поля

Коды ошибок

Ошибка	Описание ошибки
player_not_found	Игрок не найден
empty_id_or_tag	Передан пустой ID или тег награды
reward_not_found	Награда с таким ID или тегом не найдена
undefined	Непредвиденная ошибка (смотрите консоль)

Оставайтесь на связи

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

Желаем вам успехов!