The leaderboard model
Two kinds of board, four different numbers called rank, and nothing to write.
What a leaderboard is, and the vocabulary the next page uses.
A leaderboard
A ranking of everyone in the community. It costs nothing to set up, and fans open it without being prompted, which makes it one of the cheapest things you can ship that people come back to.
The leaderboard is read-only. Nothing a fan does on it changes it. They climb it by doing quests and earning XP everywhere else in your product.
What the board ranks by, and the reset before a launch, are set in the Hub. Leaderboards in the Hub docs covers that side.
Two kinds of board
A community has two boards. Pick which one you show, or show both with a switcher.
| Kind | Ranks fans by |
|---|---|
LEADERBOARD_KIND.RESOURCE | The community's main resource, usually XP. The default. |
LEADERBOARD_KIND.QUESTS | How many quests they have completed |
That is all the scope there is. There are no season boards, date ranges or filters on the community leaderboard. An event has a leaderboard of its own, with the same row shape. It belongs to the event: Results and rewards.
Four numbers called rank
The most common bug on this page, so it gets its own section. Four different integers in the SDK look like a rank. Only one of them is a position on the board.
| Number | Where it lives | What it means |
|---|---|---|
row.rank | A row on the board | The fan's position in the standings |
viewerRank.leaderboardRank | The signed-in fan's own row | Their position in the standings |
membership.tier.rank | Membership | Which paid tier they are on. 1 is free. |
current.level | XP | Their level, which is a threshold, not a position |
A fan at position 128 can be level 12 on the Premium tier. Mixing those up puts the wrong number in the wrong column, and it looks plausible enough that nobody notices for a while.
| # | Fan | XP |
|---|---|---|
| 🥇 | fern#1000 Premium | 5,200 |
| 🥈 | kilo#8919 | 5,075 |
| 🥉 | mags#7838 | 4,950 |
| 4 | oswin#6757 | 4,846 |
| 5 | tamsin#5676 Premium | 4,721 |
| 6 | rook#4595 | 4,596 |
| 7 | idris#3514 | 4,492 |
| 8 | juno#2433 | 4,367 |
| 9 | pell#1352 | 4,242 |
| 10 | wren#9271 | 4,138 |
The fan's own row
A fan always wants to see where they are, however far down that is. The SDK reads their own position separately from the page of the board you are showing, so you can pin it at the top or the bottom regardless of which page is open.
A fan who is not signed in has no row. A fan who is signed in but has not earned anything yet is unranked. Both are normal states with their own display strings.
Membership does not gate it
Everyone can see the board, signed in or not, free or paid. Rows can carry the fan's membership tier, and it makes a good badge next to their name, but it changes nothing about who is on the board or where.