Skip to main content

Reward Schedulers API

Integration of reward schedulers through SDK. Methods of operation.

List of methods​

Actions:

Properties:

Checks:

Events:

Types:

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 ss.schedulers.claimDay(), then the callback will be triggered:

If you accept all rewards for the day ss.schedulers.on('claimAllDay'), then the following callbacks will be triggered:

If you accept all rewards for all days ss.schedulers.claimAllDays(), then callbacks will be triggered for each day and a general callback for all days:

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
ss.schedulers.on('claimDay', () => renderScheduler('DAILY_7'));

// Function for rendering the scheduler
function renderScheduler(schedulerTag) {
    const { scheduler } = ss.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 = ss.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(() =>
                ss.schedulers.claimDay(scheduler.id, day)
            );
        }
    }
}

renderScheduler('DAILY_7');

Actions​

Registration in Scheduler​

+1 Request

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
ss.schedulers.register({ id: 123 });
// By tag
ss.schedulers.register({ tag: 'DAILY_30' });

The method returns the current status of the scheduler.

const schedulerInfo = await ss.schedulers.register({ tag: 'DAILY_30' });

Claim reward for the day​

+Lazy Sync Request
ss.schedulers.claimDay(idOrTag, day);

This method returns the current status of the scheduler day.

// By ID
const schedulerDayInfo = await ss.schedulers.claimDay(123, 3);
// By Tag
const schedulerDayInfo = await ss.schedulers.claimDay('DAILY_30', 3);

Claim reward for the day for additional activity​

+Lazy Sync Request
ss.schedulers.claimDayAdditional(idOrTag, day, triggerIdOrTag);

This method returns the current status of the scheduler day.

// By ID
const schedulerDayInfo = await ss.schedulers.claimDayAdditional(
    123,
    3,
    'PLAYTIME_30_DAY_3'
);
// By Tag
const schedulerDayInfo = await ss.schedulers.claimDayAdditional(
    'DAILY_30',
    3,
    'PLAYTIME_30_DAY_3'
);

Claim reward for all activities on the day​

+Lazy Sync Request
ss.schedulers.claimAllDay(idOrTag, day);

This method returns the current status of the scheduler day.

// By ID
const schedulerDayInfo = await ss.schedulers.claimAllDay(123, 3);
// By Tag
const schedulerDayInfo = await ss.schedulers.claimAllDay('DAILY_30', 3);

Claim reward for all completed days​

+Lazy Sync Request
ss.schedulers.claimAllDays(idOrTag);

This method returns the current status of the scheduler.

// By ID
const schedulerInfo = await ss.schedulers.claimAllDays(123);
// By Tag
const schedulerInfo = await ss.schedulers.claimAllDays('DAILY_30');

Properties​

List of schedulers​

FREE

You have access to the entire list of schedulers when the game starts. See scheduler fields.

ss.schedulers.list.forEach((scheduler) => {
    // scheduler.id
    // scheduler.tag
    // scheduler.type
    // scheduler.days
    // scheduler.isRepeat
    // scheduler.triggers
});

List of player active schedulers​

FREE

You have access to the entire list of schedulers that the player is registered in when the player is ready. See player scheduler fields.

ss.schedulers.activeList.forEach((playerScheduler) => {
    // playerScheduler.schedulerId
    // playerScheduler.stats.activeDays
    // playerScheduler.stats.activeDaysConsecutive
});

Get scheduler information​

FREE
ss.schedulers.getScheduler(idOrTag);

This method returns the current status of the scheduler.

// By ID
const schedulerInfo = ss.schedulers.getScheduler(123);
// By Tag
const schedulerInfo = ss.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​

FREE
ss.schedulers.getSchedulerDay(idOrTag, day);

This method returns the current status of the scheduler day.

// By ID
const schedulerDayInfo = ss.schedulers.getSchedulerDay(123, 3);
// By Tag
const schedulerDayInfo = ss.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​

FREE
ss.schedulers.getSchedulerCurrentDay(idOrTag);

This method returns the current status of the scheduler day.

// By ID
const schedulerDayInfo = ss.schedulers.getSchedulerCurrentDay(123);
// By Tag
const schedulerDayInfo = ss.schedulers.getSchedulerCurrentDay('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​

FREE
ss.schedulers.isRegistered(idOrTag);
// By ID
const isRegistered = ss.schedulers.isRegistered(123);
// By Tag
const isRegistered = ss.schedulers.isRegistered('DAILY_30');

// Check
if (isRegistered) {
    // Player participates in the DAILY_30 scheduler
}

Today's reward claimed​

FREE
ss.schedulers.isTodayRewardClaimed(idOrTag);

Check if today's reward has been claimed in the selected scheduler.

// By ID
const isClaimed = ss.schedulers.isTodayRewardClaimed(123);
// By Tag
const isClaimed = ss.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​

FREE
ss.schedulers.canClaimDay(idOrTag, day);

Check if the reward for the day can be claimed in the selected scheduler.

// By ID
const canClaim = ss.schedulers.canClaimDay(123, 15);
// By Tag
const canClaim = ss.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​

FREE
ss.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 = ss.schedulers.canClaimDayAdditional(
    123,
    3,
    'PLAYTIME_30_DAY_3'
);
// By Tag
const canClaim = ss.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​

FREE
ss.schedulers.canClaimAllDay(idOrTag, day);

Check if the reward for any activity for the day can be claimed.

// By ID
const canClaim = ss.schedulers.canClaimAllDay(123, 15);
// By Tag
const canClaim = ss.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:

ss.schedulers.on('register', (schedulerInfo) => {
    // access the current status of the scheduler
});

Failed to Register in Scheduler​

The callback returns an error. See error codes:

ss.schedulers.on('error:register', (err) => {
    // handle errors
});

Reward for the day claimed​

Callback returns current status of the scheduler day:

ss.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:

ss.schedulers.on('error:claimDay', (err) => {
    // Handle errors
});

Reward for additional activity for the day claimed​

Callback returns current status of the scheduler day:

ss.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:

ss.schedulers.on('error:claimDayAdditional', (err) => {
    // Handle errors
});

Reward for all activities for the day claimed​

Callback returns current status of the scheduler day:

ss.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:

ss.schedulers.on('error:claimAllDay', (err) => {
    // Handle errors
});

Rewards for all days claimed​

Callback returns current status of the scheduler:

ss.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:

ss.schedulers.on('error:claimAllDays', (err) => {
    // Handle errors
});

Player joined the event​

Callback returns scheduler event and player scheduler event:

ss.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:

ss.schedulers.on('error:join', (err) => {
    // Handle errors
});

Types​

Scheduler Fields​

FieldTypeDescriptionExample
idnumberScheduler ID115
tagstringTag for reference. Can be used instead of IDDAILY_30
typeSchedulerTypeScheduler type (by number of days or consecutive days)ACTIVE_DAYS
daysnumberNumber of days in the scheduler30
isRepeatbooleanRepeatable? After completing the cycle, it starts over from day 1true
isAutoRegisterbooleanThe player is automatically registered in the scheduler upon game startup.true
triggersTrigger[]List of scheduler triggers[]

Player Scheduler Fields​

FieldTypeDescriptionExample
schedulerIdnumberEvent ID115
daysClaimednumber[]List of days for which rewards have been claimed[1,2,3,4]
statsPlayerStatsPlayer's stats in the scheduler{ activeDays: 4, activeDaysConsecutive: 3}

Scheduler Information Fields​

FieldTypeDescriptionExample
schedulerSchedulerThe scheduler
statsPlayerStatsPlayer's stats in the scheduler{ activeDays: 4, activeDaysConsecutive: 3}
daysClaimednumber[]List of days for which rewards have been claimed[1,2,3,4]
isRegisteredbooleanWhether the player is participating in the schedulertrue
currentDaynumberThe current day in the player's schedulertrue

Scheduler Day Information Fields​

FieldTypeDescriptionExample
schedulerSchedulerThe scheduler
daynumberSelected day4
isDayReachedbooleanWhether the player has reached this daytrue
isDayCompletebooleanWhether all day activities are completed (login + all triggers)true
isDayClaimedbooleanWhether the reward for logging in on this day has been claimedtrue
isAllDayClaimedbooleanWhether all rewards for the day have been claimedtrue
canClaimDaybooleanWhether the reward for logging in can be claimedtrue
canClaimAllDaybooleanWhether all rewards for the day can be claimedtrue
bonusesBonus[]List of login bonuses[]
triggersTrigger[]List of triggers for the selected day[]

Scheduler Type​

TypeDescription
ACTIVE_DAYSBy number of active days
ACTIVE_DAYS_CONSECUTIVEBy number of consecutive active days

Error Codes​

ErrorError Description
player_not_foundPlayer not found
empty_id_or_tagEmpty ID or tag passed
scheduler_not_foundScheduler with provided ID or tag not found
wrong_dayInvalid day provided
day_not_reachedPlayer hasn't reached this day yet
day_already_claimedReward for the day has already been claimed
nothing_to_claimNo rewards to claim (already claimed or not found)
failed_to_claimFailed to claim reward (check console for details)
trigger_not_foundTrigger with provided ID or tag not found
trigger_not_activatedTrigger not activated
trigger_already_claimedReward for the trigger has already been claimed
undefinedUnexpected error occurred (check console for details)

Stay in Touch​

Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!