API Triggers

Integration of triggers via SDK. Work methods.

Method List

Actions:

• ss.triggers.claim() - claim reward. +Lazy Sync Request

Properties:

• ss.triggers.list - trigger list. FREE
• ss.triggers.activatedList - activated trigger list. FREE
• ss.triggers.getTrigger() - get information about a trigger by ID or tag. FREE

Checks:

• ss.triggers.isActivated() - check if trigger is activated. FREE
• ss.triggers.isClaimed() - check if trigger bonuses are claimed. FREE

Events:

• ss.triggers.on('activate') - subscribe to the moment of trigger activation.
• ss.triggers.on('claim') - subscribe to the moment of trigger bonuses claim.
• ss.triggers.on('error:claim') - subscribe to an error when claim a trigger bonuses.

Types:

• Trigger - trigger fields.

Rules for Working with Triggers

How trigger activation occurs:

• The player enters the game or saves the game.
• On the server, the fulfillment of conditions is checked.
• The SDK receives a response from the server and notifies the developer.
• A notification of trigger activation is sent.
• When reward is claimed:
• A notification of trigger reward claimed is sent.
• A notification of reward receipt is sent.
• A notification of achievement receipt is sent.
• A notification of purchase accrual is sent.

How trigger rewards are claimed:

• If automatic reward claiming is enabled, rewards, purchases or achievements are recieved to the player when conditions are met.
• If manual claiming is selected, the ss.triggers.claim() method must be called at any time in order to obtain all of the trigger rewards.
• When rewards are manually claimed, a request is made to save the player and all rewards are credited to the server and player variables are modified.

Since data consistency and bonus issuance are provided by us, there is no need to participate in the process at the code level.

It is enough for you to only subscribe to events of awarding rewards and wait for the trigger to activate.

Actions

Claim Reward

+Lazy Sync Request

To claim a reward for a trigger, you need to pass the ID or tag of the trigger.

JavaScript

// By ID
ss.triggers.claim({ id: '646929f98abe970f54fb6274' });
// By Tag
ss.triggers.claim({ tag: 'LEVEL_10' });

Unity

// By ID
SS_Triggers.Claim('646929f98abe970f54fb6274');
// By Tag
SS_Triggers.Claim('LEVEL_10');

The method returns the trigger, activation status, and reward confirmation:

JavaScript

const { trigger, isActivated, isClaimed } = await ss.triggers.claim({
    tag: 'LEVEL_10'
});

Unity

Not implemented, use SS_Trigger.GetTrigger() to get this data

Properties

Trigger List

FREE

You have access to the entire trigger list immediately upon launching the game. See trigger fields.

JavaScript

ss.triggers.list.forEach((trigger) => {
    // trigger.id
    // trigger.tag
    // trigger.isAutoClaim
    // trigger.description
    // trigger.conditions
    // trigger.bonuses
});

Unity

//Get list of triggers
TriggerData[] triggers = SS_Triggers.List();

//Show each trigger data
foreach(TriggerData trigger in triggers)
{
    Debug.Log("ID: " + trigger.id);
    Debug.Log("Tag: " + trigger.tag);
    Debug.Log("AutoClaim: " + trigger.isAutoClaim);
    Debug.Log("Descroption: " + trigger.description);

    foreach (TriggerCondition condition in trigger.conditions)
    {
        Debug.Log("Condition: " + JsonUtility.ToJson(condition));
    }

    foreach (TriggerBonus bonus in trigger.bonuses)
    {
        Debug.Log("Bonus: " + JsonUtility.ToJson(bonus));
    }
}

Activated Trigger List

FREE

You have access to the entire list of activated triggers when the player is ready.

JavaScript

ss.triggers.activatedList.forEach((triggerId) => {
    // Trigger ID as a string

    // Getting a trigger by ID
    const { trigger, isActivated, isClaimed } =
        ss.triggers.getTrigger(triggerId);
});

Unity

//Get activated triggers list
TriggerActive[] triggers = SS_Triggers.ActivatedList();

//Show each activated trigger data
foreach (TriggerActive trigger in triggers)
{
    Debug.Log("ID: " + trigger.triggerId);
    Debug.Log("Claimed: " + trigger.claimed);
}

Get Information About Trigger

FREE

The method returns trigger and activation status:

JavaScript

// By ID
const { trigger, isActivated, isClaimed } = ss.triggers.getTrigger(
    '646929f98abe970f54fb6274'
);
// By Tag
const { trigger, isActivated, isClaimed } = ss.triggers.getTrigger('LEVEl_10');

// The trigger may not exist, make sure it exists
if (trigger) {
    console.info(trigger.id, isActivated, isClaimed);
}

Unity

// By ID
TriggerAllData data = SS_Triggers.GetTrigger('646929f98abe970f54fb6274');
// By Tag
TriggerAllData data = SS_Triggers.GetTrigger('LEVEl_10');

Debug.Log(data.trigger);
Debug.Log(data.isActivated);
Debug.Log(data.isClaimed);

Checks

Trigger Activated

ss.triggers.isActivated(idOrTag) FREE

JavaScript

// By ID
const isActivated = ss.triggers.isActivated('646929f98abe970f54fb6274');
// By Tag
const isActivated = ss.triggers.isActivated('LEVEl_10');

// Check
if (isActivated) {
    // LEVEl_10 trigger is activated
}

Unity

// By ID
bool isActivated = SS_Triggers.IsActivated('646929f98abe970f54fb6274');
// By Tag
bool isActivated = SS_Triggers.IsActivated('LEVEl_10');

// Check
if (isActivated) {
    // LEVEl_10 trigger is activated
}

Reward Claimed

ss.triggers.isClaimed(idOrTag) FREE

JavaScript

// By ID
const isClaimed = ss.triggers.isClaimed('646929f98abe970f54fb6274');
// By Tag
const isClaimed = ss.triggers.isClaimed('LEVEl_10');

// Check
if (isClaimed) {
    // LEVEl_10 bonuses of the trigger is claimed
}

Unity

// By ID
bool isClaimed = SS_Triggers.IsClaimed('646929f98abe970f54fb6274');
// By Tag
bool isClaimed = SS_Triggers.IsClaimed('LEVEl_10');

// Check
if (isClaimed) {
    // LEVEl_10 bonuses of the trigger is claimed
}

Events

Trigger Activated

Callback returns trigger:

JavaScript

ss.triggers.on('activate', ({ trigger }) => {
    // Information about the trigger is available
});

Unity

//Subscribe to event
private void OnEnable()
{
    SS_Triggers.OnTriggerActivate += OnActivate;
}

//Unsubscribe from event
private void OnDisable()
{
    SS_Triggers.OnTriggerActivate -= OnActivate;
}

//Process the event
public void OnActivate(TriggerData trigger)
{
    Debug.Log(trigger.ToString());
}

Reward Claimed

Callback returns trigger:

JavaScript

ss.triggers.on('claim', ({ trigger }) => {
    // Information about the trigger is available
});

Unity

//Subscribe to event
private void OnEnable()
{
    SS_Triggers.OnTriggerClaim += OnClaim;
}

//Unsubscribe from event
private void OnDisable()
{
    SS_Triggers.OnTriggerClaim -= OnClaim;
}

//Process the event
public void OnClaim(TriggerData trigger)
{
    Debug.Log(trigger.ToString());
}

Reward Claim Failed

The callback returns an error. See error codes:

JavaScript

ss.triggers.on('error:claim', (err) => {
    // check error code
});

Unity

//Subscribe to event
private void OnEnable()
{
    SS_Triggers.OnTriggerClaimError += OnClaimError;
}

//Unsubscribe from event
private void OnDisable()
{
    SS_Triggers.OnTriggerClaimError -= OnClaimError;
}

//Process the event
public void OnClaimError(string error)
{
    Debug.LogError(error);
}

Types

Trigger Fields

Field	Type	Description	Example
id	string	Reward ID	646929f98abe970f54fb6274
tag	string	Tag for selecting the trigger. You can use it instead of ID	LEVEL_10
description	string	Trigger description	Reach level 10
isAutoClaim	boolean	The reward is automatically claimed when the trigger is activated	true
conditions	Condition[][]	List of trigger conditions	[]
bonuses	Bonus[]	List of bonuses	[]

Condition Fields

Field	Type	Description	Example
type	ConditionType	Type of condition	PLAYER_FIELD
key	string	Variable key to compare	level
operator	ConditionOperator	Type of comparison operator	EQ
value	number[] / string[] / boolean[]	Values to be checked, combined with OR	[10,20]

Full example of condition structure:

// Conditions AND on player fields

// player.level >= 10
const playerLevelGte10: Condition = {
    type: 'PLAYER_FIELD',
    key: 'level',
    operator: 'GTE',
    value: [10]
};

// player.class === 'rouge' || player.class === 'mage'
const playerRogueOrMage: Condition = {
    type: 'PLAYER_FIELD',
    key: 'class',
    operator: 'EQ',
    value: ['rogue', 'mage']
};

// player.level >= 10 && (player.class === 'rouge' || player.class === 'mage')
const playerANDConditions: Condition[] = [playerLevelGte10, playerRogueOrMage];

// Conditions AND on player statistics
// playerStats.activeDays >= 5
const activeDaysGTE5: Condition = {
    type: 'PLAYER_STAT',
    key: 'activeDays',
    operator: 'GTE',
    value: [5]
};

// playerStats.playtimeAll >= 36000
const playtimeAllGTE360000: Condition = {
    type: 'PLAYER_STAT',
    key: 'playtimeAll',
    operator: 'GTE',
    value: [36000]
};

// playerStats.activeDays >= 5 && playerStats.playtimeAll >= 36000
const playerStatsANDConditions: Condition[] = [
    activeDaysGTE5,
    playtimeAllGTE360000
];

// Conditions OR
// Trigger activates if either conditions are met for player fields or player stats
const triggerORConditions: Condition[][] = [
    playerANDConditions,
    playerStatsANDConditions
];

Condition Types

ConditionType

Type	Description
PLAYER_FIELD	Check against player fields
PLAYER_STAT	Check against player statistics
ENTITY_STAT	Check against stats from external modules, such as events or schedulers

Comparison Operator Types

ConditionOperator

Type	Description
EQ	Equal
NE	Not equal
GT	Greater than
LT	Less than
GTE	Greater than or equal to
LTE	Less than or equal to

Bonus Fields

Bonus

Field	Type	Description	Example
type	BonusType	Type of bonus	REWARD
id	number	Bonus ID	1122

Example of bonus structures:

const bonuses: Bonus[] = [
    {
        type: 'REWARD',
        id: 941
    },
    {
        type: 'PRODUCT',
        id: 31
    }
];

Bonus Types

BonusType

Type	Description
REWARD	Reward
ACHIEVEMENT	Achievement
PRODUCT	Product

Error Codes

Error	Error Description
trigger_not_found	Trigger with the provided ID or tag not found
trigger_not_activated	Trigger is not activated
trigger_already_claimed	Reward has already been claimed
undefined	Unexpected error (check the 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!