Reward Schedulers API
Integration of reward schedulers through SDK. Methods of operation.
List of methods
Actions:
gp.schedulers.register()
- registration in scheduler.gp.schedulers.claimDay()
- claim reward for the day.gp.schedulers.claimDayAdditional()
- claim reward for the day for additional activity.gp.schedulers.claimAllDay()
- claim reward for the day for all activities.gp.schedulers.claimAllDays()
- claim reward for all completed days at once.
Properties:
gp.schedulers.list
- list of schedulers.gp.schedulers.activeList
- list of player's active schedulers in which they are enrolled.gp.schedulers.getScheduler()
- get information about a scheduler by ID or tag.gp.schedulers.getSchedulerDay()
- get information about a specific day of the scheduler by ID or tag.gp.schedulers.getSchedulerCurrentDay()
- get information about the current day of the scheduler by ID or tag.
Checks:
gp.schedulers.on('register')
- subscribe to player registration in the scheduler.gp.schedulers.on('error:register')
- subscribe to error during registration in the scheduler.gp.schedulers.isRegistered()
- check if the player is participating in the scheduler.gp.schedulers.isTodayRewardClaimed()
- check if the reward for today has been claimed.gp.schedulers.canClaimDay()
- check if the reward for the day can be claimed.gp.schedulers.canClaimDayAdditional()
- check if the reward for additional activity for the day can be claimed.gp.schedulers.canClaimAllDay()
- check if the reward for any activity for the day can be claimed.
Events:
gp.schedulers.on('claimDay')
- subscribe to claim reward for the day event.gp.schedulers.on('error:claimDay')
- subscribe to error event when claiming reward for the day.gp.schedulers.on('claimDayAdditional')
- subscribe to claim reward for the day for additional activity event.gp.schedulers.on('error:claimDayAdditional')
- subscribe to error event when claiming reward for the day for additional activity.gp.schedulers.on('claimAllDay')
- subscribe to claim reward for the day for all activities event.gp.schedulers.on('error:claimAllDay')
- subscribe to error event when claiming reward for the day for all activities.gp.schedulers.on('claimAllDays')
- subscribe to claim reward for all days event.gp.schedulers.on('error:claimAllDays')
- subscribe to error event when claiming reward for all days.
Types:
Scheduler
- scheduler fields.PlayerScheduler
- player's scheduler fields. Personal information about the scheduler.SchedulerInfo
- current progress status of the scheduler.SchedulerDayInfo
- current progress status of the scheduler day.SchedulerType
- scheduler type.
Tips for working with schedulers
Subscribing to reward acceptance events
Depending on the method of accepting rewards, callbacks will be called in order.
If you accept a reward for the day gp.schedulers.claimDay()
, then the callback will be triggered:
If you accept all rewards for the day gp.schedulers.on('claimAllDay')
, then the following callbacks will be triggered:
If you accept all rewards for all days gp.schedulers.claimAllDays()
, then callbacks will be triggered for each day and a general callback for all days:
gp.schedulers.on('claimDay')
gp.schedulers.on('claimDayAdditional')
gp.schedulers.on('claimAllDay')
gp.schedulers.on('claimAllDays')
Callbacks will be triggered if you can receive a reward for the day / trigger / entire day. If a reward cannot be obtained, then the callback will be skipped for that day / trigger or entire day.
Example of rendering a reward scheduler
Let's imagine that we need to implement a reward scheduler like the one in the image:
- Mark reached days as colored
- Mark all days for which a reward has been received with a checkmark
- Mark the remaining days as gray
- Add a "claim reward" button
// When a reward is claimed - update the reward scheduler view
gp.schedulers.on('claimDay', () => renderScheduler('DAILY_7'));
// Function for rendering the scheduler
function renderScheduler(schedulerTag) {
const { scheduler } = gp.schdulers.getScheduler(schedulerTag);
// Iterate over each day of the scheduler
for (let day = 1; day <= scheduler.days; day++) {
// Get information about the day
const schedulerDayInfo = gp.schdulers.getSchedulerDay(schedulerTag, day);
const { isDayReached, isDayClaimed, canClaimDay, bonuses } = schedulerDayInfo;
// Take the first bonus to draw the image
const [firstBonus] = bonuses;
// Draw the reward
const drawnBonus = myGame.drawBonus(firstBonus);
// Mark the day as reached if reached (black and white if not reached)
drawnBonus.setColored(isDayReached);
// Mark the reward as claimed if it is claimed (not marked if not claimed)
drawnBonus.setChecked(isDayClaimed);
// If the reward can be claimed - draw the claim button
if (canClaimDay) {
const drawnButton = drawnBonus.drawClaimButton();
// When the button is clicked - claim the reward
drawnButton.onClick(() => gp.schedulers.claimDay(scheduler.id, day));
}
}
}
renderScheduler('DAILY_7');
Actions
Registration in Scheduler
By default, players are automatically registered in the scheduler when they enter the game, and their countdown begins. If there is a need to enable different schedulers, you can disable automatic registration and register the player at the desired moment.
Examples of scenarios:
- Special reward scheduler during an event.
- After completing the main scheduler for all hardcore players, provide more substantial rewards.
- Different schedulers for different audiences. For example, activate an additional reward scheduler when segmenting players or purchasing VIP.
// By ID
gp.schedulers.register({ id: 123 });
// By tag
gp.schedulers.register({ tag: 'DAILY_30' });
The method returns the current status of the scheduler.
const schedulerInfo = await gp.schedulers.register({ tag: 'DAILY_30' });
Claim reward for the day
gp.schedulers.claimDay(idOrTag, day);
This method returns the current status of the scheduler day.
// By ID
const schedulerDayInfo = await gp.schedulers.claimDay(123, 3);
// By Tag
const schedulerDayInfo = await gp.schedulers.claimDay('DAILY_30', 3);
Claim reward for the day for additional activity
gp.schedulers.claimDayAdditional(idOrTag, day, triggerIdOrTag);
This method returns the current status of the scheduler day.
// By ID
const schedulerDayInfo = await gp.schedulers.claimDayAdditional(123, 3, 'PLAYTIME_30_DAY_3');
// By Tag
const schedulerDayInfo = await gp.schedulers.claimDayAdditional('DAILY_30', 3, 'PLAYTIME_30_DAY_3');
Claim reward for all activities on the day
gp.schedulers.claimAllDay(idOrTag, day);
This method returns the current status of the scheduler day.
// By ID
const schedulerDayInfo = await gp.schedulers.claimAllDay(123, 3);
// By Tag
const schedulerDayInfo = await gp.schedulers.claimAllDay('DAILY_30', 3);
Claim reward for all completed days
gp.schedulers.claimAllDays(idOrTag);
This method returns the current status of the scheduler.
// By ID
const schedulerInfo = await gp.schedulers.claimAllDays(123);
// By Tag
const schedulerInfo = await gp.schedulers.claimAllDays('DAILY_30');
Properties
List of schedulers
You have access to the entire list of schedulers when the game starts. See scheduler fields.
gp.schedulers.list.forEach((scheduler) => {
// scheduler.id
// scheduler.tag
// scheduler.type
// scheduler.days
// scheduler.isRepeat
// scheduler.triggers
});
List of player active schedulers
You have access to the entire list of schedulers that the player is registered in when the player is ready. See player scheduler fields.
gp.schedulers.activeList.forEach((playerScheduler) => {
// playerScheduler.schedulerId
// playerScheduler.stats.activeDays
// playerScheduler.stats.activeDaysConsecutive
});
Get scheduler information
gp.schedulers.getScheduler(idOrTag);
This method returns the current status of the scheduler.
// By ID
const schedulerInfo = gp.schedulers.getScheduler(123);
// By Tag
const schedulerInfo = gp.schedulers.getScheduler('DAILY_30');
const { scheduler, isRegistered, stats, daysClaimed, currentDay } = schedulerInfo;
// The scheduler may not exist, make sure it exists
if (scheduler) {
console.info(scheduler.id, isRegistered, stats.activeDays);
}
Get scheduler day information
gp.schedulers.getSchedulerDay(idOrTag, day);
This method returns the current status of the scheduler day.
// By ID
const schedulerDayInfo = gp.schedulers.getSchedulerDay(123, 3);
// By Tag
const schedulerDayInfo = gp.schedulers.getSchedulerDay('DAILY_30', 3);
const {
scheduler,
day,
isDayReached,
isDayComplete,
isDayClaimed,
isAllDayClaimed,
canClaimDay,
canClaimAllDay,
bonuses,
triggers,
} = schedulerDayInfo;
// The scheduler may not exist, make sure it exists
if (scheduler) {
console.info(scheduler.id, day, canClaimDay);
}
Get information about the current scheduler day
gp.schedulers.getSchedulerCurrentDay(idOrTag);
This method returns the current status of the scheduler day.
// By ID
const schedulerDayInfo = gp.schedulers.getSchedulerDay(123);
// By Tag
const schedulerDayInfo = gp.schedulers.getSchedulerDay('DAILY_30');
const {
scheduler,
day,
isDayReached,
isDayComplete,
isDayClaimed,
isAllDayClaimed,
canClaimDay,
canClaimAllDay,
bonuses,
triggers,
} = schedulerDayInfo;
// The scheduler may not exist, make sure it exists
if (scheduler) {
console.info(scheduler.id, day, canClaimDay);
}
Checks
Player participates in the scheduler
gp.schedulers.isRegistered(idOrTag);
// By ID
const isRegistered = gp.schedulers.isRegistered(123);
// By Tag
const isRegistered = gp.schedulers.isRegistered('DAILY_30');
// Check
if (isRegistered) {
// Player participates in the DAILY_30 scheduler
}
Today's reward claimed
gp.schedulers.isTodayRewardClaimed(idOrTag);
Check if today's reward has been claimed in the selected scheduler.
// By ID
const isClaimed = gp.schedulers.isTodayRewardClaimed(123);
// By Tag
const isClaimed = gp.schedulers.isTodayRewardClaimed('DAILY_30');
// Check
if (isClaimed) {
// Today's login reward has already been claimed in the DAILY_30 scheduler
}
Can claim reward for the day
gp.schedulers.canClaimDay(idOrTag, day);
Check if the reward for the day can be claimed in the selected scheduler.
// By ID
const canClaim = gp.schedulers.canClaimDay(123, 15);
// By Tag
const canClaim = gp.schedulers.canClaimDay('DAILY_30', 15);
// Check
if (canClaim) {
// The reward for day 15 can be claimed in the DAILY_30 scheduler
}
Can claim reward for additional activity for the day
gp.schedulers.canClaimDayAdditional(idOrTag, day, triggerIdOrTag);
Check if the reward for additional activity (trigger) for the day can be claimed in the selected scheduler.
// By ID
const canClaim = gp.schedulers.canClaimDayAdditional(123, 3, 'PLAYTIME_30_DAY_3');
// By Tag
const canClaim = gp.schedulers.canClaimDayAdditional('DAILY_30', 3, 'PLAYTIME_30_DAY_3');
// Check
if (canClaim) {
// The reward for day 3 in the DAILY_30 scheduler can be claimed based on the PLAYTIME_30_DAY_3 trigger
}
Can claim rewards for all activities for the day
gp.schedulers.canClaimAllDay(idOrTag, day);
Check if the reward for any activity for the day can be claimed.
// By ID
const canClaim = gp.schedulers.canClaimAllDay(123, 15);
// By Tag
const canClaim = gp.schedulers.canClaimAllDay('DAILY_30', 15);
// Check
if (canClaim) {
// The reward for day 15 can be claimed in the DAILY_30 scheduler for login or completed activity
}
Events
Player Registered in Scheduler
The callback returns the current status of the scheduler:
gp.schedulers.on('register', (schedulerInfo) => {
// access the current status of the scheduler
});
Failed to Register in Scheduler
The callback returns an error. See error codes:
gp.schedulers.on('error:register', (err) => {
// handle errors
});
Reward for the day claimed
Callback returns current status of the scheduler day:
gp.schedulers.on('claimDay', (schedulerDayInfo) => {
// Current status of the scheduler day is accessible
});
Failed to claim reward for the day
Callback returns an error. See error codes:
gp.schedulers.on('error:claimDay', (err) => {
// Handle errors
});
Reward for additional activity for the day claimed
Callback returns current status of the scheduler day:
gp.schedulers.on('claimDayAdditional', (schedulerDayInfo) => {
// Current status of the scheduler day is accessible
});
Failed to claim reward for additional activity for the day
Callback returns an error. See error codes:
gp.schedulers.on('error:claimDayAdditional', (err) => {
// Handle errors
});
Reward for all activities for the day claimed
Callback returns current status of the scheduler day:
gp.schedulers.on('claimAllDay', (schedulerDayInfo) => {
// Current status of the scheduler day is accessible
});
Failed to claim reward for all activities for the day
Callback returns an error. See error codes:
gp.schedulers.on('error:claimAllDay', (err) => {
// Handle errors
});
Rewards for all days claimed
Callback returns current status of the scheduler:
gp.schedulers.on('claimAllDays', (schedulerDayInfo) => {
// Current status of the scheduler is accessible
});
Failed to claim rewards for all days
Callback returns an error. See error codes:
gp.schedulers.on('error:claimAllDays', (err) => {
// Handle errors
});
Player joined the event
Callback returns scheduler event and player scheduler event:
gp.schedulers.on('join', ({ scheduler, playerScheduler }) => {
// Scheduler event and player scheduler event are accessible
});
Failed to join the event
Callback returns an error. See error codes:
gp.schedulers.on('error:join', (err) => {
// Handle errors
});
Types
Scheduler Fields
Field | Type | Description | Example |
---|---|---|---|
id | number | Scheduler ID | 115 |
tag | string | Tag for reference. Can be used instead of ID | DAILY_30 |
type | SchedulerType | Scheduler type (by number of days or consecutive days) | ACTIVE_DAYS |
days | number | Number of days in the scheduler | 30 |
isRepeat | boolean | Repeatable? After completing the cycle, it starts over from day 1 | true |
isAutoRegister | boolean | The player is automatically registered in the scheduler upon game startup. | true |
triggers | Trigger[] | List of scheduler triggers | [] |
Player Scheduler Fields
Field | Type | Description | Example |
---|---|---|---|
schedulerId | number | Event ID | 115 |
daysClaimed | number[] | List of days for which rewards have been claimed | [1,2,3,4] |
stats | PlayerStats | Player's stats in the scheduler | { activeDays: 4, activeDaysConsecutive: 3} |
Scheduler Information Fields
Field | Type | Description | Example |
---|---|---|---|
scheduler | Scheduler | The scheduler | |
stats | PlayerStats | Player's stats in the scheduler | { activeDays: 4, activeDaysConsecutive: 3} |
daysClaimed | number[] | List of days for which rewards have been claimed | [1,2,3,4] |
isRegistered | boolean | Whether the player is participating in the scheduler | true |
currentDay | number | The current day in the player's scheduler | true |
Scheduler Day Information Fields
Field | Type | Description | Example |
---|---|---|---|
scheduler | Scheduler | The scheduler | |
day | number | Selected day | 4 |
isDayReached | boolean | Whether the player has reached this day | true |
isDayComplete | boolean | Whether all day activities are completed (login + all triggers) | true |
isDayClaimed | boolean | Whether the reward for logging in on this day has been claimed | true |
isAllDayClaimed | boolean | Whether all rewards for the day have been claimed | true |
canClaimDay | boolean | Whether the reward for logging in can be claimed | true |
canClaimAllDay | boolean | Whether all rewards for the day can be claimed | true |
bonuses | Bonus[] | List of login bonuses | [] |
triggers | Trigger[] | List of triggers for the selected day | [] |
Scheduler Type
Type | Description |
---|---|
ACTIVE_DAYS | By number of active days |
ACTIVE_DAYS_CONSECUTIVE | By number of consecutive active days |
Error Codes
Error | Error Description |
---|---|
player_not_found | Player not found |
empty_id_or_tag | Empty ID or tag passed |
scheduler_not_found | Scheduler with provided ID or tag not found |
wrong_day | Invalid day provided |
day_not_reached | Player hasn't reached this day yet |
day_already_claimed | Reward for the day has already been claimed |
nothing_to_claim | No rewards to claim (already claimed or not found) |
failed_to_claim | Failed to claim reward (check console for details) |
trigger_not_found | Trigger with provided ID or tag not found |
trigger_not_activated | Trigger not activated |
trigger_already_claimed | Reward for the trigger has already been claimed |
undefined | Unexpected error occurred (check console for details) |
Stay in Touch
Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.
GamePush Community Telegram
: @gs_community.
For your suggestions e-mail
: [email protected]
We Wish you Success!