rudder-js-sdk/skills/rudder-web-sdk/reference/leaderboards.md

Leaderboards — client.leaderboards

LeaderboardsService (source: src/leaderboards/LeaderboardsService.ts). Plain call-and-response service, NOT observable — refetch explicitly.

Surface

const board = client.leaderboards.findBySlug('weekly-kills'); // cached handle
await board.submit(score);
const entries = await board.list(limit?);
board.getEntries();

LeaderboardHandle

class LeaderboardHandle {
  readonly slug: string;

  getEntries(): readonly RankEntry[];             // last fetched list, [] initially
  submit(score: number): Promise<void>;
  list(limit = 100): Promise<readonly RankEntry[]>; // fetches and caches
}

• findBySlug(slug) caches handles per slug — repeated calls return the same instance (and its cached entries).
• list(limit): limit <= 0 sends no limit to the server; default is 100.
• submit does not update the cached entries; call list() afterwards to see the effect.

Types

interface RankEntry {
  playerId?: string;
  playerName?: string;
  rank?: number;
  score?: number;
}

Notes

• No player-around-me or metadata endpoints are exposed by this SDK — submit and top-N list only.
• Scenario leaderboard nodes surface through client.effects.onLeaderboard (end(), rewardClaimed()) — see reference/scenarios.md.