GameSDK live-ops reference

Written for: ＋ Written for
Deprecated: ＋ Deprecated
Applies to: ＋ Applies to

AdminUpdated Sep 22, 2026

GameSDK live-ops reference

Reference for the three live-ops methods on the GameSDK global: getConfig, trackEvent and reportError. For concepts, patterns and dashboards, see Remote config, analytics & crash reporting. For the rest of the SDK and the game lifecycle, see GameSDK core reference.

Method	Returns	Sign-in required	Needs an active play session
`getConfig()`	`Promise<object>`	No	No
`trackEvent(name, props?)`	`undefined`	No	Yes
`reportError(message, extra?)`	`undefined`	No	Yes

A play session opens when your game calls GameSDK.start(), or when it requests a replay seed. Sessions only open for published games.

`getConfig`

GameSDK.getConfig(): Promise<Record<string, unknown>>

Resolves with your game's live remote config, the JSON object you set in the dashboard's Live config panel or with PUT /v1/dev/games/:id/config.

Parameters

None.

Resolves with

The stored config object, exactly as saved. For example:

{ "difficulty": "hard", "dropRate": 0.08, "features": { "newBoss": true } }

The result is {} when no config has been set.

Behaviour

Situation	Result
First call on this page load	Fetches the config. Resolves when the platform answers.
Calls made while that fetch is in flight	Share the same request and resolve with the same object.
Later calls after a successful answer	Resolves immediately with the same cached object. No new fetch.
The platform can't load the config (network or server error, unknown game)	Resolves `{}`. Nothing is cached, so the next call fetches again.

Never rejects.
{} can mean "no config set" or "couldn't load it this time". Always merge over your own defaults, and call again later (for example, at the start of the next round) if you need to retry.
The cache lasts for the page load. Config saved after the game loaded isn't seen until the player reloads.
The cached object is shared between calls. Don't mutate it.

Limits

Limit	Value
Config size	Under 16 KB of serialized JSON (enforced when you save)
Top-level type	Must be a JSON object

The config can be read publicly without authentication. Don't store secrets in it.

Example

const DEFAULTS = { difficulty: "normal", dropRate: 0.1 };

GameSDK.getConfig().then((remote) => {
  const cfg = { ...DEFAULTS, ...remote };
  startGame(cfg);
});

`trackEvent`

GameSDK.trackEvent(name: string, props?: Record<string, unknown>): void

Records a custom analytics event for the current play session. The event is sent without waiting for a result.

Parameters

Name	Type	Required	Constraints
`name`	`string`	Yes	1–64 characters, matching `^[A-Za-z0-9_.\- $:]+$` (letters, digits, `_`, `.`, `-`, space, `$`, `:`). Non-strings are converted with `String()`. Names longer than 64 characters are cut to 64 by the SDK. `"$error"` is reserved for crash reports.
`props`	plain object	No	At most 50 top-level keys. Serialized JSON under 4,000 characters. Nested values allowed. Must be a plain object: arrays are rejected, and values that can't be sent between windows (functions, DOM nodes) cause the event to be dropped.

Returns

undefined. There's no promise and no confirmation.

Failure behaviour

All failures are silent. The event is simply not recorded:

Cause	What happens
`name` is empty, `null` or `undefined`	Ignored by the SDK, nothing sent
No active play session (before `GameSDK.start()`, or the game isn't published)	Dropped
Name has disallowed characters	Rejected by the server (`400`)
More than 50 prop keys	Rejected (`400 too_many_props`)
Props JSON of 4,000 characters or more	Rejected (`400 props_too_large`). Not truncated.
More than 120 events in a minute for this session	Rejected (`429 rate_limited`)
Platform-wide per-IP request limit reached	Rejected (`429`)

Your game never sees these status codes. Test with the dashboard's Analytics panel to confirm events arrive.

Limits

Limit	Value
Rate	120 events / minute / play session (shared with `reportError`)
SDK message rate	30 SDK messages / second across all `GameSDK` calls
Sampling	None. Every accepted event is stored.
Reporting window	The dashboard and API aggregate the last 30 days

Example

GameSDK.start();
// …
GameSDK.trackEvent("level_complete", { level: 3, timeMs: 42000, stars: 2 });

`reportError`

GameSDK.reportError(message: unknown, extra?: Record<string, unknown>): void

Records a crash or error report. It appears in the Crashes list of your game's Analytics panel, and in errors from GET /v1/dev/games/:id/analytics.

Parameters

Name	Type	Required	Constraints
`message`	any	Yes	Converted with `String()` and cut to 500 characters. `null`/`undefined` become `"error"`.
`extra`	plain object	No	Its top-level enumerable keys are copied into the report. A key named `message` is ignored: the `message` argument always wins. Anything that isn't an object is ignored.

What is sent

An analytics event named $error with:

{ "message": "<message, ≤500 chars>", "...": "each top-level key of extra" }

Returns

undefined.

Failure behaviour and limits

These are the same as trackEvent: an active play session is required, at most 50 keys, JSON under 4,000 characters, and 120 events per minute per session (shared with trackEvent). All failures are silent. Reports over the size limit are dropped whole, so cut long stack traces yourself.

Error objects passed as extra contribute nothing, because their message and stack aren't enumerable. Copy the fields you need into a plain object.

Where it shows

The dashboard groups reports by exact message text and shows the top 20 over the last 30 days, with counts. extra fields are stored but not displayed.

Example

try {
  loadLevel(n);
} catch (e) {
  GameSDK.reportError(e.message, {
    where: "loadLevel",
    level: n,
    stack: String(e.stack || "").slice(0, 1500),
  });
}

Remote config, analytics & crash reporting: the guide - GameSDK core reference: start(), ready() and the rest of the SDK
Errors & limits: rate limits and error codes

Was this page helpful?

GameSDK live-ops reference