Leaderboards step by step
Leaderboards step by step
The leaderboards reference has the contract. This guide is the order to set things up in.
1. Decide what the board measures#
| You want to rank | Sorting | Incremental | Label |
|---|---|---|---|
| Best single score | Highest first (DESC) |
Off | POINTS or XP |
| Fastest time | Lowest first (ASC) |
Off | MINUTES |
| Total progress this week | Highest first | On: each submission adds to the weekly total | XP |
Boards reset every week (Monday 09:00 UTC). At the end of the week, ranks 1 to 3 earn gold, silver and bronze trophies on their profile; with at least 10 players, the top 1 %, 5 % and 10 % earn trophies too.
2. Configure it in the console#
Open the game, Leaderboard, set the rules and press Save rules first. Then generate the keys: the encryption key for the game client and the server API key for your backend. A new key is shown once; copy it immediately. Rotating the encryption key breaks builds that still use the old one.
- Set the minimum and maximum to values a legitimate player can reach. Anything outside is dropped. On an incremental board the range applies to each submitted amount, not to the total.
- Set a cooldown to stop spam submissions (for example 10 seconds).
- Write a one-line guide that tells players how to score.
3. Submit from the game (client)#
const KEY = "<encryption key from the console>";
const GAME_ID = "<your game id>"; // anything in a browser can be read; see the warning below
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 additionalData = new TextEncoder().encode(`zoko-score-v1|${userId}|${gameId}`); // binds the payload to this player and game
const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData }, key, new TextEncoder().encode(`${score}|${Date.now()}`)));
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; // guests do not appear on boards
await SDK.user.submitScore({ encryptedScore: await encryptScore(score, KEY, user.__dangerousUserId, GAME_ID), score });
}Encrypt at the moment you submit: payloads are bound to the player and game, expire after 2 minutes and work once. Submit once per run, at the end. The call resolves whether or not the score was accepted. A guest who triggers a submission gets the portal's sign-in prompt once per session instead. Players are limited to 30 submissions per minute per game.
The client path stops casual tampering, not a determined cheater, because the key ships in the browser. For competitive games compute the score on your server and use the server API.
4. Submit from your server (authoritative)#
- The game sends
await SDK.user.getUserToken()with the run to your server. - Your server verifies the token against the JWKS, checks the
gameIdclaim and takesuserId. - Your server validates the run and posts the score:
const res = 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: [{ userId, score }] }),
});
const { ok, results } = await res.json(); // results[i].ok, .rank, .score or .errorBatch up to 100 scores per request. The API key must never be shipped in the game.
5. Show it to players#
The portal shows the leaderboard next to the game and refreshes the player's rank after an accepted submission. To show ranks inside your own UI, read the public endpoint:
const r = await fetch(`https://zokogames.com/api/leaderboard/${GAME_ID}?scope=global&limit=10`);
const { entries, me, neighbours, season, seasonEndsAt } = await r.json();6. Test#
- Local mode accepts
submitScoreand does nothing: it has no board. Use the Preview tool to confirm the call is made ("A leaderboard score was submitted" in the game's preview checklist), and test acceptance on a build in basic launch with a real account. - If scores seem to vanish, check in this order: the player is signed in, the board is enabled, the value is inside min and max, the cooldown has passed, the key in the build matches the console key.