Core SDK functionality

The methods in this document live on the global SDK instance, window.RollerzSDK — the same object you get after loading the SDK script. They cover core concerns: SDK initialization and user management (bridge setup, game identity, and fetching a server-backed player snapshot).

---

The core module

The core surface of the SDK is the set of methods that are not specific to a game provider: init, getGameId, getUser, generic call, and bridge on / off. This page documents init and getUser in depth. For a compact index of all methods, see the API reference.

---

Initialization (init)

Call await sdk.init(gameId, options?) once at startup, before any other SDK call. It creates the hidden bridge iframe, loads session context, and exchanges a GAME_LOADED message so subsequent API calls can flow through the bridge. Calling init twice throws (SDK is already initialized).

Parameter	Type	Description
gameId	string	Unique identifier for your game (used by the SDK server and session resolution).
options	InitOptions	Optional configuration (see table below).

InitOptions

Field	Type	Description
platformEvents	Record<string, (payload?) => void>	When the host page sends a postMessage with a matching event type, the SDK invokes the callback. Use with platformSource.
platformSource	string	postMessage source the SDK listens for (default: 'rollerz-platform').
enableLogging	boolean	When true, enables the SDK’s structured debug log (useful when diagnosing bridge or API issues).

Returns: Promise<void>

const sdk = window.RollerzSDK;

await sdk.init('my-game-id', {
  enableLogging: true,
  platformEvents: {
    MUTE_CHANGED: (payload) => {
      myAudio.muted = payload?.muted ?? false;
    },
  },
});

InitOptions is defined in @rollerz/types.

After init, provider methods (e.g. sdk.go3.openGame()) and getUser() (once a session exists) are available.

getGameId()

Returns the gameId string passed to init, or null if init has not run. Documented in the API reference.

---

Player snapshot (getUser)

The SDK exposes getUser() to fetch a small, typed JSON object from the SDK server (POST /api/user). It mirrors common Reelsoft GDK fields the RGS returns on responses such as opengame and placebet: balance, currency, session id, player display name, and session statistics (play time, rounds, win/loss in cents).

The SDK does not persist this data. Your game or host app decides whether to cache it, show it in the UI, or ignore fields.

Prerequisites

1. Call await sdk.init(gameId, options?) so the bridge is ready.
2. Open a provider session (e.g. await sdk.go3.openGame()). The server stores the active session keyed by the bridge’s X-Client-Id; without an open session, /api/user returns 404.

Then:

const user = await sdk.getUser();

TypeScript

getUser() resolves to User from @rollerz/types:

import type { User } from '@rollerz/types';

const user: User = await sdk.getUser();

See Types — User for field definitions.

HTTP (SDK server)

Method	POST
Path	/api/user
Body	{} (empty JSON object)
Headers	Content-Type: application/json, X-Client-Id (set automatically by the bridge)

200 — JSON body matches User.

404 — No active provider session for this client id ({ "message": "No active session" }).

The route constant USER_ROUTE / API_ROUTES.USER in @rollerz/types is '/api/user'.

RGS mapping

The math server often sends:

• Top-level playerAlias, balance, currency, sessionId
• A nested session object with seconds, rounds, winLoss (amounts in cents)

The SDK server merges those into the active session and exposes them on User as flat optional fields seconds, rounds, winLoss (the nested GDK session is not recreated on the wire shape returned by getUser()).

If the RGS omits a field, it will be absent on the JSON until a later response supplies it.

Example (Rock Smash)

The Smash Game example calls getUser() after openGame() and after bet/collect so the top bar player alias stays aligned with the server when the operator supplies it.