Skip to content

Time windowed leaderboards #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cbrinicombe13 merged 3 commits into from
Jul 8, 2026
Merged

Time windowed leaderboards #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9d2681e
Changes to image widths
cbrinicombe13 Jul 8, 2026
749cb2e
Add docs for leaderboard time restrictions
cbrinicombe13 Jul 8, 2026
ad5ac59
Lock
cbrinicombe13 Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion account/billing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ You can view your usage for the current billing period on the [billing page](htt
<Frame>
<img
height="200"
width="50%"
width="100%"
noZoom
src="../assets/account/billing/plan-usage.png"
/>
Expand Down
Binary file added assets/features/leaderboards/time_restrictions.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion es/account/billing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Puedes ver tu uso para el período de facturación actual en la [página de fact
<Frame>
<img
height="200"
width="50%"
width="100%"
noZoom
src="../../assets/account/billing/plan-usage.png"
/>
Expand Down
200 changes: 114 additions & 86 deletions es/features/leaderboards.mdx
View file
Open in desktop

Large diffs are not rendered by default.

56 changes: 42 additions & 14 deletions features/leaderboards.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ The ranking method of a leaderboard determines on what dimension participants wi
<Frame>
<img
height="200"
width="50%"
width="75%"
noZoom
src="../assets/features/leaderboards/ranking_methods.png"
/>
Expand Down Expand Up @@ -141,7 +141,7 @@ Use start and end dates to control the window within which leaderboards are acti
<Frame>
<img
height="200"
width="50%"
width="75%"
noZoom
src="../assets/features/leaderboards/start_end_dates.png"
/>
Expand All @@ -163,32 +163,60 @@ Leaderboards in Trophy can have end dates. If you set an end date on a leaderboa
the end date according to their local clock.
</Note>

## Participant Limits {#participant-limits}
## Time Restrictions {#time-restrictions}

In addition to [start & end dates](#start-end-dates), leaderboards can be configured to have time restrictions.

When time restrictions are enabled, leaderboard rankings will only update during the configured time period.

Time restrictions are useful when building leaderboards for limited-time events or promotions that run for a specific period of time.

Time restrictions work on all leaderboards, including [repeating leaderboards](#repeating-leaderboards). Where a repeating leaderboard has a time restriction, the time restriction will be applied to each run of the leaderboard.

### Setting Time Restrictions {#setting-time-restrictions}

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.
To set time restrictions on a leaderboard, head to the leaderboard configuration page and turn on the switch labelled 'Restrict to time window'. This will give you two fields, a start and end time.

- Setting only a start time will mean leaderboard rankings only start to update after the start time on each day that the leaderboard is active.
- Similarly, setting only an end time will mean leaderboard rankings will stop updating after the end time on each day that the leaderboard is active.
- Setting both a start and end time will mean leaderboard rankings will only update during the configured time period.

<Frame>
<img
height="200"
width="50%"
width="100%"
noZoom
src="../assets/features/leaderboards/max_participants.png"
src="../assets/features/leaderboards/time_restrictions.png"
/>
</Frame>

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.
### Time Zone Considerations {#time-zone-considerations}

<Tip>
We chose to limit leaderboard size to help guide customers on best practice.
Time restrictions on leaderboards are applied in **local time** for each participant based on their configured [time zone](/features/users#param-tz).

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).
This means that each user can participate in the leaderboard at any time during the configured time restriction according to their local clock.

For more background on the negative effects on global leaderboards, read this [blog post](https://www.trophy.so/blog/leaderboard-only-motivating-top-one-percent).
## Participant Limits {#participant-limits}

</Tip>
Leaderboards in Trophy have a default 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.

<Frame>
<img
height="200"
width="100%"
noZoom
src="../assets/features/leaderboards/max_participants.png"
/>
</Frame>

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.

The only exception to this is when using [breakdown attributes](#ranking-breakdowns) to group participants into smaller cohorts. When using breakdown attributes the participant limit applies to each group, not overall.

<Tip>
If you require a larger participant limit, considering using [breakdown attributes](#ranking-breakdowns) to group participants into smaller cohorts. Or please contact us at [support@trophy.so](mailto:support@trophy.so) and we'll be happy to increase your defaults.
</Tip>

## Creating Leaderboards {#creating-leaderboards}

To create a leaderboard, head to the [leaderboards page](https://app.trophy.so/leaderboards) in the Trophy dashboard and hit the _New Leaderboard_ button.
Expand Down Expand Up @@ -269,7 +297,7 @@ Trophy has built-in analytics to help you understand how users are engaging with
<Frame>
<img
height="200"
width="50%"
width="75%"
noZoom
src="../assets/features/leaderboards/analytics.png"
/>
Expand Down Expand Up @@ -321,7 +349,7 @@ This chart is a histogram of users' scores in a particular leaderboard. This is
<Frame>
<img
height="200"
width="50%"
width="75%"
noZoom
src="../assets/features/leaderboards/score_distribution.png"
/>
Expand Down
119 changes: 64 additions & 55 deletions i18n.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ checksums:
content/34: 75f650be2ee26c19e702ee477bdc50de
content/35: 735a49f8018ffb1e2b53f77dc8a1fc22
content/36: b17980588574ebeea2ebce919f1787bc
content/37: 7c87bc40f5b8b37dda105d9efa1bd792
content/37: 225b3ea4d5a3a6922e350efd44d209c5
content/38: 79524f874744893afda00224a0203ea6
content/39: 96fdea992e14b309e21d70cbd5052f03
content/40: 10e8e9a59847ddd720c6d06b12c7b120
Expand Down Expand Up @@ -3389,7 +3389,7 @@ checksums:
content/21: e036d4ad9db1420e0a814ac8f5ed5e16
content/22: 8e4e667bbdd789fbe3210c23cbe1ebb4
content/23: 05d9d86b6a58731d254b23e09927766d
content/24: 6e81945c9b0985eca10db22fd8243d84
content/24: c7780417c4eb6fd5fa148fd8b77a8d95
content/25: e4f34910c18c88b2b107407ab1eda508
content/26: 64e9dabe3ebe042e2cb011b8dc9a9e15
content/27: 7c8a322b60417298299aa6a860fd7647
Expand All @@ -3413,65 +3413,74 @@ checksums:
content/45: abdc26659c4e48ac2a87a447c8069e21
content/46: 2da3bce39f011d227e7439bf39000c4b
content/47: 376db24492fd179249a97399cac62c7b
content/48: 981b0c659c120de7e54569bad48cc69e
content/48: 1f65a0e76a538cfda34ef69ff7316d11
content/49: be8ee42c61c2f8412a2223346fd1e5d7
content/50: 19ddbf4a6a27d1217a35ff1ab7082883
content/51: 6978c15affabcb936aeac6d02d2a9201
content/52: f53d2373b481a20fe76d332f4a102b84
content/53: 26f14651033af5a7e0da93c5dd653916
content/54: 84be083ce8f618a49aa37c1b5ebae0ad
content/55: 29eba1f6a44ec24ee2b0d97faff09564
content/56: 7fc3a5a4f12e019d5546b6c8688751ce
content/57: b7bfa8d2f17614327d05838374b72786
content/58: 610db0f043625ec6ace32150e8b96a66
content/59: 094e89e6ac397f5e15ea0fc1c209558d
content/60: 20e3ac38d3cc61e817f1dffacaa1c21e
content/61: defd8dab42b430e9687cc7ca90e0052e
content/62: 4dec52ce04aa8849a8a60508baae30ae
content/63: 258c9459be6a0fc3f535b41a89922f50
content/64: 830481b98e88ae69a3971df3aff5d250
content/65: 538df8a5de4562fa88ae14bd586adc97
content/66: 13d00a5c8b9f29080a87b703527bda75
content/67: b0655e68a1c5d9579fbcfdd75db04fce
content/68: 71d221bcbeb83b663ee8c0a0e4975b04
content/69: a40d8cc248a02d4ce34ae16119b14bf8
content/70: 4e5ddca85ed818337a2757ae6bc2dc64
content/71: a27e8a0a72073744f925f2820a1b7684
content/72: 73aea3ef20f5f9d1626fcc73fdea597d
content/73: a01a451f7aba1a80f0af7148df811dfc
content/74: 84a204a7da04ff738ebcc5f4d3a5ea35
content/75: 3347863434fc4a0bd8f075b971428c95
content/76: bb2ac20c712241859473f415c26a0a11
content/77: e180f5d5909fef8296047e0782fe8a85
content/78: 9c2bbabcea6c0a514182170b67f38183
content/79: 214aa9e0d35236656ba1738c8be4c3f0
content/80: 919b58f12a4f16d63b5a35d18fdf04bb
content/81: 2ca28a1219570c10ddeaf4cb1157bb6d
content/82: a6390089f6e92430098d3d97c610c17a
content/83: 300bcdb15fbcadfde3db772fafe63524
content/84: 3d93f05e4ce92565d044836c948352a9
content/85: 0d08ff106c532b64677561ea2c3bad1f
content/86: 116df75dc256a5019b4809510f35677c
content/87: 29354e8dfa046bfdc4fb70d7a8dc6e6d
content/88: 0ab559de8fc24b6e6cca6175444cfe9a
content/89: fab414b91a7a42cd5e37a0c5ade9945a
content/90: b87703add8d1e584a1307b28c871a0db
content/91: 2d9538daa0f3bcd2d760598097ee5d80
content/92: 9c3265eff155d4a823fd955cde7dba35
content/93: 689a23c317009f8944c124a0058137bc
content/94: ed10345c824c6fc4c69c882e9983b12b
content/95: fb9ce2e2edb7815efec73b696b5d5e95
content/96: afd2cbb809e9881ac70735964981a355
content/97: 44d8170f535788a47c7874e25dedb768
content/98: fa9f6f1b8a7829a8e68a1d0340a84533
content/99: 59c04c26d75493c450e9dd2355302733
content/100: 79524f874744893afda00224a0203ea6
content/101: 0fa45599d835da6f2e916859554673eb
content/102: 450ad7f99b79b12599856f813b9ef758
content/103: 4f9f49c4756aa59d40fcc76ca15669a9
content/104: f151f31b2581a7bd7f7d8635bff09dc8
content/105: 10e8e9a59847ddd720c6d06b12c7b120
content/106: 9799b973234bf2d10d5c971b267f55a5
content/55: 0c38bac95149de65c170e1dc15518530
content/56: 09b8810dc95ee7576ab78014537171b0
content/57: caea7e41aac97a6ddc795b729dea0931
content/58: 273ebc1d83cace35c22fa22d2197272c
content/59: a613f2df863b43e86ca0da44e6f15453
content/60: b33e18f0f1d560693bb4dbd7e1721d4f
content/61: 7f6326115eac856bb1a7ff6880f71906
content/62: d8f1e59bb6a7b4a47013dd4ac7685903
content/63: 6b8ea2b42e1d06e799a5a8dd20f18e4c
content/64: f2795e78ad428a0fc0d12ad8186b899a
content/65: 68fd00d1807b1c3633aa5546dc4144d5
content/66: f6e705bf5e8338559f9cdecad266d761
content/67: 29eba1f6a44ec24ee2b0d97faff09564
content/68: 99c2177f3abb1ba8d08e6d45f6f7fb47
content/69: b51af007ac57c287f3cc3e85e77d6aec
content/70: 610db0f043625ec6ace32150e8b96a66
content/71: 258c9459be6a0fc3f535b41a89922f50
content/72: afef5bbb2a19c4fd4958de5066bc51c1
content/73: 830481b98e88ae69a3971df3aff5d250
content/74: 538df8a5de4562fa88ae14bd586adc97
content/75: 13d00a5c8b9f29080a87b703527bda75
content/76: b0655e68a1c5d9579fbcfdd75db04fce
content/77: 71d221bcbeb83b663ee8c0a0e4975b04
content/78: a40d8cc248a02d4ce34ae16119b14bf8
content/79: 4e5ddca85ed818337a2757ae6bc2dc64
content/80: a27e8a0a72073744f925f2820a1b7684
content/81: 73aea3ef20f5f9d1626fcc73fdea597d
content/82: a01a451f7aba1a80f0af7148df811dfc
content/83: 84a204a7da04ff738ebcc5f4d3a5ea35
content/84: 3347863434fc4a0bd8f075b971428c95
content/85: bb2ac20c712241859473f415c26a0a11
content/86: e180f5d5909fef8296047e0782fe8a85
content/87: 9c2bbabcea6c0a514182170b67f38183
content/88: 214aa9e0d35236656ba1738c8be4c3f0
content/89: 919b58f12a4f16d63b5a35d18fdf04bb
content/90: 2ca28a1219570c10ddeaf4cb1157bb6d
content/91: a6390089f6e92430098d3d97c610c17a
content/92: 300bcdb15fbcadfde3db772fafe63524
content/93: 3d93f05e4ce92565d044836c948352a9
content/94: 0d08ff106c532b64677561ea2c3bad1f
content/95: 116df75dc256a5019b4809510f35677c
content/96: 162d669fb5a317e3a9deb84a1745c08c
content/97: 0ab559de8fc24b6e6cca6175444cfe9a
content/98: fab414b91a7a42cd5e37a0c5ade9945a
content/99: b87703add8d1e584a1307b28c871a0db
content/100: 2d9538daa0f3bcd2d760598097ee5d80
content/101: 9c3265eff155d4a823fd955cde7dba35
content/102: 689a23c317009f8944c124a0058137bc
content/103: ed10345c824c6fc4c69c882e9983b12b
content/104: fb9ce2e2edb7815efec73b696b5d5e95
content/105: afd2cbb809e9881ac70735964981a355
content/106: 44d8170f535788a47c7874e25dedb768
content/107: fa9f6f1b8a7829a8e68a1d0340a84533
content/108: b38dbc626d4fb02a18b368e626ca7cb0
content/109: 79524f874744893afda00224a0203ea6
content/110: 0fa45599d835da6f2e916859554673eb
content/111: 450ad7f99b79b12599856f813b9ef758
content/112: 4f9f49c4756aa59d40fcc76ca15669a9
content/113: f151f31b2581a7bd7f7d8635bff09dc8
content/114: 10e8e9a59847ddd720c6d06b12c7b120
content/115: 9799b973234bf2d10d5c971b267f55a5
6e661270fda5f62c58626640850c56b3:
meta/title: d17179a947e9687dd2338ca524b26b63
meta/description: a491b9e76be8c65506d2af60e6c6b972
Expand Down
Loading