Leaderboards docs

docs.json

@@ -56,6 +56,7 @@
               "platform/achievements",
               "platform/streaks",
               "platform/points",
+              "platform/leaderboards",
               "platform/emails"
             ]
           },

getting-started/introduction.mdx

@@ -5,7 +5,7 @@ description: Trophy documentation for gamification APIs, quickstart guides and t
 
 Trophy is a developer-friendly toolkit for building gamified product experiences in any mobile or web app.
 
-It makes building features like [Achievements](/platform/achievements), [Streaks](/platform/streaks) and [Points](/platform/points) simple with just a few lines of code, and can send gamified [Emails](/platform/emails) to increase your retention and engagement.
+It makes building features like [Achievements](/platform/achievements), [Streaks](/platform/streaks), [Points](/platform/points) and [Leaderboards](/platform/leaderboards) simple with just a few lines of code, and can send gamified [Emails](/platform/emails) to increase your retention and engagement.
 
 <CardGroup>
   <Card
@@ -38,7 +38,7 @@ It's been proven by the likes of Duolingo and others to predictably boost retent
 
 But building gamification at scale can be tricky. You have a global userbase, all in different timezones, all with different usage patterns that need to be measured and optimized in realtime. Plus, you want to run experiments to test different approaches and see how they impact retention, but this requires constant code changes, which holds up work on your core product.
 
-Trophy takes away the legwork involved in building features like achievements, streaks and points systems and provides reliable, scalable APIs for shipping gamification experiences faster than building in-house. Plus, it provides a web platform to easily configure, measure and experiment with the product experience without constant code changes.
+Trophy takes away the legwork involved in building features like achievements, streaks, points systems and leaderboards while providing reliable, scalable APIs for shipping gamification experiences faster than building in-house. Plus, it provides a web platform to easily configure, measure and experiment with the product experience without constant code changes.
 
 ## Get Support
 

getting-started/quickstart.mdx

@@ -89,12 +89,32 @@ Here you'll integrate your backend web application with Trophy and start buildin
       <Card title="Points" icon="sparkle" href="/platform/points">
         Build sophisticated points systems to reward and retain users.
       </Card>
+      <Card
+        title="Leaderboards"
+        icon={
+          <svg
+            width="20"
+            height="18"
+            viewBox="0 0 20 18"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            className="text-primary dark:text-primary-light"
+          >
+            <path
+              d="M2 16H6V8H2V16ZM8 16H12V2H8V16ZM14 16H18V10H14V16ZM0 16V8C0 7.45 0.195833 6.97917 0.5875 6.5875C0.979167 6.19583 1.45 6 2 6H6V2C6 1.45 6.19583 0.979167 6.5875 0.5875C6.97917 0.195833 7.45 0 8 0H12C12.55 0 13.0208 0.195833 13.4125 0.5875C13.8042 0.979167 14 1.45 14 2V8H18C18.55 8 19.0208 8.19583 19.4125 8.5875C19.8042 8.97917 20 9.45 20 10V16C20 16.55 19.8042 17.0208 19.4125 17.4125C19.0208 17.8042 18.55 18 18 18H2C1.45 18 0.979167 17.8042 0.5875 17.4125C0.195833 17.0208 0 16.55 0 16Z"
+              fill="currentColor"
+            />
+          </svg>
+        }
+        href="/platform/leaderboards">
+        Create friendly competitions to increase user engagement.
+      </Card>
       <Card title="Emails" icon="mail" href="/platform/emails">
         Deliver personalized lifecyle emails to users at the perfect moment.
       </Card>
     </CardGroup>
 
-    Or, explore our [purpose-built APIs](/api-reference/introduction) that support building any in-app gamification UI you want.
+    Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
 
   </Step>
 </Steps>

platform/events.mdx

@@ -7,6 +7,7 @@ icon: radio
 
 import MetricChangeRequestBlock from "/snippets/metric-change-request-block.mdx";
 import MetricChangeResponseBlock from "/snippets/metric-change-response-block.mdx";
+import IdempotentEventTracking from "/snippets/idempotent-event-tracking.mdx";
 
 ## What are Events?
 
@@ -198,7 +199,9 @@ Watch Charlie integrate metric tracking into a simple NextJS application using t
 
 Trophy supports enforcing uniqueness on events so that users cannot increase a metric by taking the same exact action over and over.
 
-For example, a language learning app could specify that users can only increase the `lessons completed` metric by 1 for each unique lesson completed, so if they complete the same lesson twice only the first counts.
+For example, a language learning app could specify that users can only increase the `lessons-completed` metric by 1 for each unique lesson completed, so if they complete the same lesson twice only the first counts.
+
+<IdempotentEventTracking />
 
 This helps keep your codebase free of logic that checks if users have completed actions before, and can instead trust Trophy to uphold the constraints you need.
 

platform/leaderboards.mdx

@@ -0,0 +1,272 @@
+---
+title: Leaderboards
+description: Learn how to use Leaderboards in a gamified product experience with Trophy.
+"og:description": Create daily, weekly or monthly competitions that rank users based on metrics, points or streaks and increase user engagement.
+icon: /icons/leaderboard.svg
+---
+
+<Frame>
+  <img
+    height="100"
+    width="100%"
+    noZoom
+    src="../assets/platform/leaderboards/hero.png"
+  />
+</Frame>
+
+## 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](#end-dates).
+
+### 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](/api-reference/endpoints/leaderboards/get-leaderboard) to fetch ranking data on historical runs.
+
+#### Handling Time Zones
+
+If you have tracked users' [time zones](/platform/users#param-tz) 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](mailto:support@trophy.so)! 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](#repeating-leaderboards) on a 7 day schedule and set the start date to be the next occuring 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 Method
+
+Leaderboards in Trophy can be configured to rank users in a few different ways.
+
+<Frame>
+  <img
+    height="200"
+    width="50%"
+    noZoom
+    src="../assets/platform/leaderboards/ranking_methods.png"
+  />
+</Frame>
+
+### Metric Rankings
+
+Metric leaderboards are linked to an existing Trophy [Metric](/platform/metrics) 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](/platform/points) 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.
+
+<Tip>Streak leaderboards can only be [perpetual](#perpetual-leaderboards).</Tip>
+
+## Start & End Dates
+
+Use start and end dates to control the window within which leaderboards are actively ranking users.
+
+<Frame>
+  <img
+    height="200"
+    width="50%"
+    noZoom
+    src="../assets/platform/leaderboards/start_end_dates.png"
+  />
+</Frame>
+
+### 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 be finalized and winners chosen.
+
+<Note>
+  Due to differences in [time zones](#handling-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.
+</Note>
+
+## 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.
+
+<Frame>
+  <img
+    height="200"
+    width="50%"
+    noZoom
+    src="../assets/platform/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.
+
+We plan to test increasing participant limits, however as computing leaderboard rankings can be resource intensive, there is always a tradeoff between correctness and scale.
+
+Read on for more information on how we think about this.
+
+### Tradeoffs
+
+As leaderboards increase in size, the time required to compute a user's new rank based on a state change increases as `O(n log n)`. If applications rely on each state change needing to know the users new rank in realtime, then this added latency can lead to a poor user experience.
+
+If however you don't care about realtime updates and are happy to accept eventual correctness, then leaderboards can increase in size without much impact.
+
+We chose to favor a more engaging, realtime experience where applications can trust Trophy to communicate changes in rank immediately and correctly, rather than supporting arbitrarily large numbers of participants but without the correctness that enables a richer user experience.
+
+### Our Vision
+
+Our long term vision for leaderboards is centered around facilitating smaller, more socially-relevant interactions more akin to 'leagues' than longer, platform-wide rankings that often fail to engage users outside the top 10%.
+
+We hope you agree this is the right approach but if you have any thoughts then [let us know!](mailto:support@trophy.so).
+
+## 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.
+
+<Frame>
+  <video
+    autoPlay
+    muted
+    loop
+    playsInline
+    className="w-full aspect-15/4"
+    src="../assets/platform/leaderboards/creating_leaderboards.mp4"
+  ></video>
+</Frame>
+
+<Steps>
+  <Step title="Enter a name">
+    Choose a name for the leaderboard.
+  </Step>
+
+  <Step title="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.
+  </Step>
+
+   <Step title="Choose a ranking method">
+    Choose one of the [methods](#ranking-method) 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
+
+  </Step>
+
+    <Step title="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](#participant-limits) to learn more about how we chose this limit.
+    </Step>
+
+    <Step title="Hit save">
+    Hit save and head to the configure page to set up [start & end dates](#start-and-end-dates), [repeating leaderboard schedules](#repeating-leaderboards) and more.
+    </Step>
+
+</Steps>
+
+## 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](#start-dates) 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](#end-dates), 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.
+
+<Warning>
+  Once a leaderboard is archived, it can only be restored by contacting support.
+</Warning>
+
+## Leaderboard Analytics
+
+Trophy has built-in analytics to help you understand how users are engaging with your leaderboards.
+
+<Frame>
+  <img
+    height="200"
+    width="50%"
+    noZoom
+    src="../assets/platform/leaderboards/analytics.png"
+  />
+</Frame>
+
+### 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](#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
+
+<AccordionGroup>
+  <Accordion title="How many participants can be in a leaderboard at once?">
+    We limit leaderboards to 1,000 participants.
+
+    Read more about this in the [dedicated section](#participant-limits) of this page.
+
+  </Accordion>
+
+{" "}
+
+<Accordion title="I don't see a weekly leaderboard option, how can I set one up?">
+  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](#tips-for-weekly-leaderboards) for more tips of
+  creating weekly leaderboards.
+</Accordion>
+</AccordionGroup>
+
+## Get Support
+
+Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!