Skip to main content

​
What are Leaderboards?

Leaderboards are social competitions between users of your application. Use leaderboards to increase engagement and foster social interaction.

​
Types of Leaderboards

Leaderboards in Trophy can be one of a few different types.

​
Perpetual Leaderboards

Perpetual leaderboards never reset. Once started they continually track and rank users progress over time forever, or until the configured end date.

​
Repeating Leaderboards

Repeating leaderboards can be configured to reset after any arbitrary number of days, months or years. In Trophy each instance of a repeating leaderboard is called a ‘run’. For example, a monthly leaderboard would have 12 runs in a year, but a daily leaderboard would have n runs in a month where n is the number of days in a given month. Repeating leaderboards reset all ranks at the start of each run giving new users an equal chance to compete with existing users. Trophy tracks the rankings in each run of a repeating leaderboard individually and provides APIs to fetch ranking data on historical runs.

​
Handling Time Zones

If you have tracked users’ time zones with Trophy, these will be used to ensure that each user has an equal chance of winning no matter where they are in the world. In practice this means leaderboards are finalized and winners chosen about 12 hours after they naturally finish in UTC to allow time for users in all time zones to make their final push.

​
Tips for Weekly Leaderboards

As the start of the week can be different in different countries, there is some debate about how to manage weekly leaderboards correctly and consistently. We’ll be adding better support for weekly leaderboards in the future based on customer requests, so if that’s you let us know! However Trophy leaderboards will cover 90% of weekly use cases, so here’s what we suggest if you want to set one up. To create a weekly leaderboard, set up a repeating leaderboard on a 7 day schedule and set the start date to be the next occurring first day of the week. While you wait for the start date to come around, the leaderboard will be in scheduled status and will automatically go live on the start date. This will make sure each run of the leaderboard consistently tracks the start and end of each week that your users are familiar with.

​
Ranking Logic

Leaderboards in Trophy are configurable to rank participants in a number of different ways to support common use cases.

​
Ranking Methods

The ranking method of a leaderboard determines on what dimension participants will be ordered.

​
Metric Rankings

Metric leaderboards are linked to an existing Trophy Metric and rank users based on their progress against it. Use metric leaderboards if you just want to rank users based on a single interaction.

​
Points Rankings

Points leaderboards are linked to an existing Trophy Points System and automatically rank users according to their total points. Use a points leaderboard if you want to rank users based on a combination of metrics, achievements or other Trophy features.

​
Streak Rankings

Streak leaderboards rank users based on their current streak length.
Streak leaderboards can only be perpetual.

​
Ranking Breakdowns

Leaderboards in Trophy can be configured to group users into smaller subsets according to a specific custom user attribute.
We consider using breakdowns best practice as smaller, more socially-connected leaderboards often have higher engagement than global leaderboards. This is why we limit leaderboards to a maximum of 1,000 participants.If you think you want to create a leaderboard with a higher number of participants than this, instead consider using breakdown attributes.
On the leaderboard configuration page, create or select your user attribute in the ‘Breakdown Attribute’ field. Trophy will automatically start grouping users into smaller leaderboards based on the values of your chosen attribute for each of your users.
To fetch rankings for a particular group of users with a specific attribute value, use the leaderboard rankings API, specifying the attribute value in the userAttributes parameter as follows: 
curl --request GET \
  --url https://api.trophy.so/v1/leaderboards/{key}?userAttributes=city:london \
  --header 'X-API-KEY: <api-key>'
If you wish to fetch rankings for a particular group of users with a specific combination of user attributes, create a new attribute to track the combination and use that as your breakdown attribute as follows: 
curl --request GET \
  --url https://api.trophy.so/v1/leaderboards/{key}?userAttributes=region_city:southeast_london \
  --header 'X-API-KEY: <api-key>'

​
Start & End Dates

Use start and end dates to control the window within which leaderboards are actively ranking users.

​
Start Dates

Leaderboards in Trophy can be set to start at a future date of your choice. This is often useful to allow some time for last minute changes or adjustments before leaderboards start ranking users. Leaderboards with a start date in the future are scheduled and automatically go live on the start date you choose.

​
End Dates

Leaderboards in Trophy can have end dates. If you set an end date on a leaderboard then after that date it will enter finished status and rankings will be finalized and winners chosen.
Due to differences in time zones, leaderboards can be finalized up to 12 hours after the end date in UTC to allow all users to reach the end date according to their local clock.

​
Participant Limits

Leaderboards in Trophy have a maximum number of participants of 1,000. However a leaderboard can be configured to have any arbitrary number of participants to support use cases like Top 100 or similar.
If a leaderboard already has a number of participants that matches its configured maximum, new users will have to surpass the score of the lowest rank to join the leaderboard.
We chose to limit leaderboard size to help guide customers on best practice.Traditionally, leaderboards with lots of participants fail to engage users beyond the top 1%, and have a negative impact on users in the bottom half, particularly new users. To avoid this, keep your leaderboards small by breaking them down into smaller leaderboards using breakdown attributes(#ranking-breakdowns).For more background on the negative effects on global leaderboards, read this blog post.

​
Creating Leaderboards

To create a leaderboard, head to the leaderboards page in the Trophy dashboard and hit the New Leaderboard button.
1

Enter a name

Choose a name for the leaderboard.
2

Enter a unique key

Enter a unique reference key for the leaderboard. This is what you’ll use to reference the leaderboard in your application code.
3

Choose a ranking method

Choose one of the methods that the leaderboard will rank users by:
  • Metric: Ranks users by total value of a chosen metric
  • Points: Ranks users by total points in a chosen points system
  • Streak: Ranks users by current streak length
4

Set max participants

Choose the maximum number of participants the leaderboard should support. The current upper limit supported by Trophy is 1,000. Read this section to learn more about how we chose this limit.
5

Hit save

Hit save and head to the configure page to set up start & end dates, repeating leaderboard schedules and more.

​
Managing Leaderboards

Leaderboards in Trophy have a number of statuses to help you control when users and how users can join them.

​
Leaderboard Statuses

Leaderboards can have one of the following statuses:
  • Inactive
  • Scheduled
  • Active
  • Finished
  • Archived
All new leaderboards are created as Inactive. While inactive, any properties or settings of the leaderboard can be changed, they won’t be visible to users and users can’t join them. Once you’re ready for users to start participating, you can make it Active. This means Trophy will start tracking users’ activity and entering them into leaderboards. Leaderboards that have been configured with a start date in the future can’t be made active, they can only be Scheduled. Once the start date is past, Trophy will automatically make them Active and start accepting participants. If a leaderboard has an end date, then once it has past Trophy will automatically move it to Finished status and stop monitoring user activity. Once a leaderboard has finished it won’t be visible to users but you can still query APIs to get rankings for historical runs. If you decide you no longer need a leaderboard, you can move it to Archived status.
Once a leaderboard is archived, it can only be restored by contacting support.

​
Displaying Leaderboards

Check out our full guide on adding leaderboards to your app for more details.

​
Leaderboard Analytics

Trophy has built-in analytics to help you understand how users are engaging with your leaderboards.
### Total Unique Participants This chart shows how many unique users have participated in any run of a leaderboard over time. This is useful to understand how many of your users actually take part in leaderboards and how participant limits are affecting this.

​
Active Users

This chart show the number of users who have changed rank at least once in a given leaderboard. This is useful to get a sense of how competitive the average user is in a particular leaderboard.

​
Rank Changes

This chart shows the total number of rank changes in a particular leaderboard over time. This is useful to understand how competitive users are across the board.

​
Score Distribution

This chart is a histogram of users’ scores in a particular leaderboard. This is useful to get a sense of how bunched up or spread out users are, and what sections of the rankings are the most competitive.

​
Frequently Asked Questions

We limit leaderboards to 1,000 participants.Read more about this in the dedicated section of this page.
Trophy supports running repeating leaderboards on any arbitrary number of days. So a weekly leaderboard would just be a leaderboard that repeats every 7 days. Read this section for more tips of creating weekly leaderboards.

​
Get Support

Want to get in touch with the Trophy team? Reach out to us via email. We’re here to help!