Sessions and widget

Creating and relaunching sessions, embedded and overlay widgets, SDK events, and reveal modes.

On this page

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

json
{
  "operatorId": "op-42",
  "playerId": "p-8c1d0f",
  "gameId": "reel-triple",
  "currency": "EUR",
  "language": "en",
  "demo": false
}
FieldNotes
operatorIdThe code of one of your own Operators, otherwise 1100 operatorNotAllowed. Optional for an Operator Partner with exactly one Operator. Providers always send it.
playerIdOpaque, 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.
gameIdreel-stars, reel-triple or reel-streak, if enabled for the Operator.
currencyISO 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.
languageA 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.
demotrue 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:

json
{
  "sessionId": "ses_4KQ2...",
  "sessionToken": "st_7f3a9c...",
  "launchUrl": "https://sandbox.reelxtra.net/v1/public/widget/#lt=Zk3...",
  "expiresAt": "2027-03-01T12:30:00Z"
}
  • sessionToken stays on your server. You send it with every bet. Never pass it to the browser.
  • launchUrl goes 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 with 1506 maintenance (HTTP 503, maintenanceUntil in the body), because no play could follow. Create the session after maintenanceUntil.
  • 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:

json
{ "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 gets 1302.
  • It is rate limited per session (1600).
  • During planned maintenance of the game, relaunch is refused with 1506 maintenance as 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 launchUrl from 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

PlacementStreamWhat it is
EmbeddedGame integrationThe widget sits inside your game page, at integration level L1 or L2 (below).
OverlayCasino integrationThe 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.

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

js
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 spin

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

js
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:

html
<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)

js
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 position you 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 parentOrigin to 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:

  1. Check the origin of the event and trust only events from the widget iframe, never from other windows.
  2. 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.
  3. 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.

EventDataWhen
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:

  1. On ready, take enabled as the start state. Do not assume the side game is on.
  2. While enabled is false, stop offering and stop sending the side game: do not send POST /v1/partner/bets for it. If you do, you get 1508 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.
  3. On optInChanged with enabled: true, offer the side game again.
  4. 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.

js
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 choice

The 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

EventWhen
readyThe widget is connected. Carries enabled, the start state of the on/off switch.
roundThe 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.
shownThe widget finished showing a round.
winA win is being shown (use it to pause your own celebrations if you like).
poolUpdateJackpot values changed (progressive games, at most once per second).
sessionReplacedA newer session for this Partner, Operator, player and game took over.
optInChangedThe on/off switch changed and ReelXtra saved it: { enabled, reason }. See "The on/off switch decides play".
levelChosenWidget level picker only: { level }, advisory, see above.
errorConnection 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:

ModeNameDefault forBehaviour
1ImmediateCasino integrationThe widget shows each result as soon as it arrives.
2Partner reveal()Game integrationThe 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 call reveal() 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)

js
rx.reveal(roundId); // roundId from the bet response, passed to your client with the spin result

Call it when your base reels stop. Level 1 only; Level 2 (plain iframe) has no reveal call.

Sync with your reels: the bet response returns the win and roundId, the widget holds the round, and your client calls rx.reveal(roundId) when the reels stop

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.