Skip to main content

Rewards API

Integration of rewards through SDK. Methods of operation.

List of methods​

Actions:

Properties:

Checks:

Events:

Types:

Rules for working with rewards​

Procedure for working with rewards:

  • Give the player a reward. Manually or through triggers.
  • Accept the reward. Automatically or manually, for example by clicking on the "receive" button.
  • Bonuses are automatically credited.
  • Save the player.

As we ensure consistency of data and changes in player variables, there is no need to stick to strict rules as when consuming purchases.

You can designate different types of rewards for yourself, for example: one-time and permanent.

Example of a one-time reward:

  • Login reward
  • Starter kit
  • Premium chest
  • Achievement reward

Such rewards can be accepted immediately or left for manual action by the player.

tip

Rewards are automatically credited upon acceptance. However, if you want to add non-standard changes to variables, you can make them by subscribing to the accepted event.

For example, you need to:

  • Add an item to the inventory
  • Change data in a JSON structure
  • Perform other manipulations not related to the player or not supported by the control panel.

Example of a permanent reward:

  • Unique sword / skin / car
  • VIP status / advertising off
  • DLC / levels / islands and other unlockable content

Permanent rewards do not need to be accepted. Once the reward has been given, it will always be visible to the user.

Rules for conducting a one-time reward with automatic acceptance​

Basic​

// 1. Give the reward
await ss.rewards.give({ tag: 'STARTER_PACK' });

// 2. The reward acceptance will be triggered automatically
// 3. The reward will be credited

// 4. Save the player on the server
await ss.player.sync();

With non-standard data changes​

Using adding health and mana potions to the inventory as an example:

// 1. Subscribe to the reward acceptance event
ss.rewards.on('accept', ({ reward }) => {
    switch (reward.tag) {
        case 'STARTER_PACK': {
            // 2. If necessary, add additional rewards
            inventory.push({ item: 'HP_POTION', amount: 100 });
            inventory.push({ item: 'MP_POTION', amount: 100 });

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

    // 3. If necessary, update the UI to display variable changes
    myGame.refreshUI();
});

// 4. Give the reward
await ss.rewards.give({ tag: 'STARTER_PACK' });

// 5. The reward acceptance will be triggered automatically
// 6. The reward will be credited
// 7. The accept event will be called

// 8. Save the player on the server
await ss.player.sync();

Receiving rewards when starting the game​

Sometimes it may happen that the player did not have time to receive the rewards and save the progress, for example:

  • Closed / restarted the tab, browser or application
  • Turned off / broke the device
  • The game crashed.

They need to be received upon entering the game.

All unreceived rewards with automatic acceptance enabled are automatically accepted by the SDK at start-up.

info

Important. We don't know when the game is fully loaded and you're ready to process the accruals. Therefore, call the game start method ss.gameStart() when you are ready to receive rewards. After calling the game start, we will award the rewards, and you can subscribe to the reward acceptance event in advance.

If the reward does not have automatic acceptance, you can manually receive the rewards you need at game start:

// If manual reward processing is required,
// you must !! first !! subscribe to the accept event
ss.rewards.on('accept', ({ reward }) => {
  // Actions when receiving a reward
})

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

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

  // Such a reward does not exist
  if (!reward) {
    return
  }

  // Get the number of unreceived rewards
  const unacceptedRewardsLeft =
    playerReward.countTotal - playerReward.countAccepted

  // Accept rewards
  for (let i = 0; i < unacceptedRewardsLeft; i++) {
    ss.reward.accept(reward.id)
  }
})

Rules for conducting a permanent reward​

// 1. Give the reward
await ss.rewards.give({ tag: 'NOOB_SKIN' });

// 2. Check for the presence of the reward at the right time
if (ss.rewards.has('NOOB_SKIN')) {
    // do something when you have the noob skin.
}

Actions​

Give reward​

+1 Request

To give a player a reward, you need to pass the ID or tag of the reward.

// By ID
ss.rewards.give({ id: 123 });
// By tag
ss.rewards.give({ tag: 'STARTER_PACK' });

You can give a reward with delayed saving. It will be saved together with the player's save.

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

The method returns the reward and player's reward:

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

Accept reward​

FREE

After giving a reward, it can be accepted and variable changes credited.

// Accept by ID
ss.rewards.accept({ id: 123 });

// Accept by tag
ss.rewards.accept({ tag: 'STARTER_PACK' });

The method returns the reward and player's reward:

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

Properties​

List of rewards​

FREE

You have access to the entire list of rewards at once when the game starts. See reward fields.

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

List of given rewards​

FREE

You have access to the entire list of awarded rewards at once when the player is ready. See player's reward fields.

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

Getting information about a reward​

FREE

The method returns the reward and player's reward:

// By ID
const { reward, playerReward } = ss.rewards.getReward(123);
// By tag
const { reward, playerReward } = ss.rewards.getReward('STARTER_PACK');

// The reward may not exist, make sure it does
if (reward) {
    console.info(reward.id, playerReward.countTotal);
}

Checks​

Reward given​

ss.rewards.has(idOrTag) FREE

// By ID
const hasReward = ss.rewards.has(123);
// By Tag
const hasReward = ss.rewards.has('STARTER_PACK');

// Check
if (hasReward) {
    // The STARTER_PACK reward exists
}

Reward accepted​

ss.rewards.hasAccepted(idOrTag) FREE

// By ID
const hasAcceptedReward = ss.rewards.hasAccepted(123);
// By Tag
const hasAcceptedReward = ss.rewards.hasAccepted('STARTER_PACK');

// Check
if (hasAcceptedReward) {
    // The STARTER_PACK reward has been accepted
}

Reward given but not accepted​

ss.rewards.hasUnaccepted(idOrTag) FREE

// By ID
const hasUnacceptedReward = ss.rewards.hasUnaccepted(123);
// By Tag
const hasUnacceptedReward = ss.rewards.hasUnaccepted('STARTER_PACK');

// Check
if (hasUnacceptedReward) {
    // The STARTER_PACK reward has been given but not accepted
}

Events​

Reward given​

The callback returns the reward and player reward:

ss.rewards.on('give', ({ reward, playerReward }) => {
    // The reward and player reward are available
});

Failed to give reward​

The callback returns an error. See error codes:

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

Reward accepted​

The callback returns the reward and player reward:

ss.rewards.on('accept', ({ reward, playerReward }) => {
    // The reward and player reward are available
});

Failed to accept reward​

The callback returns an error. See error codes:

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

Types​

Reward fields​

FieldTypeDescriptionExample
idnumberID of the reward115
tagstringTag to help select. You can use it instead of IDVIP
namestringName translated into the user's languageVIP status
descriptionstringDescription, translated into the user's languageAd-free, x2 reward
iconstringLink to an icon with a size of 256x256Example link
iconSmallstringLink to an icon with a size of 64x64Example link
mutationsDataMutation[]List of variable changes[]
isAutoAcceptbooleanAuto-accepting rewardtrue

Player reward fields​

FieldTypeDescriptionExample
rewardIdnumberReward ID115
countTotalnumberNumber of given rewards23
countAcceptednumberNumber of accepted awards12

Data mutation fields​

DataMutation

FieldTypeDescriptionExample
typeMutationTypeMutation typePLAYER_FIELD
keystringVariable key for mutationscore
actionMutationActionType of action in mutationADD
valuenumber / string / booleanChanged value100

Structure example:

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

// Will be equivalent to:
ss.player.add('score', 100);

Data mutation types​

MutationType

TypeDescription
PLAYER_FIELDPlayer field mutation

Mutation action types for data mutation fields​

MutationAction

TypeDescription
ADDAdding a value to a field
REMOVESubtracting from a field / deleting the field
SETSetting the value of a field

Error codes​

ErrorError description
player_not_foundPlayer not found
empty_id_or_tagEmpty reward ID or tag
reward_not_foundReward with this ID or tag was not found
undefinedAn unforeseen error occurred (see console)

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!