Skip to main content

Events API

Integration of events through SDK. Methods of work.

List of methods

Actions:

Properties:

Checks:

Events:

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:

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

The method returns the event and player's event:

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

Properties

Event List

FREE

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

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
});

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.

ss.events.activeList.forEach((playerEvent) => {
// playerEvent.eventId
// playerEvent.stats.activeDays
// 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);
// 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);
}

Checks

Event is active

ss.events.has(idOrTag) FREE

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

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

Player is joined in the event

ss.events.isJoined(idOrTag) FREE

// 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
}

Events

Player joined the event

The callback returns event and player event:

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

Failed to join the event

The callback returns an error. See error codes:

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

Types

Event Fields

FieldTypeDescriptionExample
idnumberEvent ID115
tagstringTag for easier selection. You can use it instead of IDHALLOWEEN
namestringName translated into the user's languageHalloween
descriptionstringDescription translated into the user's languageJoin the spooky-fun event!
iconstringLink to the icon size 256x256Example link
iconSmallstringLink to the icon size 64x64Example link
dateStartstringEvent start date in ISO 8601 format2023-10-31T00:00:00-0400
dateEndstringEvent end date2023-11-05T23:59:00-0400
isActivebooleanThe event is activetrue
timeLeftnumberNumber of seconds left until the event ends3600
isAutoJoinbooleanAutomatically join the eventtrue
triggersTrigger[]List of event triggers[]

Player Event Fields

FieldTypeDescriptionExample
eventIdnumberEvent ID115
statsPlayerStatsPlayer's stats in the event{ activeDays: 4, activeDaysConsecutive: 3}

Error Codes

ErrorError Description
player_not_foundPlayer not found
empty_id_or_tagEmpty ID or event tag provided
event_not_foundEvent with the given ID or tag not found
event_not_publishedEvent is not active
event_not_published_on_platformEvent is not active on the player's platform
event_not_startedEvent has not started yet
already_joinedPlayer has already joined the event
undefinedUnexpected 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!