Skip to main content

QSPlaySDK.data

A simple key-value store for saving the player's progress. For when to use it instead of your own save backend, see Requirements · Progress Storage.

The portal never reads what you store here. To show the player's level in their portal profile, report it with game.reportPlayerLevel().

How it works​

data.* works the same way for a guest and for a signed-in player. The game doesn't choose or see where the bytes physically end up:

  • Guest — the data lives in the portal page's storage, scoped to the game.
  • Signed-in player — the data goes to the portal's server, is scoped to the account, and is available from any device where the player is signed in.
  • On sign-in the portal itself, once and without the game's involvement, moves whatever the player managed to save as a guest into the account (a key that already exists in the account is not overwritten).

One game's keys aren't visible to other games — the scope is set by the host.

Write debouncing​

setItem/removeItem/clear aren't sent to the host one by one — the SDK accumulates them until 1 second of quiet and sends the whole set of changes in a single request. Several consecutive calls on the same key collapse — only the last one reaches the host. If calls come in continuously and there is never 1 second of quiet, a forced flush still happens no later than 30 seconds after the start of the batch.

QSPlaySDK.data.setItem("progress", { level: 1 });
QSPlaySDK.data.setItem("progress", { level: 2 }); // cancels the previous one — only { level: 2 } goes to the host

getItem() called before the flush sees the changes that have already been applied but not yet sent (your own setItem/removeItem/clear) — reading right after writing is safe. If a single batch contained a clear() followed by a new setItem() on the same key, the key will appear again: clear rolls back only what came before it in that same batch, not what happened after.

The promise from setItem/removeItem/clear resolves (or rejects, for example with DATA_QUOTA_EXCEEDED) only when the batch has actually been sent to the host and has received a response — so it may hang for almost a second in the ordinary case and up to 30 seconds with continuous writing. If it matters to your game to wait for the actual save (rather than merely record the intent), awaiting the promise guarantees that, just not instantly.

Reading a value​

data.getItem(key):

const value = await QSPlaySDK.data.getItem("progress");
// nothing saved: null
// saved: exactly what was put there via setItem, as is — without a wrapper

Writing a value​

data.setItem(key, value). value is any JSON-compatible value (string, number, boolean, null, array, object) — there is no need to serialize it manually.

await QSPlaySDK.data.setItem("progress", { level: 3, coins: 120 });

In total, 1 MB is available per player per game — measured as the JSON size of all saved keys combined. When it is exceeded, the promise rejects with an SdkError, error.code === "DATA_QUOTA_EXCEEDED" (see Errors):

try {
await QSPlaySDK.data.setItem("progress", hugeObject);
} catch (error) {
if (error.code === "DATA_QUOTA_EXCEEDED") {
// saving failed — for example, warn the player that storage is full
}
}

Keep the saved data compact: progress, settings, achievements — not full snapshots of the game state or assets.

Removing a value​

data.removeItem(key):

await QSPlaySDK.data.removeItem("progress");

Clearing all data​

data.clear() removes all keys of the current game for the current player (a guest or an account, depending on who is currently active).

await QSPlaySDK.data.clear();