📘

Limited availability

The leaderboard feature is currently in the beta stage and is available via API only.

What Can Admins Do?

Manage Leaderboards

You can create, and delete leaderboards. This allows you to set up leaderboards based on different metrics that are important for their application.

Configure Leaderboard Score

You can define the score property which determines how users are ranked. They can set which numeric property would be used to count user scores.

For example, if you've picked $.experience and you have a user with 25 experience units, then their score would be 25 and their position would be determined by the scores (experience units) of the other users in that leaderboard.

Configure Leaderboard tiers

You can define a "tier" property to classify users into separate groups within a single leaderboard. These tiers share the same leaderboard but have their own rankings and positions for their respective users.

For example, if you set $.level as the tier property and have 15 users at level 1 and 25 users at level 2, the 15 users at level 1 will be ranked together in their own tier, and the same applies to the 25 users at level 2.

Users can belong to only one tier per leaderboard configuration since they can only match one tier at a time. However, they can appear in different leaderboards if those leaderboards are based on entirely different configurations.

View Leaderboard Configurations

You can retrieve all leaderboard configurations. This helps in monitoring and analyzing the setup of leaderboards.

Distribute Rewards

Rewards can be distributed to users based on their positions on the leaderboard at the time of rotation. A rotation marks the conclusion of the current leaderboard, the distribution of rewards, and the reset of leaderboard entries for the next cycle.

The "First Rotation Start Time" property specifies when the initial rotation should occur. If this property is not set, the first rotation will automatically be scheduled as "now + rotation period".

Examples of Reward Distribution:
1st Place: 1000 tokens and a T-shirt.
2nd to 5th Place: 200 tokens each.
6th to 20th Place: 20 tokens each.

🔄

Automatic updates

The system can handle events such as user creation and property changes to keep the leaderboards up-to-date. This ensures that the leaderboard data is always current and accurate.

What Can Players Do?

View All Their Leaderboards

Players can view any leaderboard they are eligible to participate in, with the option to see more details if needed.

Participate in a Leaderboard

Players who meet the criteria for any existing or new leaderboard are automatically added to it.

Check Their Position

Players can check their current ranking on a specific leaderboard.

How to start?

1. Go to the Leaderboards section and click on Create.
2. Pick the score property, for example $.experience.
3. (Optional) Pick the tier property, for example $.level. Users with the same level will compete on the same leaderboard.
4. Pick the rotation period, which can range from 10 minutes to 4 weeks. At the end of each period, the system distributes rewards based on user positions.
5. (Optional) Specify the First Rotation Start Time. If not set, the first rotation will default to 'now + rotation period'. After this initial rotation, the chosen period will be used for subsequent rotations.
6. (Optional) Set the rewards users will receive based on their positions within the leaderboard.

Benefits

Engagement: Encourages users to stay engaged by providing a competitive environment.
Transparency: Users can see their progress and understand how they rank compared to others.
Motivation: Provides motivation for users to improve their performance and climb the leaderboard.