Game events
While a game runs, it tells your page what is happening: when it has loaded, when a play starts and ends, and what the player got. Use these events to update your own page, for example to show a “play again” button or to record a finished play in your analytics.
Events are for your page’s user interface. To act on results in your backend, use webhooks, which are signed and cannot be faked by a visitor.
Listen for events
Section titled “Listen for events”With the web SDK, call on on the object mount returns. The handler receives the
event’s payload:
const game = KrdsGames.mount('#keliplay-game', { channelId, clientToken, playBaseUrl })
game.on('session_completed', (payload) => { showPlayAgainButton()})on returns a function that removes the handler. In React, use the matching
on... prop instead. See React.
Events
Section titled “Events”The game has loaded and is about to start.
| Field | Type | Description |
|---|---|---|
gameSlug |
string | Which game it is, such as spin-wheel. |
gameInstanceId |
string | The campaign being played. |
resize
Section titled “resize”The game’s content changed height. The SDK resizes the frame for you, so you only need this if you lay out other things around it.
| Field | Type | Description |
|---|---|---|
height |
number | The new height in pixels. |
session_started
Section titled “session_started”A play has started.
| Field | Type | Description |
|---|---|---|
sessionId |
string | Identifies this play. The same id appears in webhooks. |
outcome_revealed
Section titled “outcome_revealed”Sent by games with an instant result, such as Spin the Wheel, when the result is
shown. It comes just before session_completed.
| Field | Type | Description |
|---|---|---|
sessionId |
string | The play. |
outcomeId |
string | Which result came up, for example the id of a wheel segment. |
label |
string | The result’s label as the player saw it. |
isWin |
boolean | Whether this result counts as a win. |
session_completed
Section titled “session_completed”The play has finished and its result is recorded.
| Field | Type | Description |
|---|---|---|
sessionId |
string | The play. |
score |
number or null | The final score, for games that keep score. |
result |
object | Present for games with an instant result. Contains outcome, with the same id, label and isWin as above. |
The score here is for display. Winners and rewards are always decided by Keliplay from the recorded play, never from what the page reports.
presentation
Section titled “presentation”The game asks to fill the screen, or to go back to its normal place in the page.
The SDK handles this for you unless you set allowImmersive: false.
| Field | Type | Description |
|---|---|---|
mode |
'immersive' or 'inline' |
immersive covers the viewport. inline returns to the page. |
Something stopped the game, such as an expired token or a campaign that is no longer live. The frame shows a neutral message to the player.
| Field | Type | Description |
|---|---|---|
code |
string | A short identifier, such as unauthorized or conflict. |
message |
string | A description for you, not for players. |
Log these so you can see problems in your own monitoring. Treat codes you do not recognise as a general failure; new ones may be added.
Without the SDK
Section titled “Without the SDK”In an Android or iOS app, the native SDKs deliver these
events as typed values, so there is nothing to parse. If you build your own
embed, the frame sends each event to its parent with postMessage. Every message has this shape:
{ "channel": "krds-games", "protocolVersion": 1, "sentAt": "2026-10-05T10:02:11.418Z", "type": "session_completed", "payload": { "sessionId": "01a10a6f-c777-7753-b0e6-63c92d26cb9b", "score": 840 }}Ignore messages whose channel is not krds-games, and check that event.origin
is https://play.keliplay.com before trusting one.