Events API

Integration of events through SDK. Methods of work.

List of methods

Actions:

• ss.events.join() - join an event. +1 Request

Properties:

• ss.events.list - list of events. FREE
• ss.events.activeList - list of events in which the player is registered. FREE
• ss.events.getEvent() - get information about an event by ID or tag. FREE

Checks:

• ss.events.has() - check if an event is active. FREE
• ss.events.isJoined() - check if a player is participating in an event. FREE

Events:

• ss.events.on('join') - subscribe to the player joining an event.
• ss.events.on('error:join') - subscribe to an error when joining an event.

Types:

• Event - event fields.
• PlayerEvent - player event fields. Personal information about the event.

Tips when working with events

Track events

Use the ss.events.has() check to find out if an event is currently taking place.

You can style your game for the event by checking if it is active at the start of the game.

if (ss.events.has('HALLOWEEN')) {
    ss.setBackground({ url: '/halloween-bg.png' });
}

Join the Event

A player can join an event automatically if the event has auto-join enabled or through the ss.events.join() method.

Use manual registration for the event if you need to interactively invite the player to join the event.

// It's Halloween right now
if (ss.events.has('HALLOWEEN') {
    // The player has not joined the event yet
    if (!ss.events.isJoined('HALLOWEEN')) {
        myGame.showDialog({
            name: 'Halloween Celebration',
            description: 'Travel back in time and discover how Halloween originated!',
            buttonText: 'Embark on an adventure',
            onAccept: () => ss.events.join({ tag: 'HALLOWEEN' })
        });
    }
}

Actions

Join Event

+1 Request

If auto-join is disabled for the event, you can have the player join the event at a specific moment:

JavaScript

// By ID
ss.events.join({ id: 123 });
// By Tag
ss.events.join({ tag: 'HALLOWEEN' });

Unity

// By ID
SS_Events.Join("123");
// By Tag
SS_Events.Join("HALLOWEEN");

The method returns the event and player's event:

JavaScript

const { event, playerEvent } = await ss.events.join({ id: 123 });

Unity

Not implemented in Unity

Properties

Event List

FREE

You have access to the complete list of events when the game starts. See event fields.

JavaScript

ss.events.list.forEach((event) => {
    // event.id
    // event.tag
    // event.name
    // event.description
    // event.icon
    // event.isAutoJoin
    // event.dateStart
    // event.dateEnd
    // event.timeLeft
    // event.triggers
});

Unity

EventData[] eventsData = SS_Events.List();
foreach (EventData data in eventsData)
{
    Debug.Log("ID: " + data.id);
    Debug.Log("Tag: " + data.tag);
    Debug.Log("Name: " + data.name);
    Debug.Log("Description: " + data.description);
    Debug.Log("Icon: " + data.icon);
    Debug.Log("Icon small: " + data.iconSmall);
    Debug.Log("Date Start: " + data.dateStart);
    Debug.Log("Date End: " + data.dateEnd);
    Debug.Log("Is Active: " + data.isActive);
    Debug.Log("Time left: " + data.timeLeft);
    Debug.Log("Is Auto join: " + data.isAutoJoin);

    foreach (TriggerData trigger in data.triggers)
    {
        Debug.Log("Trigger: " + JsonUtility.ToJson(trigger));
    }
}

Player's Active Event List

FREE

You have access to the complete list of events in which the player is participating as soon as the player is ready. See player event fields.

JavaScript

ss.events.activeList.forEach((playerEvent) => {
    // playerEvent.eventId
    // playerEvent.stats.activeDays
    // playerEvent.stats.activeDaysConsecutive
});

Unity

PlayerEvents[] playerEvents = SS_Events.ActiveList();
foreach (PlayerEvents playerEvent in playerEvents)
{
    Debug.Log("ID: " + playerEvent.eventId);
    Debug.Log("Active Days: " + playerEvent.stats.activeDays);
    Debug.Log("Active Days Consecutive: " + playerEvent.stats.activeDaysConsecutive);
}

Get Event Information

FREE

The method returns the event and additional fields:

• isJoined - Whether the player has joined the event or not;
• stats - Player's activity statistics in the event: total days and consecutive active days;
• rewards - A list of rewards that can be obtained from the event (calculated from the triggers list);
• achievements - A list of achievements that can be obtained from the event (calculated from the triggers list);
• products - A list of in-game purchases that can be obtained from the event (calculated from the triggers list);

JavaScript

// By ID
const eventInfo = ss.events.getEvent(123);
// By Tag
const eventInfo = ss.events.getEvent('HALLOWEEN');

const { event, isJoined, stats, rewards, achievements, products } = eventInfo;

// The event may not exist, make sure it exists
if (event) {
    console.info(event.id, isJoined, stats.activeDays);
}

Unity

// By ID or Tag
EventData data = SS_Events.GetEvent("HALLOWEEN");

// If an event exists, you can get information about it
Debug.Log("ID: " + data.id);
Debug.Log("Tag: " + data.tag);
Debug.Log("Name: " + data.name);
Debug.Log("Description: " + data.description);
Debug.Log("Icon: " + data.icon);
Debug.Log("Icon small: " + data.iconSmall);
Debug.Log("Date Start: " + data.dateStart);
Debug.Log("Date End: " + data.dateEnd);
Debug.Log("Is Active: " + data.isActive);
Debug.Log("Time left: " + data.timeLeft);
Debug.Log("Is Auto join: " + data.isAutoJoin);

foreach (TriggerData trigger in data.triggers)
{
    Debug.Log("Trigger: " + JsonUtility.ToJson(trigger));
}

Checks

Event is active

ss.events.has(idOrTag) FREE

JavaScript

// By ID
const hasEvent = ss.events.has(123);
// By Tag
const hasEvent = ss.events.has('HALLOWEEN');

// Check
if (hasEvent) {
    // The event HALLOWEEN exists
}

Unity

// By ID or Tag
bool isActive = SS_Events.IsActive("HALLOWEEN");

// Check
if (isActive) {
    // The event HALLOWEEN exists
}

Player is joined in the event

ss.events.isJoined(idOrTag) FREE

JavaScript

// By ID
const isJoinedEvent = ss.events.isJoined(123);
// By Tag
const isJoinedEvent = ss.events.isJoined('HALLOWEEN');

// Check
if (isJoinedEvent) {
    // The player is joined in the event HALLOWEEN
}

Unity

// By ID or Tag
bool isJoined = SS_Events.IsJoined("HALLOWEEN");

// Check
if (isJoined) {
    // The player is joined in the event HALLOWEEN
}

Events

Player joined the event

The callback returns event and player event:

JavaScript

ss.events.on('join', ({ event, playerEvent }) => {
    // event and player event are available
});

Unity

// Subscribe to event
private void OnEnable()
{
    SS_Events.OnEventJoin += OnJoin;
}

// Unsubscribe from event
private void OnDisable()
{
    SS_Events.OnEventJoin -= OnJoin;
}

// Successful join
public void OnJoin(PlayerEvents playerEvent)
{
    Debug.Log("Join event: " + JsonUtility.ToJson(playerEvent));
}

Failed to join the event

The callback returns an error. See error codes:

JavaScript

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

Unity

// Subscribe to event
private void OnEnable()
{
    SS_Events.OnEventJoinError += OnJoinError;
}

// Unsubscribe from event
private void OnDisable()
{
    SS_Events.OnEventJoinError -= OnJoinError;
}

// Handle errors
public void OnJoinError(string error)
{
    Debug.Log("Join error: " + error);
}

Types

Event Fields

Field	Type	Description	Example
id	number	Event ID	115
tag	string	Tag for easier selection. You can use it instead of ID	HALLOWEEN
name	string	Name translated into the user's language	Halloween
description	string	Description translated into the user's language	Join the spooky-fun event!
icon	string	Link to the icon size 256x256	Example link
iconSmall	string	Link to the icon size 64x64	Example link
dateStart	string	Event start date in ISO 8601 format	2023-10-31T00:00:00-0400
dateEnd	string	Event end date	2023-11-05T23:59:00-0400
isActive	boolean	The event is active	true
timeLeft	number	Number of seconds left until the event ends	3600
isAutoJoin	boolean	Automatically join the event	true
triggers	Trigger[]	List of event triggers	[]

Player Event Fields

Field	Type	Description	Example
eventId	number	Event ID	115
stats	PlayerStats	Player's stats in the event	{ activeDays: 4, activeDaysConsecutive: 3}

Error Codes

Error	Error Description
player_not_found	Player not found
empty_id_or_tag	Empty ID or event tag provided
event_not_found	Event with the given ID or tag not found
event_not_published	Event is not active
event_not_published_on_platform	Event is not active on the player's platform
event_not_started	Event has not started yet
already_joined	Player has already joined the event
undefined	Unexpected error (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!