A few lines on your page. Every play on our servers.
Mint a player token on your backend, mount a channel on your page, and get results by signed webhook. The frame, the game and the scoring are ours.
<div id="game"></div>
<script type="module">
import { mount } from '@keliplay/sdk-web/mount'
mount('#game', {
channelId: 'chn_summer',
clientToken,
})
</script> How a play travels
One capsule, five stops.
Embed
Three steps. No game code.
-
Mint a player token
Your backend asks for a token for one player on one channel. The API key stays on your server. The token covers one campaign, one player and one origin, for up to an hour.
POST /v1/auth/session-tokens Authorization: Bearer <API key> Content-Type: application/json { "channelId": "chn_summer", "participantRef": "user_8412", "origin": "https://shop.example" } -
Mount the channel
Point the embed at a channel, not a game. Swap campaigns behind it from the dashboard and this code never changes. Between campaigns the mint returns
clientToken: nulland the slot shows your own message.<div id="game"></div> <script type="module"> import { mount } from '@keliplay/sdk-web/mount' const embed = mount('#game', { channelId: 'chn_summer', clientToken: '…', // from step 1; omit when null theme: 'light', locale: 'en', }) </script>import { KeliplayGame } from '@keliplay/sdk-react' <KeliplayGame channelId="chn_summer" clientToken={token} onSessionCompleted={({ score }) => track(score)} onOutcomeRevealed={({ label, isWin }) => celebrate(isWin)} /> -
Listen on the page
The embed tells your page when a play ends and what came up, so you can react in your own UI. The authoritative copy still arrives by webhook.
embed.on('session_completed', ({ sessionId, score }) => { // show a thank-you, update a progress bar }) embed.on('outcome_revealed', ({ label, isWin }) => { if (isWin) confetti() })
Mount options
| Option | Required | Default | What it does |
|---|---|---|---|
channelId | Yes | none | The only thing a page ever points at. |
clientToken | No | none | From step 1. Leave it out when the mint returned null. |
theme | No | none | 'light' or 'dark', passed to the frame. |
locale | No | none | Passed to the frame. |
initialHeight | No | 420 | Height before the game reports its own. |
allowImmersive | No | true | Set false on a page whose layout must not be taken over. |
Webhooks
Signed results, pushed to you.
Subscribe an endpoint to the events you care about. Pick one to see its payload.
Headers on every delivery
-
X-Keliplay-Signature -
t=<unix seconds>,v1=<hex> -
X-Keliplay-Event - The event name.
-
X-Keliplay-Delivery-Id - Unique per delivery. Use it to ignore repeats.
A failed delivery is tried up to five times in all, with exponential backoff. Timeouts, network errors, 5xx, 408 and 429 are retried; any other 4xx is treated as permanent. Every attempt is in your delivery log.
// POST to your endpoint · X-Keliplay-Event: session_completed
{
"type": "session_completed",
"createdAt": "2026-06-03T14:22:07.118Z",
"data": {
"gameInstanceId": "gin_01J…",
"sessionId": "ses_01J…",
"participantRef": "user_8412",
"outcome": {
"id": "seg_3",
"label": "15% off",
"isWin": true
},
"score": null
}
} // POST to your endpoint · X-Keliplay-Event: winner_selected
{
"type": "winner_selected",
"createdAt": "2026-09-01T09:00:02.410Z",
"data": {
"gameInstanceId": "gin_01J…",
"runId": "run_01J…",
"winners": [
{
"participantRef": "user_8412",
"rank": 1,
"entryId": "ent_01J…",
"prize": {
"label": "Weekend for two"
}
},
{
"participantRef": "user_2290",
"rank": 2,
"entryId": "ent_01J…",
"prize": {
"label": "Weekend for two"
}
}
]
}
} // POST to your endpoint · X-Keliplay-Event: reward_granted
{
"type": "reward_granted",
"createdAt": "2026-06-03T14:22:07.402Z",
"data": {
"gameInstanceId": "gin_01J…",
"grantId": "grt_01J…",
"participantRef": "user_8412",
"sessionId": "ses_01J…",
"source": "rule",
"expiresAt": "2026-07-03T23:59:59.000Z"
}
} // Verify before you trust it. Node, with the raw request body.
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody, header, secret, toleranceSec = 300) {
const { t, v1 } = Object.fromEntries(
header.split(',').map((p) => p.split('=')))
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false
const expected = createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex')
return v1.length === expected.length &&
timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
} API keys
Keys that do one job.
Give a key only the permissions its job needs. A key for minting player tokens can't reveal a seed or change your webhooks. Tick a few to build one.
This key can mint player tokens. Nothing else.
Documentation
The whole manual is in the docs.
Step-by-step guides, every API endpoint, error codes and limits, and the settings for each game.