Saving Player Progress in an HTML5 Game: localStorage, Iframes and Cloud Save

"My progress disappeared" is one of the most common complaints about browser games, and in most cases the game did save. The save just wasn't there when the player came back. If you ship HTML5 games, it helps to know why that happens and how to make your save code survive it.

localStorage is the default choice because it takes one line of code. It is also the least reliable place to keep something a player cares about:

• The player clears site data. Cleaning tools and "clear cookies and site data" settings wipe it along with everything else.
• Private windows. Storage may be unavailable, throw an error, or disappear when the window closes.
• Iframes on other sites. When your game runs inside an iframe on a page that belongs to someone else, modern browsers can block or partition third-party storage. The same game can behave differently on your own domain and on a partner's website.
• Browser limits. Safari can remove script-written storage for sites a user hasn't interacted with for a while.
• A new device. Local storage never follows the player to a phone or another computer.

Reading or writing storage can throw. Wrap every call so the worst case is "no save", not a frozen loading screen.

function readSave() {
  try {
    const raw = localStorage.getItem("mygame.save");
    return raw ? JSON.parse(raw) : null;
  } catch (e) {
    return null; // blocked, corrupted or missing
  }
}

function writeSave(data) {
  try {
    localStorage.setItem("mygame.save", JSON.stringify(data));
  } catch (e) {
    // quota full or storage blocked: keep playing
  }
}

You will change your game after launch. Add a version number to the save object and migrate old saves instead of discarding them. A player who loses a 10-hour save because you renamed a field will not come back.

const save = readSave() || {};
if (!save.version) { save.version = 1; save.coins = save.coins || 0; }
if (save.version === 1) { save.version = 2; save.skins = ["default"]; }

Saving only on a "Quit" button fails, because players close tabs. Save when something meaningful happens (level finished, purchase made) and also when the page is hidden:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") writeSave(state);
});
window.addEventListener("pagehide", () => writeSave(state));

Do not write on every frame. Writing a large object 60 times a second wastes battery and can slow low-end phones. Save on events, or debounce to once every few seconds.

When your game runs in the PlayKovo player, the SDK exposes a cloud save that follows the player's account across devices. It is two calls:

const result = await window.PlayKovoSDK.cloudSave.get();
if (result.ok && result.data) {
  loadFrom(result.data);
}

// later, after a level or purchase
await window.PlayKovoSDK.cloudSave.set(state);

Treat cloud save as an addition, not a replacement:

• Both calls resolve with an object. Check ok. When it is false (no signed-in player, a timeout after about six seconds, a network error), fall back to your local save and carry on.
• Guests do not have a cloud save. Keep the local save working for them.
• If you have both a local and a cloud save, compare a timestamp or progress value you store yourself and keep the more advanced one. Do not silently overwrite a longer save with a shorter one.
• Keep the payload small: IDs, counters and unlocked items, not whole level maps you can regenerate.

1. Play, close the tab, reopen: is the progress there?
2. Open the game in a private window: does it still start?
3. Embed it in an iframe on a different domain: does the save still work, or at least fail quietly?
4. Load a save written by your previous version: does the migration run?
5. Hand it a corrupted value (localStorage.setItem("mygame.save", "{")): does the game start with a fresh save?

If you want to see how players run into this from the other side, read why browser games lose your progress. For the technical side of how PlayKovo hosts and loads your build, see how to prevent old cached files from breaking game updates.