Skip to content
ZokoGames

Log in

Data (cloud save)

Data (cloud save)

SDK.data stores small key/value saves in the portal so progress follows the player across devices and survives cleared browser storage. The API deliberately mirrors localStorage:

getItem(key: string): string | null
setItem(key: string, value: string): void
removeItem(key: string): void
clear(): void

All four are synchronous. The whole save is loaded when init() resolves, so reads never wait. Writes update memory immediately and sync to the portal in the background.

await SDK.init();

const level = Number(SDK.data.getItem("level") ?? "1");

function onLevelComplete(next) {
  SDK.data.setItem("level", String(next));
  SDK.data.setItem("stars", JSON.stringify(stars));
}

Values are strings. Store structured state with JSON.stringify and parse defensively.

How syncing works#

  • Writes are debounced by one second: several setItem calls in a burst become one upload.
  • If writes keep arriving, an upload still goes out at least every 30 seconds.
  • Pending writes are sent immediately when the page is hidden or closed (visibilitychange to hidden, pagehide).
  • If an upload fails, the data is kept in memory and retried with the next write.

Guests and signed-in players both get a save, but it lives in different places:

  • Signed-in players: the save is stored on the portal's servers and follows the account across devices and browsers.
  • Guests: the save is kept in the browser's own storage for the portal, so it survives reloads but not a cleared browser or another device.
  • When a guest signs in while playing, their save is uploaded if the account has no save for your game yet. If the account already has a save, the account's copy wins and the portal offers the player a reload, because the running game holds stale data. Plan for both outcomes: never assume the data you loaded at start is still the data in the store.

Limit#

The whole save, serialised as JSON, must stay under 1,048,576 bytes (1 MiB). A setItem that would exceed it throws dataLimitExceeded and changes nothing.

try {
  SDK.data.setItem("replay", bigString);
} catch (e) {
  if (e.code === "dataLimitExceeded") SDK.data.removeItem("replay");
}

Keep saves compact: store ids and numbers, not whole world snapshots.

Errors#

Code Meaning
dataLimitExceeded The write would push the save over 1 MiB. Nothing was written.
dataModuleDisabled The data module is not enabled for this game.
sdkNotInitialized, sdkDisabled See errors.

Because these methods are synchronous they throw rather than reject.

When to use something else#

  • Progress that must be shared between your own services, or tied to purchases, belongs on your server with the verified token.
  • Large assets and replays belong on your own storage.
  • Anything you cannot afford to lose should also be stored in a way you can recover. Treat cloud save as convenient, not as a database.

Local testing#

In local mode the save lives in localStorage under zoko-sdk-data. Delete that key (or use an incognito window) to simulate a new player.

Migrating from localStorage#

const migrated = SDK.data.getItem("migrated") === "1";
if (!migrated) {
  for (const key of ["level", "stars", "coins"]) {
    const v = localStorage.getItem(key);
    if (v !== null) SDK.data.setItem(key, v);
  }
  SDK.data.setItem("migrated", "1");
}

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