Sessions and widget
Creating and relaunching sessions, embedded and overlay widgets, SDK events, and reveal modes.
On this page
- Create a session
- Relaunch a session
- Embed the widget
- Placements
- Level 1: SDK (recommended)
- Level 2: plain iframe
- Overlay (casino integration)
- The on/off switch decides play
- Events
- Reveal: when the widget shows a result
- Game integration: sync with your reels (mode 2)
- Casino integration: immediate (mode 1)
- Jackpot display
Create a session
Create a game session when a player opens an Extra Game (game integration: or your slot with the Extra Game switched on; casino integration: when the player turns the overlay on or loads a casino page that shows it).
POST /v1/partner/sessions — signed, nonce required
{
"operatorId": "op-42",
"playerId": "p-8c1d0f",
"gameId": "reel-triple",
"currency": "EUR",
"language": "en",
"demo": false
}| Field | Notes |
|---|---|
operatorId | The code of one of your own Operators, otherwise 1100 operatorNotAllowed. Optional for an Operator Partner with exactly one Operator. Providers always send it. |
playerId | Opaque, stable, unique within the Operator. No personal data. Send the Operator's own player id (Operator Partners must, Providers are recommended to) so a player's card is shared across streams. Optional for a demo session, where it only counts the session as verified and is never stored. |
gameId | reel-stars, reel-triple or reel-streak, if enabled for the Operator. |
currency | ISO 4217, or the code of a crypto or fun currency (a social casino's coins are fun currencies) where enabled. FUN, and only FUN, for a demo session; a real session in FUN is refused with 1202. |
language | A language tag of 2 to 16 characters (en, de, pt-BR); an unsupported language gets English. Social casinos: end it in _SC or _SOC (en_SC, de_SOC) to show every player text in social terms ("Play amount" for bet, "Awarded" for paid, no gambling wording), or ask us to turn social casino mode on for the Operator so every session has it. Amounts and currencies are unchanged. |
demo | true for FUN play (the session id starts with dses_, the session token with dst_); refused with 1504 demoNotAllowed where the jurisdiction forbids demo, or where it requires a verified session and no playerId is sent. |
Response 201:
{
"sessionId": "ses_4KQ2...",
"sessionToken": "st_7f3a9c...",
"launchUrl": "https://sandbox.reelxtra.net/v1/public/widget/#lt=Zk3...",
"expiresAt": "2027-03-01T12:30:00Z"
}sessionTokenstays on your server. You send it with every bet. Never pass it to the browser.launchUrlgoes to the browser. It contains a one-time launch token valid for 60 seconds; the widget swaps it for its own random session key (valid for at most 24 hours). If it expires, relaunch the session (below).- During planned maintenance of the game (see
09-games.md), session create is refused with1506maintenance(HTTP503,maintenanceUntilin the body), because no play could follow. Create the session aftermaintenanceUntil. - One session per Partner, Operator, player and Extra Game. Creating a new session for the same combination replaces the old one: the old widget shows "session replaced" and closes. Sessions for different games, or from different Partners, run side by side. So a Provider's slot session and the Operator's casino overlay session for the same player and game don't replace each other. All their bets are serialised by us.
- One widget instance per Extra Game. An overlay that shows several Extra Games runs one SDK instance, with its own session and connection, for each game.
- Idle expiry is set per Operator (default 30 minutes without a bet). A bet on an expired session gets
error
1300; create a new session. Retries of bets you already sent keep working after expiry (see Bets). - Log out:
DELETE /v1/partner/sessions/{sessionId}(nonce required), for example on shared devices. - Player Game State is not tied to the session. A part-filled card is still there in the next session, on any device.
Relaunch a session
When the player reloads the page or navigates, the one-time launchUrl has already been used. Ask for a fresh
one instead of creating a new session:
POST /v1/partner/sessions/{sessionId}/launch — signed, nonce required (not idempotent), no body. Response 200:
{ "launchUrl": "https://sandbox.reelxtra.net/v1/public/widget/#lt=Qm9...", "expiresAt": "2027-03-01T12:30:00Z" }- Works only on an active session. An expired or closed session gets
1300; a replaced one gets1302. - It is rate limited per session (
1600). - During planned maintenance of the game, relaunch is refused with
1506maintenanceas well. A widget that is already open keeps working and shows the player's card; session close, look-ups and history links are unaffected. - Once the new link is opened, the widget's new session key replaces the previous one, and the old widget's connection is closed, so a stale copy of the old link can't keep a connection open.
- The widget shows the player's current state: after a relaunch the new widget shows the player's current card or board and the result of their latest round. It does not replay earlier rounds; their wins were already paid in your bet responses.
- It doesn't reset idle expiry; only bets keep a session alive.
- Like
launchUrlfrom session creation, the new link goes from your server to the browser only.
Embed the widget
The widget is a sealed iframe served from our domain. It only shows results; it never takes bets or handles money, so it needs no secrets and can't be used to move funds.
Placements
| Placement | Stream | What it is |
|---|---|---|
| Embedded | Game integration | The widget sits inside your game page, at integration level L1 or L2 (below). |
| Overlay | Casino integration | The widget floats over the casino site: placement: 'overlay', with a position and a minimise state that is kept across relaunch. |
Either way the widget is one rectangle: a header and the game. The header has a ? button that opens the game's
How to play screen (the rules, what the game pays at the bet on show and the RTP). The player can minimise it to a small pill that
shows the card's progress and the jackpot or prize, drag it anywhere in the window, and dock it: dropped at
the left or right edge, it tucks into a slim tab that slides out on a tap. On a portrait screen (taller than wide)
it switches to a wide, short layout; it scales to the window and lays itself out again on every rotation. An
embedded widget starts in the box you gave it; the first drag lifts it out to float over the page, and a "put it
back in its place" button in its header returns it to your box. Its state (minimised, place, docked) is kept across
reloads and relaunches in your page's localStorage. If your box sits inside an element with a CSS transform or
filter, the floating widget stays inside that element: keep the box outside such elements.
Sizes. The square layout is 264 by 306 CSS pixels before scaling and the wide layout 420 by 202; the SDK scales the widget to the window (or, embedded, to your box's width) and sizes the iframe to match. Everything outside the widget's rounded panels is transparent, so it sits cleanly on any page colour.
Screenshots of every form (the three games, both layouts, the overlay controls, the compact strip, the pill, docking, the help screen, languages and social casino terms) are on the website's widget page.
Level 1: SDK (recommended)
<div id="reelxtra"></div>
<script src="https://sandbox.reelxtra.net/v1/public/sdk/reelxtra.js"></script>
<script>
const rx = ReelXtra.mount({
container: document.getElementById('reelxtra'),
launchUrl: launchUrlFromYourServer,
onEvent: (e) => { /* optional: see events below */ }
});
</script>The SDK (software development kit) creates and sizes the iframe, keeps the connection alive, keeps your latest reveal during short network drops, and can expand the iframe for full-screen win animations.
Make each play look live (recommended). Call rx.spinStart() when you place a bet that plays the Extra Game:
the widget spins the card's empty squares until the result arrives, then lands them on the new stars. If the bet
does not go through, call rx.spinStop(). Both only animate the widget; nothing is sent to us, and without a
result or a stop the squares stop by themselves after 10 seconds. Without spinStart, a result still spins briefly
before it lands.
rx.spinStart(); // the player's bet is on its way
const result = await yourBackend.placeBet(...); // your server calls POST /v1/partner/bets
if (!result.played) rx.spinStop(); // refused or failed: stop the spinShow the card of the bet the player picked (recommended). A player has a separate card for each bet size. When
the player changes the bet on your page, call rx.setLevel(level) with the new Bet Level: the widget shows that
bet's card, its price and its jackpot. It keeps each card it has seen, so going up and down the bet sizes is instant.
Without it, the widget shows the new bet's card only when the next bet's result arrives.
betSelect.onchange = () => rx.setLevel(Number(betSelect.value));The SDK and the widget come from the same host as the API, under /v1/public. Always load the SDK from this one
address and never copy it to your own server: the browser checks it on every page load, so your players get each new
release on their next page load with no change on your side. Releases under /v1 keep ReelXtra.mount and its
options compatible. Don't add an integrity attribute: the file changes with each release. Your page's Content Security Policy must allow one origin for both:
frame-src https://sandbox.reelxtra.net and script-src https://sandbox.reelxtra.net (use the production host
supplied at go-live).
Level 2: plain iframe
If you can't add scripts, embed the launch URL directly:
<iframe src="{launchUrl}" title="ReelXtra" width="264" height="306" allow="autoplay" style="border:0;background:transparent"></iframe>Without the SDK the widget is not scaled, so give the iframe its unscaled size (264 by 306). There is no reveal call (and no events), so reveal mode 2 is not available at
Level 2: results are shown at once. Reveal mode 2 is rejected for Level 2 integrations.
Overlay (casino integration)
const rx = ReelXtra.mount({
launchUrl: launchUrlFromYourServer,
placement: 'overlay',
position: 'bottom-right', // where the overlay sits on the page
onEvent: (e) => { /* optional */ }
});- The overlay can be minimised, moved and docked by the player (see Placements). The
positionyou pass is where it first appears; after that the player's choice is kept across relaunch. - Run one SDK instance per Extra Game if you show more than one.
- No origin to register. The widget may be shown on any page or domain you run, so there is no origin
allowlist and no
parentOriginto send. The widget never sends a bet or action to us: your backend sends every play, so a page that frames the widget can't move money. What the page can do is switch the side game off or hide it, which stops play (see "The on/off switch decides play").
Widget level picker (optional)
Whether the widget shows a level picker is an Operator setting, not a mount option: ask ReelXtra to turn widget
level control on for your Operator when you onboard (or later). With it on, the widget's bet shows − and + to
step through your levels. They only emit the advisory SDK event levelChosen { level }; the widget never sends a
bet or action to us. With it off, the bet is shown read only: the price of the level last played.
What you must do with levelChosen:
- Check the origin of the event and trust only events from the widget iframe, never from other windows.
- Pass the choice to your backend. Your backend confirms it (for example, the player is allowed to play that level) and sends the confirmed level and its bet amount in each play.
- Treat it as a hint. A bet is only ever played because your backend sent
POST /v1/partner/bets.
If the setting is off, show your own level picker in the casino UI instead. Either way the bet amount is the price of a level chosen by the player, never derived from the casino bet.
The on/off switch decides play
The widget always shows an on/off switch in its header. ReelXtra decides what it means, not your page and not
your backend. While the side game is off, every POST /v1/partner/bets for that game and player is refused with
error 1508 sideGameOff (HTTP 403, definite: no Round was made, nothing to retry). Switch it on and bets play again.
This is the same for game integration and casino integration, and for demo sessions.
What counts as off.
- The player switched it off with the switch. The widget then collapses to a compact strip (264 by 46 CSS pixels before scaling) that keeps the jackpot of the level on show live (Reel Streak, which has no jackpot, shows what a full card pays now), the stars on the card and the switch. Switching it on shows the full widget again. An overlay keeps its corner while it shrinks and grows.
- The widget is hidden. A hidden widget is loaded and connected but not shown, and it counts as off. Any visible state plays: full, minimised to the pill, docked open or docked tucked.
What the widget starts with. The player's last choice is remembered for each Operator, player and game, across reloads, relaunches and sessions. A player who has never chosen starts with your Operator's starts on setting (on unless you asked ReelXtra to start new players off). A widget mounted hidden starts off whatever the player chose; when you show it, it goes back to the player's choice.
Telling your page. The server has already decided; the widget tells your page as a courtesy, so you can stop offering the side game while it is off.
| Event | Data | When |
|---|---|---|
ready | { gameId, version, enabled } | The widget is connected. enabled is the start state: true when bets play now. |
optInChanged | { enabled, reason } | The state changed and ReelXtra saved it. reason is player (the player used the switch), hidden (your page called rx.hide()) or shown (your page called rx.show()). |
optInChanged is sent only after ReelXtra has saved the change, so enabled is the truth. It is also sent to every
other widget of the same session. These events are not advisory: they report a decision already taken. Still check
their origin like every SDK event (the SDK does it before calling onEvent).
What your page and backend should do:
- On
ready, takeenabledas the start state. Do not assume the side game is on. - While
enabledisfalse, stop offering and stop sending the side game: do not sendPOST /v1/partner/betsfor it. If you do, you get1508 sideGameOff; treat it as "off", not as a failure: do not retry, and do not debit the player (a refused bet makes no Round). If you debited before sending, reverse the debit as for any refusal. - On
optInChangedwithenabled: true, offer the side game again. - A Reel Triple bonus carried over from a card that timed out waits while the side game is off and is paid in the response of the first bet after it is switched on.
Hide and show only through the SDK. To remove the widget from sight, call rx.hide(); to bring it back call
rx.show(). To mount it hidden, pass hidden: true to ReelXtra.mount. ReelXtra can only enforce what the widget
knows: if you hide the iframe in any other way (CSS, removing it from view, covering it), it still counts as on and
bets play without the player seeing the game. Do not do that.
const rx = ReelXtra.mount({
container: document.getElementById('reelxtra'),
launchUrl: launchUrlFromYourServer,
hidden: false, // true: loaded but not shown, and off
onEvent: (e) => {
if (e.type === 'ready') {
sideGame.setOffered(e.data.enabled); // start state
} else if (e.type === 'optInChanged') {
sideGame.setOffered(e.data.enabled); // reason: 'player' | 'hidden' | 'shown'
yourBackend.sideGameState(e.data.enabled); // optional: tell your backend to stop or resume
}
}
});
// your page decides to remove the widget, for example while a bonus feature runs
rx.hide(); // off: bets are refused with 1508 until rx.show()
rx.show(); // back to the player's own choiceThe widget calls ReelXtra over its own connection when the player uses the switch or you call rx.hide() and
rx.show(); it never sends a bet. The calls can only stop play or allow it, and the player's switch is the
only thing that turns a player's play on.
Events
| Event | When |
|---|---|
ready | The widget is connected. Carries enabled, the start state of the on/off switch. |
round | The latest round result has arrived (held until reveal in mode 2). A round that was replaced by a newer one before it was shown gives no shown or win event. |
shown | The widget finished showing a round. |
win | A win is being shown (use it to pause your own celebrations if you like). |
poolUpdate | Jackpot values changed (progressive games, at most once per second). |
sessionReplaced | A newer session for this Partner, Operator, player and game took over. |
optInChanged | The on/off switch changed and ReelXtra saved it: { enabled, reason }. See "The on/off switch decides play". |
levelChosen | Widget level picker only: { level }, advisory, see above. |
error | Connection or token problem; the SDK retries automatically. A rejected launch link means you need a relaunch. |
Reveal: when the widget shows a result
Results reach the widget at the same moment your backend gets the bet response. The reveal mode is set per Operator:
| Mode | Name | Default for | Behaviour |
|---|---|---|---|
1 | Immediate | Casino integration | The widget shows each result as soon as it arrives. |
2 | Partner reveal() | Game integration | The widget holds the result until you call rx.reveal(roundId), or until the short safety timeout (default 2 s). |
- The widget shows only the latest state: the player's current card or board and the result of their latest round. If several rounds arrive while one is held or the widget is reconnecting, only the latest is shown, and earlier ones are skipped for display. Their wins were already paid in the bet responses.
- If you don't call
reveal(), the result shows after a short delay (default 2 seconds, configurable between 1 and 3 seconds per Operator). If you callreveal()sooner, the result shows sooner. The delay affects only what the player sees: the win is always paid in the bet response. - After a reload (or a reconnect), the widget shows the player's current state.
Game integration: sync with your reels (mode 2)
rx.reveal(roundId); // roundId from the bet response, passed to your client with the spin resultCall it when your base reels stop. Level 1 only; Level 2 (plain iframe) has no reveal call.
How to read it: time runs downwards. Your backend sends the bet and gets the win and roundId back. The widget receives the round at the same time and holds it. Your backend passes the spin result and roundId to your client, the reels spin and stop, and the client calls rx.reveal(roundId); the widget then plays the Extra Game animation.
Casino integration: immediate (mode 1)
No client call is needed. If the Operator prefers to hold a result until its own casino bet has finished
(for example, a crash game round), ask us to set mode 2 for the Operator and call rx.reveal(roundId) from the
casino page.
Jackpot display
For progressive games the widget shows the live pool values for the player's level, converted to the player's currency at the Operator's exchange rates. Values update at most once per second and drop immediately after a hit.