Game SDK Reference

Integrate your HTML5 game with the platform in minutes.

Version0.1.0·Protocol1.0.0

Installation

Add the following script tag to your game's <head>. The SDK is hosted on the platform and loaded automatically when the game runs inside the iframe.

<script src="/sdk/game-sdk.js"></script>

The SDK exposes a singleton at window.GamePlatform. You do not need to instantiate it.

Quick start

async function main() {
  const { userId, locale } = await window.GamePlatform.init();
  // userId is null for anonymous players

  // Submit an intermediate score during gameplay
  await window.GamePlatform.submitScore(1200);

  // When the game ends
  window.GamePlatform.reportGameOver(1200);
}

main();

Lifecycle events

The platform may pause your game (e.g., when a dialog opens or the tab is hidden). Listen to these events to pause animations and mute audio.

window.GamePlatform.on("pause", () => {
  myGame.pause();
});

window.GamePlatform.on("resume", () => {
  myGame.resume();
});

API reference

init() → Promise<{ userId, locale }>

Must be called before any other method. Returns the authenticated user's ID (null for anonymous players) and the BCP 47 locale string (e.g. en, pt). Times out after 10 seconds.

submitScore(score, meta?) → Promise<{ ok }>

Submit an intermediate score during gameplay. Can be called multiple times. score must be a non-negative safe integer. meta is an optional JSON-serialisable object (max 64 keys).

reportGameOver(score) → void

Report the end of a game session. Automatically includes elapsed time since init(). Separate from submitScore because games may submit intermediate scores during play.

showRewardedAd() → Promise<{ rewarded }>

Request a rewarded ad. Returns { rewarded: true } if the user watched the full ad. Times out after 30 seconds.

const { rewarded } = await window.GamePlatform.showRewardedAd();
if (rewarded) grantExtraLife();

showInterstitial() → Promise<void>

Show a non-rewarded interstitial ad (e.g., between levels). Resolves when the ad completes. Times out after 30 seconds.

track(name, props?) → void

Send a custom analytics event to PostHog. name must match /^[a-z][a-z0-9_]*$/ (lower_snake_case). props is optional with max 32 keys. The platform automatically adds game_id and session_id.

window.GamePlatform.track("level_complete", { level: 3, stars: 2 });

saveProgress(key, value) → Promise<void>

Persist arbitrary JSON-serialisable data. For authenticated users, data is stored in Supabase; for anonymous players, it falls back to localStorage. Key must be 1–64 characters matching [a-zA-Z0-9_.:-].

loadProgress(key) → Promise<unknown>

Retrieve previously saved data. Returns nullif no value exists for the key — use this as the "fresh start" signal.

const saved = await window.GamePlatform.loadProgress("save_slot_1");
if (saved === null) startNewGame();
else restoreGame(saved);

on(event, handler) / off(event, handler)

destroy() → void

Remove all event listeners and clear pending timers. Call this when unloading the game iframe. Optional but recommended.

Constraints

Parameter	Constraint
`score`	Integer, 0 – Number.MAX_SAFE_INTEGER
`progress key`	1–64 chars, pattern [a-zA-Z0-9_.:-]
`track name`	/^[a-z][a-z0-9_]*$/ (lower_snake_case)
`meta keys`	Max 64 keys, JSON-serialisable values
`track props`	Max 32 keys

← Submit a Game Developer Guidelines →