Events API

Integration of events through SDK. Methods of work.

List of methods

Actions:

• gp.events.join() - join an event.

Properties:

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

Checks:

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

Events:

• gp.events.on('join') - subscribe to the player joining an event.
• gp.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 gp.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 (gp.events.has('HALLOWEEN')) {
    gp.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 gp.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 (gp.events.has('HALLOWEEN') {
    // The player has not joined the event yet
    if (!gp.events.isJoined('HALLOWEEN')) {
        myGame.showDialog({
            name: 'Halloween Celebration',
            description: 'Travel back in time and discover how Halloween originated!',
            buttonText: 'Embark on an adventure',
            onAccept: () => gp.events.join({ tag: 'HALLOWEEN' })
        });
    }
}

Actions

Join Event

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

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

The method returns the event and player's event:

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

Properties

Event List

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

gp.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

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.

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

Get Event Information

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 = gp.events.getEvent(123);
// By Tag
const eventInfo = gp.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

gp.events.has(idOrTag)

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

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

Player is joined in the event

gp.events.isJoined(idOrTag)

// By ID
const isJoinedEvent = gp.events.isJoined(123);
// By Tag
const isJoinedEvent = gp.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:

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

Failed to join the event

The callback returns an error. See error codes:

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

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.

GamePush Community Telegram: @gs_community.

For your suggestions e-mail: [email protected]

We Wish you Success!