Планировщики наград API
Интеграция планировщиков наград через SDK. Методы работы.
Список методов
Действия:
gp.schedulers.register()
- регистрация в планировщике.gp.schedulers.claimDay()
- принять награду за день.gp.schedulers.claimDayAdditional()
- принять награду за день за дополнительную активность.gp.schedulers.claimAllDay()
- принять награду за день за все активности.gp.schedulers.claimAllDays()
- принять награду за все выполненные дни сразу.
Свойства:
gp.schedulers.list
- список планировщиков.gp.schedulers.activeList
- список планировщиков игрока, в которых он зарегистрирован.gp.schedulers.getScheduler()
- получить информацию о планировщике по ID или тегу.gp.schedulers.getSchedulerDay()
- получить информацию о нужном дне планировщика по ID или тегу.gp.schedulers.getSchedulerCurrentDay()
- получить информацию о текущем дне планировщика по ID или тегу.
Проверки:
gp.schedulers.isRegistered()
- проверить участвует ли игрок в планировщике.gp.schedulers.isTodayRewardClaimed()
- проверить принята ли сегодня награда.gp.schedulers.canClaimDay()
- проверить можно ли забрать награду за день.gp.schedulers.canClaimDayAdditional()
- проверить можно ли забрать награду за дополнительную активность за день.gp.schedulers.canClaimAllDay()
- проверить можно ли забрать награду за какую-нибудь активность за день.
События:
gp.schedulers.on('register')
- подписаться на регистрацию игрока в планировщике.gp.schedulers.on('error:register')
- подписаться на ошибку при регистрации в планировщике.gp.schedulers.on('claimDay')
- подписаться на принятие награды за день.gp.schedulers.on('error:claimDay')
- подписаться на ошибку при принятии награды за день.gp.schedulers.on('claimDayAdditional')
- подписаться на принятие награды за день за дополнительную активность.gp.schedulers.on('error:claimDayAdditional')
- подписаться на ошибку при принятии награды за день за дополнительную активность.gp.schedulers.on('claimAllDay')
- подписаться на принятие награды за день за все активности.gp.schedulers.on('error:claimAllDay')
- подписаться на ошибку при принятии награды за день за все активности.gp.schedulers.on('claimAllDays')
- подписаться на принятие награды за все дни.gp.schedulers.on('error:claimAllDays')
- подписаться на ошибку при принятии награды за все дни.
Типы:
Scheduler
- поля планировщика.PlayerScheduler
- поля планировщика игрока. Персональная информация о планировщике.SchedulerInfo
- текущий статус прохождения планировщика.SchedulerDayInfo
- текущий статус прохождения дня планировщика.SchedulerType
- тип планировщика.
Советы при работе с планировщиками
Подписка на события о принятии наград
В зависимости от вызова метода принятия наград будут вызваны поочередно коллбеки.
Если принять награду за день gp.schedulers.claimDay()
, то сработает коллбек:
Если принять все награды за день gp.schedulers.claimAllDay()
, то сработают коллбеки:
Если принять все награды за все дни gp.schedulers.claimAllDays()
, то сработают коллбеки для каждого дня и общий для всех дней:
gp.schedulers.on('claimDay')
gp.schedulers.on('claimDayAdditional')
gp.schedulers.on('claimAllDay')
gp.schedulers.on('claimAllDays')
Коллбеки сработают, если можно получить награду за день / триггер / весь день. Если награду нельзя получить, то для этого дня / триггера или всего дня коллбек будет пропущен.
Пример отрисовки планировщика наград
Представим, что нужно реализовать планировщик наград как на картинке:
- Достигнутые дни пометим цветными
- Все дни, за которые получена награда пометим галкой
- Остальные дни пометим серым
- Добавим кнопку "забрать награду"
// При принятии награды - обновляем представление планировщика
gp.schedulers.on('claimDay', () => renderScheduler('DAILY_7'));
// Функция отисовки планировщика
function renderScheduler(schedulerTag) {
const { scheduler } = gp.schdulers.getScheduler(schedulerTag);
// Проходимся по каждому дню планировшика
for (let day = 1; day <= scheduler.days; day++) {
// Получаем информацию о дне
const schedulerDayInfo = gp.schdulers.getSchedulerDay(schedulerTag, day);
const { isDayReached, isDayClaimed, canClaimDay, bonuses } = schedulerDayInfo;
// Берем первый бонус для отрисовки картинки
const [firstBonus] = bonuses;
// Рисуем награду
const drawnBonus = myGame.drawBonus(firstBonus);
// День достигнут, пометим цветным (не достингут - черно белым)
drawnBonus.setColored(isDayReached);
// Награда получена - пометим галкой (не получена - не пометим)
drawnBonus.setChecked(isDayClaimed);
// Можно забрать награду - рисуем кнопку принятия награды
if (canClaimDay) {
const drawnButton = drawnBonus.drawClaimButton();
// При клике на кнопку - принимаем награду
drawnButton.onClick(() => gp.schedulers.claimDay(scheduler.id, day));
}
}
}
renderScheduler('DAILY_7');
Действия
Регистрация в планировщике
По-умолчанию игрок автоматически регистрируется в планировщике при заходе в игру и затем у него начинается отсчет дней. Если есть необходимость включать разные планировщики, то вы можете отключить у них автоматическую регистрацию и регистрировать игрока в нужный момент.
Примеры сценариев:
- Специальный планировщик наград пока идет мероприятие.
- После прохождения основного планировщика для всех заядлых игроков выдавать более весомые награды.
- Разные планировщики на разную аудиторию. Например, при сегментации игроков или при покупке VIP активировать дополнительный планировщик наград.
// По ID
gp.schedulers.register({ id: 123 });
// По тегу
gp.schedulers.register({ tag: 'DAILY_30' });
Метод возвращает текущий статус планировщика.
const schedulerInfo = await gp.schedulers.register({ tag: 'DAILY_30' });
Принять награду за день
gp.schedulers.claimDay(idOrTag, day);
Метод возвращает текущий статус дня планировщика.
// По ID
const schedulerDayInfo = await gp.schedulers.claimDay(123, 3);
// По Тегу
const schedulerDayInfo = await gp.schedulers.claimDay('DAILY_30', 3);
Принять награду за день за дополнительную активность
gp.schedulers.claimDayAdditional(idOrTag, day, triggerIdOrTag);
Метод возвращает текущий статус дня планировщика.
// По ID
const schedulerDayInfo = await gp.schedulers.claimDayAdditional(123, 3, 'PLAYTIME_30_DAY_3');
// По Тегу
const schedulerDayInfo = await gp.schedulers.claimDayAdditional('DAILY_30', 3, 'PLAYTIME_30_DAY_3');
Принять награду за день за все активности
gp.schedulers.claimAllDay(idOrTag, day);
Метод возвращает текущий статус дня планировщика.
// По ID
const schedulerDayInfo = await gp.schedulers.claimAllDay(123, 3);
// По Тегу
const schedulerDayInfo = await gp.schedulers.claimAllDay('DAILY_30', 3);
Принять награду за все выполненные дни
gp.schedulers.claimAllDays(idOrTag);
Метод возвращает текущий статус планировщика.
// По ID
const schedulerInfo = await gp.schedulers.claimAllDays(123);
// По Тегу
const schedulerInfo = await gp.schedulers.claimAllDays('DAILY_30');
Свойства
Список планировщиков
Вам доступен весь список планировщиков сразу при запуске игры. См. поля планировщика.
gp.schedulers.list.forEach((scheduler) => {
// scheduler.id
// scheduler.tag
// scheduler.type
// scheduler.days
// scheduler.isRepeat
// scheduler.triggers
});
Список активных планировщиков игрока
Вам доступен весь список планировщиков, в которых игрок зарегистрирован, сразу при готовности игрока. См. поля планировщика игрока.
gp.schedulers.activeList.forEach((playerScheduler) => {
// playerScheduler.schedulerId
// playerScheduler.stats.activeDays
// playerScheduler.stats.activeDaysConsecutive
});
Получение информации о планировщике
gp.schedulers.getScheduler(idOrTag);
Метод возвращает текущий статус планировщика.
// По ID
const schedulerInfo = gp.schedulers.getScheduler(123);
// По Тегу
const schedulerInfo = gp.schedulers.getScheduler('DAILY_30');
const { scheduler, isRegistered, stats, daysClaimed, currentDay } = schedulerInfo;
// Планировщика может не существовать, убедитесь, что он есть
if (scheduler) {
console.info(scheduler.id, isRegistered, stats.activeDays);
}
Получение информации о дне планировщика
gp.schedulers.getSchedulerDay(idOrTag, day);
Метод возвращает текущий статус дня планировщика.
// По ID
const schedulerDayInfo = gp.schedulers.getSchedulerDay(123, 3);
// По Тегу
const schedulerDayInfo = gp.schedulers.getSchedulerDay('DAILY_30', 3);
const {
scheduler,
day,
isDayReached,
isDayComplete,
isDayClaimed,
isAllDayClaimed,
canClaimDay,
canClaimAllDay,
bonuses,
triggers,
} = schedulerDayInfo;
// Планировщика может не существовать, убедитесь, что он есть
if (scheduler) {
console.info(scheduler.id, day, canClaimDay);
}
Получение информации о текущем дне планировщика
gp.schedulers.getSchedulerCurrentDay(idOrTag);
Метод возвращает текущий статус дня планировщика.
// По ID
const schedulerDayInfo = gp.schedulers.getSchedulerDay(123);
// По Тегу
const schedulerDayInfo = gp.schedulers.getSchedulerDay('DAILY_30');
const {
scheduler,
day,
isDayReached,
isDayComplete,
isDayClaimed,
isAllDayClaimed,
canClaimDay,
canClaimAllDay,
bonuses,
triggers,
} = schedulerDayInfo;
// Планировщика может не существовать, убедитесь, что он есть
if (scheduler) {
console.info(scheduler.id, day, canClaimDay);
}
Проверки
Игрок участвует в планировщике
gp.schedulers.isRegistered(idOrTag);
// По ID
const isRegistered = gp.schedulers.isRegistered(123);
// По Тегу
const isRegistered = gp.schedulers.isRegistered('DAILY_30');
// Проверка
if (isRegistered) {
// Игрок участвует в планировщике DAILY_30
}
Сегодня принята награда
gp.schedulers.isTodayRewardClaimed(idOrTag);
Проверить принята ли сегодня награда в выбранном планировщике.
// По ID
const isClaimed = gp.schedulers.isTodayRewardClaimed(123);
// По Тегу
const isClaimed = gp.schedulers.isTodayRewardClaimed('DAILY_30');
// Проверка
if (isClaimed) {
// Сегодня награда за вход уже принята в планировщике DAILY_30
}
Можно забрать награду за день
gp.schedulers.canClaimDay(idOrTag, day);
Проверить можно ли забрать награду за день в выбранном планировщике.
// По ID
const canClaim = gp.schedulers.canClaimDay(123, 15);
// По Тегу
const canClaim = gp.schedulers.canClaimDay('DAILY_30', 15);
// Проверка
if (canClaim) {
// можно принять награду за 15 день в планировщике DAILY_30
}
Можно забрать награду за дополнительную активность за день
gp.schedulers.canClaimDayAdditional(idOrTag, day, triggerIdOrTag);
Проверить можно ли забрать награду за дополнительную активность (триггер) за день в выбранном планировщике.
// По ID
const canClaim = gp.schedulers.canClaimDayAdditional(123, 3, 'PLAYTIME_30_DAY_3');
// По Тегу
const canClaim = gp.schedulers.canClaimDayAdditional('DAILY_30', 3, 'PLAYTIME_30_DAY_3');
// Проверка
if (canClaim) {
// можно принять награду за 3 день в планировщике DAILY_30 по триггеру PLAYTIME_30_DAY_3
}
Можно забрать награду за все активности за день
gp.schedulers.canClaimAllDay(idOrTag, day);
Проверить можно ли забрать награду за какую-нибудь активность за день.
// По ID
const canClaim = gp.schedulers.canClaimAllDay(123, 15);
// По Тегу
const canClaim = gp.schedulers.canClaimAllDay('DAILY_30', 15);
// Проверка
if (canClaim) {
// можно принять награду за 15 день в планировщике DAILY_30 за вход либо за выполненную активность
}
События
Игрок зарегистрировался в планировщике
Коллбек возвращает текущий статус планировщика:
gp.schedulers.on('register', (schedulerInfo) => {
// доступен текущий статус планировщика
});
Не удалось зарегистрироваться в планировщике
Коллбек возвращает ошибку. См. коды ошибок:
gp.schedulers.on('error:register', (err) => {
// обработать ошибки
});
Награда за день принята
Коллбек возвращает текущий статус дня планировщика:
gp.schedulers.on('claimDay', (schedulerDayInfo) => {
// доступен текущий статус дня планировщика
});
Не удалось принять награду за день
Коллбек возвращает ошибку. См. коды ошибок:
gp.schedulers.on('error:claimDay', (err) => {
// обработать ошибки
});
Награда за день за дополнительную активность принята
Коллбек возвращает текущий статус дня планировщика:
gp.schedulers.on('claimDayAdditional', (schedulerDayInfo) => {
// доступен текущий статус дня планировщика
});
Не удалось принять награду за день за дополнительную активность
Коллбек возвращает ошибку. См. коды ошибок:
gp.schedulers.on('error:claimDayAdditional', (err) => {
// обработать ошибки
});
Награда за день за все активности принята
Коллбек возвращает текущий статус дня планировщика:
gp.schedulers.on('claimAllDay', (schedulerDayInfo) => {
// доступен текущий статус дня планировщика
});
Не удалось принять награду за день за все активности
Коллбек возвращает ошибку. См. коды ошибок:
gp.schedulers.on('error:claimAllDay', (err) => {
// обработать ошибки
});
Награда за все дни принята
Коллбек возвращает текущий статус планировщика:
gp.schedulers.on('claimAllDays', (schedulerDayInfo) => {
// доступен текущий статус планировщика
});
Не удалось принять награду за все дни
Коллбек возвращает ошибку. См. коды ошибок:
gp.schedulers.on('error:claimAllDays', (err) => {
// обработать ошибки
});
Игрок присоединился к событию
Коллбек возвращает событие и событие игрока:
gp.schedulers.on('join', ({ scheduler, playerScheduler }) => {
// доступны событие и событие игрока
});
Не удалось вступить в событие
Коллбек возвращает ошибку. См. коды ошибок:
gp.schedulers.on('error:join', (err) => {
// обработать ошибки
});
Типы
Поля планировщика
Поле | Тип | Описание | Пример |
---|---|---|---|
id | number | ID планировщика | 115 |
tag | string | Тег для помощи при выборе. Вы можете использовать его вместо ID | DAILY_30 |
type | SchedulerType | Тип планировщика (по количеству дней или количеству дней подряд) | ACTIVE_DAYS |
days | number | Количество дней в планировщике | 30 |
isRepeat | boolean | Повторяемый? После завершения цикла - начнется заново с 1 дня | true |
isAutoRegister | boolean | Игрок автоматически регистрируется в планировщике при входе | true |
triggers | Trigger[] | Список триггеров планировщика | [] |
Поля планировщика игрока
Поле | Тип | Описание | Пример |
---|---|---|---|
schedulerId | number | ID События | 115 |
daysClaimed | number[] | Список дней, за которые была получена награда | [1,2,3,4] |
stats | PlayerStats | Статистика игрока в планировщике | { activeDays: 4, activeDaysConsecutive: 3} |
Поля информации о планировщике
Поле | Тип | Описание | Пример |
---|---|---|---|
scheduler | Scheduler | Планировщик | |
stats | PlayerStats | Статистика игрока в планировщике | { activeDays: 4, activeDaysConsecutive: 3} |
daysClaimed | number[] | Список дней, за которые была получена награда | [1,2,3,4] |
isRegistered | boolean | Игрок участвует в планировщике | true |
currentDay | number | Текущий день в планировщщике у игрока | true |
Поля информации о дне планировщика
Поле | Тип | Описание | Пример |
---|---|---|---|
scheduler | Scheduler | Планировщик | |
day | number | Выбранный день | 4 |
isDayReached | boolean | Игрок достиг этого дня | true |
isDayComplete | boolean | Все активности дня выполнены (вход + все дополнительные триггеры) | true |
isDayClaimed | boolean | Награда за вход получена | true |
isAllDayClaimed | boolean | Все награды за день получены за все активности | true |
canClaimDay | boolean | Можно забрать награду за вход | true |
canClaimAllDay | boolean | Можно забрать награду за все активности | true |
bonuses | Bonus[] | Список бонусов за вход | [] |
triggers | Trigger[] | Список триггеров выбранного дня | [] |
Тип планировщика
Тип | Описание |
---|---|
ACTIVE_DAYS | По количеству дней активности |
ACTIVE_DAYS_CONSECUTIVE | По количеству дней активности подряд |
Коды ошибок
Ошибка | Описание ошибки |
---|---|
player_not_found | Игрок не найден |
empty_id_or_tag | Передан пустой ID или тег планировщика |
scheduler_not_found | Планировщик с таким ID или тегом не найден |
wrong_day | Передан несуществующий день планировщика |
day_not_reached | Игрок еще не дошел до этого дня |
day_already_claimed | Награда за день уже получена |
nothing_to_claim | Нет наград для получения (уже получены или не найдены) |
failed_to_claim | Не удалось получить награду (смотрите консоль) |
trigger_not_found | Триггер с таким ID или тегом не найден |
trigger_not_activated | Триггер не активирован |
trigger_already_claimed | Награда уже получена |
undefined | Непредвиденная ошибка (смотрите консоль) |
Оставайтесь на связи
С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.
Сообщество GamePush в Telegram
: @gs_community.
Для ваших обращений e-mail
: [email protected]
Желаем вам успехов!