Skip to content
LootBox Solutions

Embedding the iframe

The player surface is an iframe at https://{operator}.app.lootboxsolutions.com/play. You mint a launch token, embed the URL, and the game app takes over.

<iframe
  src="https://{operator}.app.lootboxsolutions.com/play?token=lt_…&parent=https://casino.example"
  allow="clipboard-write"
  style="width:100%;height:720px;border:0">
</iframe>
URL paramPurpose
tokenThe launch token from /launches.
boxIdGuest mode — render a box anonymously without a token. See Guest mode.
parentYour origin. Required to enable host messaging; the game app only posts to a matching origin.

Session lifecycle

mint launch token (S2S, 60s, single-use)
      │
      ▼
iframe loads /play?token=…
      │  POST /api/play/session/init  { launchToken }
      ▼
session token + frozen bootstrap
      │  Authorization: Bearer <sessionToken> on every /api/play/* call
      ▼
heartbeat (idle bump + balance refresh) … logout / idle expiry
  • session/init exchanges the launch token for a session token and the bootstrap. The launch token is consumed here.
  • session/heartbeat bumps idle expiry and refreshes balance.
  • session/logout revokes the session immediately.

The bootstrap is frozen at init — the box, price, theme, locale, and currency are pinned for the session. (Live locale/currency changes use a separate channel — see Localization.)

Refresh & deep-linking

Launch tokens are single-use and expire in 60s, so an iframe can’t simply be reloaded from the same URL. To make refreshes and deep links work:

  1. The iframe reports its current location to your page via a navigation:changed message (route + params).
  2. Your page persists that location (URL hash, query, or storage) so it knows where the player was.
  3. On refresh, your page re-mints a launch token server-side targeting that location and re-embeds.

This keeps the host address bar in sync and lets a player refresh — or share a link — and land back where they were. See messaging for the message shapes and Localization for carrying locale/currency through a re-launch.

Within a single tab, a soft refresh with the same token is also restored from the game app’s own sessionStorage cache; the re-mint flow above covers everything else (new tab, shared link, expired token).

Sizing & responsiveness

The game app fills its frame. Give the iframe a responsive height (or listen for a resize message — see messaging) so the box page and lobby have room on mobile.

Sections