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(): voidAll 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
setItemcalls 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 (
visibilitychangeto 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");
}