Launching Games

When a player clicks a game tile, the frontend requests a secure launchUrl from the platform; the platform establishes a session with the provider and returns a URL to load in an <iframe>.

Public surface

Member	Returns	Auth	Description
launchGame(gameId, mode)	Promise<GameSession>	required (REAL)	Start a game session and get the launch URL

Launch modes

Mode	Auth	Money	Notes
REAL	Required; an authenticated session with a wallet	Plays with real money; the provider reads and updates the wallet balance through the platform	Login required before launching
DEMO	Public	Free play, no funds, no wallet	Only offered when game.hasDemo is true

Rules

GIVEN an authenticated player with a wallet
WHEN launchGame(gameId, 'REAL') is called for an existing game
THEN a provider session is established and a GameSession is returned
     with a launchUrl to embed in an iframe.

GIVEN no authenticated session (or an expired one)
WHEN launchGame(gameId, 'REAL') is called
THEN the call rejects with the common UNAUTHORIZED error;
     route the player to login.

GIVEN a game whose hasDemo is false
WHEN launchGame(gameId, 'DEMO') is called
THEN the call rejects with GAME_DEMO_UNAVAILABLE;
     show "this game does not support free play."

GIVEN an unknown gameId
WHEN launchGame is called in any mode
THEN the call rejects with GAME_NOT_FOUND.

If the access token has expired, the SDK silently refreshes and retries once before surfacing an error (see State & Security). REAL launches are blocked during an active self-exclusion (RG_SELF_EXCLUDED; see Self-Exclusion & Reality Checks).

try {
  const session = await sdk.games.launchGame('game_sweet_bonanza', 'REAL');
  document.getElementById('game-iframe').src = session.launchUrl;
} catch (error) {
  // Branch on error.code; never on message text (see Error Reference)
}

GameSession

Launching is stateless for 1.0.x: the session is the launch URL plus its mode; load it in an iframe and manage the frame's lifecycle yourself. Session teardown/close events are a future capability.

type GameLaunchMode = 'REAL' | 'DEMO';

interface GameSession {
  sessionId: string;  // opaque; quote it in support tickets
  launchUrl: string;  // embed in an <iframe>
  mode: GameLaunchMode;
}

Error contract

Code	Error class	HTTP status	Trigger condition	Retryable
GAME_NOT_FOUND	GameNotFoundError	404	Unknown gameId	No
GAME_DEMO_UNAVAILABLE	DemoUnavailableError	409	DEMO mode on a game with hasDemo: false	No (launch REAL instead)
GAME_LAUNCH_FAILED	GameLaunchFailedError	502	The provider rejected or failed the session handshake	Yes (retry the launch)

Common errors (UNAUTHORIZED, NETWORK_ERROR, …) are defined once in the Error Reference.

Sandbox

All catalog games launch with a mock provider URL. REAL launches enforce the authenticated session exactly as production (the 401 gate); DEMO launches are public. Games without demo support (e.g. the seeded live-casino title) reject DEMO with GAME_DEMO_UNAVAILABLE.

Divergence flag: sandbox launch URLs point at a mock provider page, not a real provider; in-game balance movement is simulated only through the sandbox round controls (see Round History).