Leaderboard

A leaderboard ranks buddies by a scoring function over a window. It's optional — not every product benefits from ranking, and ranking can be stressful. When it fits, though, it's a strong pull.

What defines a leaderboard

• Metric — coins earned, skills-leveled, streaks completed, a custom sum.
• Window — all-time, monthly, weekly, custom cohort.
• Scope — global (across all buddies of the customer), per-audience, or per-group (classroom, team, etc.).
• Visibility — public to all, visible only to the buddy's own rank ±3 entries, or admin-only.

Example

Weekly coin leaderboard, scoped to the students audience. Resets every Monday. Each student sees their own rank plus the five nearest neighbours; admins see the full list.

How it computes

Leaderboards are snapshotted periodically (default every 10 minutes) and cached. Reads from the widget or API hit the snapshot, not the live aggregate — this keeps performance stable regardless of scale.

A refresh fires leaderboard.snapshot.ready if you want to react on your backend.

Gotchas

• Leaderboards can demotivate the bottom ranks. Consider scoping visibility to "within ±N of me" rather than the whole list.
• Per-group leaderboards require you to pass a groupId on events; without it, the event doesn't count toward group ranking.
• Weekly/monthly windows reset in UTC. Cross-timezone products may see a sudden "reset" mid-day for some users.