Skip to content
ZokoGames

Log in

Leaderboards

Leaderboards

Leaderboards are enabled per game in the developer console. Players are ranked inside a weekly season, and the best of each season earns trophies on their profile.

Concepts#

Configure these in the console, on your game's Leaderboard tab.

Setting Meaning
Score label How scores are described to players: XP, KDA, POINTS or MINUTES.
Sorting DESC (bigger is better) or ASC (smaller is better, for times).
Min and max value Scores outside the range are rejected. Default 0 to 999,999,999. On an incremental board the range applies to each submitted amount, not to the running total.
Cooldown Minimum seconds between submissions from the same player (counted from their last update). 0 for none.
Incremental When on, each submitted score is added to the player's season total, and must be greater than zero. When off, the player keeps their better score for the season; a worse score is accepted but changes nothing.
Guide Free text shown on the leaderboard page that explains how to score.
Encryption key A 32-byte key (base64) used to encrypt client submissions. Shown in the console.
API key For server submissions, starts with zlb_. Shown once; we store only a hash.

A season is one ISO week (for example 2026-W47). Seasons roll over on Monday at 09:00 UTC. When a season closes, ranks 1, 2 and 3 receive gold, silver and bronze trophies, and further top-1 %, top-5 % and top-10 % trophies are awarded once at least 10 players took part. Players with the same score share a rank.

Only signed-in players appear on a leaderboard. Guests cannot submit.

Client submission#

SDK.user.submitScore(options: { encryptedScore: string; score: number }): Promise<void>

encryptedScore proves the number came from your game: it is the score encrypted with your board's encryption key. When the board has a key, only the encrypted value counts; the plain score is ignored. When the board has no key yet, the plain score is used and encryptedScore must still be a non-empty string (the SDK rejects an empty one with invalidArgument). Generate the key in the console before you ship.

The scheme is AES-256-GCM, and the payload is bound to the player, the game and the moment it was made:

  1. Build the plaintext "<score>|<unix milliseconds now>", for example "4210|1767225600000". The score may be negative or have up to 6 decimals, with at most 15 integer digits.
  2. Generate a random 12-byte IV. It doubles as a one-time nonce, so use a fresh one for every submission.
  3. Encrypt the UTF-8 bytes with the game's 32-byte key and the additional authenticated data zoko-score-v1|<userId>|<gameId> (the player's id from getUser() and your game's id). The tag (16 bytes) is appended to the ciphertext.
  4. Send base64(iv || ciphertext || tag).

The portal rejects a payload made for another player or game, one older than 2 minutes (or from the future), and one it has already seen. Encrypt at the moment of submission; do not store or retry old payloads.

async function encryptScore(score, keyBase64, userId, gameId) {
  const raw = Uint8Array.from(atob(keyBase64), (c) => c.charCodeAt(0));
  const key = await crypto.subtle.importKey("raw", raw, "AES-GCM", false, ["encrypt"]);
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const data = new TextEncoder().encode(`${score}|${Date.now()}`);
  const additionalData = new TextEncoder().encode(`zoko-score-v1|${userId}|${gameId}`);
  const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData }, key, data));
  const out = new Uint8Array(iv.length + sealed.length);
  out.set(iv, 0);
  out.set(sealed, iv.length);
  return btoa(String.fromCharCode(...out));
}

async function finishRun(score) {
  const user = await SDK.user.getUser();
  if (!user) return;
  const encryptedScore = await encryptScore(score, GAME_KEY, user.__dangerousUserId, GAME_ID);
  await SDK.user.submitScore({ encryptedScore, score });
}
Warning

Anything shipped in the browser can be read by a determined player, including the key. The scheme stops casual tampering, not a motivated cheater. If your game has real competitive stakes, calculate the score on your own server and use the server API below.

A submission that cannot be read (wrong key, malformed payload) or that breaks a board rule (range, cooldown) is dropped by the portal without telling the game why, so a cheater learns nothing; the call itself still resolves. A player who is not signed in does not get an error either: the portal opens its sign-in prompt once per play session (so it can attach the score to an account) and the call resolves without recording anything. Submissions are limited to 30 per minute per player and game; beyond that the call rejects with rateLimited. When a score is accepted the portal shows the player's rank.

Server API#

For authoritative scores. Authenticate with your API key and send up to 100 scores per request (a request body over 100 KB is refused). userId is the userId claim from a verified token. Each key may make 1,000 requests per minute.

POST https://zokogames.com/api/v1/leaderboard/scores
X-API-Key: <your game's api key>
Content-Type: application/json

{ "scores": [ { "userId": "0b9c2e1a-8f2c-4d7e-9a11-2f6f3c1d4b55", "score": 4210 }, { "userId": "5e1d77a0-1a77-4c0b-8b3e-9d2c6a7f1e08", "score": 3987 } ] }
await fetch("https://zokogames.com/api/v1/leaderboard/scores", {
  method: "POST",
  headers: { "x-api-key": process.env.ZOKO_LEADERBOARD_KEY, "content-type": "application/json" },
  body: JSON.stringify({ scores: batch }),
});

Keep the API key on your server only. The same min, max, sorting, cooldown and incremental rules apply as for the client path. Each score is checked on its own, so one bad entry does not stop the others. The response has one result per submitted score, in order:

{
  "ok": true,
  "results": [
    { "index": 0, "userId": "0b9c2e1a-8f2c-4d7e-9a11-2f6f3c1d4b55", "ok": true, "score": 4210, "rank": 12 },
    { "index": 1, "userId": "5e1d77a0-1a77-4c0b-8b3e-9d2c6a7f1e08", "ok": false, "error": "validation" }
  ]
}

Per-score error values:

Error Meaning
no-active-season The leaderboard is disabled for this game.
user-not-found The userId is unknown or the player is banned.
validation The entry is malformed, outside the min and max range, or inside the cooldown.
internal-server-error Retry later.

The whole request fails instead (with no per-score results and { "ok": false, "error": ... }) in these cases:

HTTP status error
400 invalid-body (not { scores: [...] }), empty
401 invalid-api-key (missing, unknown or revoked)
404 leaderboard-not-found
413 too-many-items (more than 100), payload-too-large
429 rate-limited (a retry-after header says when to retry)

Each score item is { "userId": string, "score": number }.

Note

Generate and rotate the encryption key and the server API key on the game's Leaderboard tab (or the API keys page). A new key is shown once. Rotating the encryption key breaks any shipped build that still uses the old one.

Reading rankings#

Public rankings for a game are available without a key:

GET https://zokogames.com/api/leaderboard/<gameId>?scope=global&limit=10&season=2026-W47

scope is global, country or friends (friends needs a signed-in session and answers 401 otherwise). limit is 1 to 100 (default 10) and season (format YYYY-Www) defaults to the current one. The answer includes the season, when it ends, the sorting, the entries (rank, userId, username, avatarUrl, countryCode, score), the total, and the signed-in viewer's own row (me) and nearest neighbours. The game must be live and have the leaderboard enabled, otherwise the endpoint answers 404.

Design tips#

  • Submit once per run, at the end, not every frame.
  • For time-based games use ASC with MINUTES.
  • Show the player's own rank, not just the top ten.
  • Do not make the leaderboard the only reason to play; the weekly reset is a feature for new players too.

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