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!