Cloud saves in practice
Cloud saves in practice
The data module is a localStorage-shaped store: synchronous reads, background writes, 1 MiB for the whole save. This guide covers the design questions that bite later.
One key or many#
Each setItem is cheap, and several writes in a burst become a single upload. Prefer a few focused keys over one giant blob, so a corrupt value does not lose everything:
SDK.data.setItem("profile", JSON.stringify({ v: 2, name, coins, unlocked }));
SDK.data.setItem("settings", JSON.stringify({ v: 1, music, sfx }));
SDK.data.setItem("run", JSON.stringify({ v: 1, level, seed })); // small checkpoint, not a replayThe 1 MiB limit counts the whole save serialised as JSON. Store ids and numbers, not world snapshots. A setItem that would break the limit throws dataLimitExceeded and writes nothing.
Version every value#
Players keep saves for years. Put a version in each value and migrate on load:
function load(key, version, migrate, fallback) {
try {
const raw = SDK.data.getItem(key);
if (!raw) return fallback;
let obj = JSON.parse(raw);
while (obj.v < version) obj = migrate[obj.v](obj);
return obj;
} catch {
return fallback; // corrupt or unreadable: start clean, never crash
}
}Write at meaningful moments#
Save when something worth keeping changed (level complete, purchase, setting), not every frame. The SDK debounces for one second, uploads at least every 30 seconds while writes continue and flushes when the page is hidden or closed. Do not build your own timer around that.
Guests and signing in#
Signed-in players have a save on the portal's servers. Guests have a save in the browser. When a guest signs in during play:
- If the account has no save for your game, the guest's progress is uploaded and becomes the account's save.
- If the account already has a save, the account's save wins and the portal offers the player a reload, because your running game holds data that is no longer the store's.
Handle this by listening for sign-ins and re-reading your state when the game starts again, and never assume the first read is final:
SDK.user.addAuthListener(() => {
// Cheap and safe: persist what you hold now; the portal merges as described above.
SDK.data.setItem("profile", JSON.stringify(currentProfile()));
});Keep the browser-local fallback honest#
Do not use localStorage for progress. Inside the portal's frame it may be partitioned or cleared; SDK.data follows the player. If you are migrating existing players, copy old keys once (see data).
When the SDK is disabled#
Without the SDK (environment is "disabled"), SDK.data throws sdkDisabled. Wrap storage in a tiny adapter that falls back to localStorage for standalone runs:
const store = {
get: (k) => (live ? SDK.data.getItem(k) : localStorage.getItem(k)),
set: (k, v) => (live ? SDK.data.setItem(k, v) : localStorage.setItem(k, v)),
};Things not to store#
- Anything that must be authoritative or tied to payments: keep it on your server and verify the player with the token.
- Secrets, tokens and personal data.
- Large assets and replays.
Testing#
- Local mode keeps the save in
localStorageunderzoko-sdk-data; delete that key for a new player. - Pass
?user_response=logged_outto test the guest path, then?show_auth_prompt_response=user1and press your sign-in button to test the upgrade. - In the Preview tool the "Data module used" checklist item ticks when your game writes.