Skip to content
ZokoGames

Log in

Quick start

Quick start

About ten minutes from a plain HTML5 game to a build you can upload. If you use an engine, follow the same steps with the matching engine page. If you would rather start from working code, copy a starter kit: html5-minimal is a single-file canvas game that already calls every relevant SDK method.

1. Load the script (1 minute)#

Add the SDK before your game code. The URL is versioned (v1) and stays backwards compatible within that major version.

<script src="https://sdk.zokogames.com/zokogames-sdk-v1.js"></script>

The script defines window.ZokoGames.SDK. Everything below uses that object. With a bundler, keep this script tag and read the global; the Vite starter kit includes typings.

2. Initialise once, then start your game (2 minutes)#

init() resolves when the SDK knows where it is running. Call it once at startup. It never rejects and is safe to call twice.

<script>
  const SDK = window.ZokoGames.SDK;

  async function boot() {
    await SDK.init();
    console.log("SDK environment:", SDK.environment); // "zokogames", "local" or "disabled"

    if (SDK.environment !== "disabled") {
      const applySettings = (s) => audio.setMuted(s.muteAudio);
      applySettings(SDK.game.settings);
      SDK.game.addSettingsChangeListener(applySettings);
    }
    startGame(); // the game must run in every environment
  }

  boot();
</script>
Important

When SDK.environment is "disabled" every other SDK member fails with sdkDisabled (properties throw, methods reject). Your game must still run, so branch on the environment or wrap calls instead of assuming the SDK is there.

3. Report gameplay (2 minutes)#

Call gameplayStart() the moment input is live (not while a menu is open) and gameplayStop() on pause, game over, menus and level-complete screens.

function onLevelBegin() { SDK.game.gameplayStart().catch(() => {}); }
function onLevelEnd()   { SDK.game.gameplayStop().catch(() => {}); }

For basic launch this one event (gameplayStart) is all the SDK integration we need.

4. Show an ad at a natural break (2 minutes)#

Ask for a midgame ad between levels. Pause and mute inside adStarted, resume inside adFinished and adError. Ads only run for games in full launch, so while you test in basic launch or locally you will see the local placeholder or an adsDisabled error, and the code path is the same.

async function betweenLevels() {
  await SDK.ad.requestAd("midgame", {
    adStarted: () => { game.pause(); audio.mute(); },
    adFinished: () => { audio.unmute(); game.resume(); },
    adError: (error) => { console.warn("ad skipped:", error.code); audio.unmute(); game.resume(); },
  });
  nextLevel();
}

requestAd resolves only after adFinished or adError has been delivered, so the line after the await is a safe place to continue.

5. Save progress (1 minute)#

The data module has the same shape as localStorage, but follows the player across devices.

const best = Number(SDK.data.getItem("best") ?? "0");
function onGameOver(score) {
  if (score > best) SDK.data.setItem("best", String(score));
}

6. Test it (2 minutes)#

Serve the folder over HTTP (not file://) on localhost. The SDK switches to its local mock: ads become a three-second overlay, banners become dashed placeholder boxes, and a fake signed-in user is available.

npx http-server . -p 8080
# open http://localhost:8080/?sdk_debug=true

With sdk_debug=true every SDK call is logged to the console. Then open the Preview tool, enter your local address and watch the same calls arrive inside the real portal frame, with a live checklist of what you have integrated. See testing.

7. Zip and upload#

Zip the contents of your build so that index.html is at the root of the archive (a single top-level folder is also accepted). Use only relative paths. Then create a game in the developer console, upload the zip and read the validation report. The requirements checklist lists everything the validator and reviewers check.

Next steps#

Something unclear, wrong or missing on this page? Tell us through support · Test your game in the preview tool