Перейти к основному содержимому

Награды API

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

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

Действия:

Свойства:

Проверки:

События:

Типы:

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

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

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

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

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

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

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

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

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(rewardTag);

    // Такой награды не существует
    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')) {
    // сделать что-нибудь при наличии скина нубика
}

Действия​

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

+1 Request

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

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

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

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

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

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

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

FREE

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

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

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

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

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

Свойства​

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

FREE

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

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

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

FREE

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

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

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

FREE

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

// По 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) FREE

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

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

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

gp.rewards.hasAccepted(idOrTag) FREE

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

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

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

gp.rewards.hasUnaccepted(idOrTag) FREE

// По 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) => {
    // обработать ошибки
});

Типы​

Поля награды​

ПолеТипОписаниеПример
idnumberID награды115
tagstringТег для помощи при выборе. Вы можете использовать его вместо IDVIP
namestringНазвание, переведенное на язык пользователяVIP Статус
descriptionstringОписание, переведенное на язык пользователяБез рекламы, награда x2
iconstringСсылка на иконку размером 256x256Пример ссылки
iconSmallstringСсылка на иконку размером 64x64Пример ссылки
mutationsDataMutation[]Список изменений переменных[]
isAutoAcceptbooleanАвтопринятие наградыtrue

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

ПолеТипОписаниеПример
rewardIdnumberID Награды115
countTotalnumberКоличество выданных наград23
countAcceptednumberКоличество принятых наград12

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

DataMutation

ПолеТипОписаниеПример
typeMutationTypeТип мутацииPLAYER_FIELD
keystringКлюч переменной для мутацииscore
actionMutationActionТип действия в мутацииADD
valuenumber / 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]

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