Leaderboards

Leaderboards show a user or group their ranking based on points, actions, or missions.

To create a leaderboard, you must:

1. Create the leaderboard structure - The structure defines what you want the leaderboard to track. This includes the leaderboard type (points, actions, etc.) and duration (alltime, weekly, monthly, etc.).

2. Create the leaderboard layout - The layout defines what users see when they view the leaderboard. This includes the name, filters, and formatting. There are different methods of creating the leaderboard layout depending on your program.

   • Impact block - use the Layouts tab in the Leaderboards view

   • Web components - use the Leaders web component

   • Custom user experience - use the GET /leaderboards/{leaderboardId}/leaders API

Nitro leaderboards build on-demand in the background (not real-time). The first API call to Nitro for a given type and duration of leaderboard initializes the leaderboard. Then, Nitro tracks that leaderboard moving forward for the remainder of the duration. The first call to Nitro for a leaderboard may, in some instances, return no results until Nitro finishes processing the leaderboard (this is also true if the configuration settings on the leaderboard change). All subsequent calls to the leaderboard for the remainder of the duration return immediate results.

Group Membership

You can filter user leaderboards by one or more group classes and group leaderboards by one group class (the selected group class must be a segment). A filtered leaderboard displays the points/missions/actions based on the user's current group membership. Show me an example

Using the following diagram as an example, if we filtered a leaderboard by Role, the Manager leaderboard would show users A, B, C, and D and the Non-Manager leaderboard would show users E, F, and G. You would not be able to filter by Sales Region as the group class is not a segment.

When a leaderboard is filtered by a specific group, the leaderboard totals are based on the user's current group membership, not their historical group membership. Any group a user is in at the time the points/actions/missions are earned will get those points/actions/missions. If a user changes groups, their points/actions/missions stay with the group where they were earned.

Point Discrepancies

Removing a mission or debiting points may cause point discrepancies with duration based leaderboards.

The point in time when you remove a mission is when the points are removed and applied to leaderboards. If you're using duration based leaderboards (e.g. monthly) and the mission is removed in the time period after the achievement, then points will not match. For example, if you have a monthly leaderboard and a mission is awarded in May and removed in June, the June leaderboard will show incorrect points. The July leaderboard points will be accurate. You want to remove the mission in the same cycle it was awarded and before the next cycling of the leaderboard points.

The same is true for crediting and debiting points. If you credit and then debit a user's points, you want to do both within the same leaderboard cycle.

See also

Action logging

Web components