diff --git a/assets/platform/leaderboards/analytics.png b/assets/platform/leaderboards/analytics.png new file mode 100644 index 0000000..3e19e85 Binary files /dev/null and b/assets/platform/leaderboards/analytics.png differ diff --git a/assets/platform/leaderboards/creating_leaderboards.mp4 b/assets/platform/leaderboards/creating_leaderboards.mp4 new file mode 100644 index 0000000..4b15a0f Binary files /dev/null and b/assets/platform/leaderboards/creating_leaderboards.mp4 differ diff --git a/assets/platform/leaderboards/hero.png b/assets/platform/leaderboards/hero.png new file mode 100644 index 0000000..ff5182a Binary files /dev/null and b/assets/platform/leaderboards/hero.png differ diff --git a/assets/platform/leaderboards/max_participants.png b/assets/platform/leaderboards/max_participants.png new file mode 100644 index 0000000..b16d877 Binary files /dev/null and b/assets/platform/leaderboards/max_participants.png differ diff --git a/assets/platform/leaderboards/ranking_methods.png b/assets/platform/leaderboards/ranking_methods.png new file mode 100644 index 0000000..6c01394 Binary files /dev/null and b/assets/platform/leaderboards/ranking_methods.png differ diff --git a/assets/platform/leaderboards/start_end_dates.png b/assets/platform/leaderboards/start_end_dates.png new file mode 100644 index 0000000..55a6e36 Binary files /dev/null and b/assets/platform/leaderboards/start_end_dates.png differ diff --git a/docs.json b/docs.json index 01f99ba..b3dd845 100644 --- a/docs.json +++ b/docs.json @@ -56,6 +56,7 @@ "platform/achievements", "platform/streaks", "platform/points", + "platform/leaderboards", "platform/emails" ] }, diff --git a/getting-started/introduction.mdx b/getting-started/introduction.mdx index de7e3f7..5c0c6e5 100644 --- a/getting-started/introduction.mdx +++ b/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. Build sophisticated points systems to reward and retain users. + + + + } + href="/platform/leaderboards"> + Create friendly competitions to increase user engagement. + Deliver personalized lifecyle emails to users at the perfect moment. - 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. diff --git a/icons/leaderboard.svg b/icons/leaderboard.svg new file mode 100644 index 0000000..efd96c2 --- /dev/null +++ b/icons/leaderboard.svg @@ -0,0 +1,3 @@ + + + diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 6ab6825..0000000 --- a/package-lock.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "docs", - "lockfileVersion": 3, - "requires": true, - "packages": {} -} diff --git a/platform/events.mdx b/platform/events.mdx index f2c7ca7..643dbcf 100644 --- a/platform/events.mdx +++ b/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. + + 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. diff --git a/platform/leaderboards.mdx b/platform/leaderboards.mdx new file mode 100644 index 0000000..b27b5ad --- /dev/null +++ b/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 +--- + + + + + +## 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. + + + + + +### 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. + +Streak leaderboards can only be [perpetual](#perpetual-leaderboards). + +## 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 be finalized and winners chosen. + + + 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. + + +## 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 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. + + + + + + + + Choose a name for the leaderboard. + + + + Enter a unique reference key for the leaderboard. This is what you'll use to reference the leaderboard in your application code. + + + + 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 + + + + + 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. + + + + 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. + + + + +## 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. + + + Once a leaderboard is archived, it can only be restored by contacting support. + + +## 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](#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](#participant-limits) 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](#tips-for-weekly-leaderboards) for more tips of + creating weekly leaderboards. + + + +## 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! diff --git a/platform/overview.mdx b/platform/overview.mdx index a3ff434..48a969e 100644 --- a/platform/overview.mdx +++ b/platform/overview.mdx @@ -6,27 +6,59 @@ description: Learn the key concepts behind Trophy's gamification system. Trophy is built around a set of key concepts that all gamification experiences have in common, while still offering enough customization for you to build any kind of gamified experience you need. +## Platform Concepts + +Trophy's platform concepts are scalable building blocks that support all of Trophy's features and are the main things for developers to get comfortable with. + - Model user interactions and drive gamification features. + Model how users interact with your application. - Track usage against metrics. + Track user interactions against metrics. - Automatically track usage across your entire userbase. + Tell Trophy about the people using your application. + + +## Gamification Concepts + +Trophy's gamification concepts are flexible primitives built on the infrastructure concepts that support a wide range of common gamification use cases. + + - Reward users for continued progress or taking specific actions. + Encourage users to make continued progress or to take specific actions. Motivate users to build regular usage habits. - Build sophisticated points systems to reward and retain users. + Reward users with sophisticated points systems. + + + + + } + href="/platform/leaderboards" + > + Create friendly competitions to increase user engagement. - Deliver personalized lifecyle emails to users at the perfect moment. + Deliver personalized lifecyle emails to users to increase retention. diff --git a/platform/users.mdx b/platform/users.mdx index c071935..8cb6ffe 100644 --- a/platform/users.mdx +++ b/platform/users.mdx @@ -49,8 +49,8 @@ Additionally, you can tell Trophy about any of the following optional key attrib The user's time zone. Must be specified as an [IANA timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - Used to calculate streaks and send emails to users in accordance with their - local clock. + Used for streaks, leaderboard rankings and sending emails to users in + accordance with their local clock. @@ -274,6 +274,13 @@ To tell Trophy about an update to a user in your platform you can use the [Updat Any properties that you pass to Trophy will be updated to the new values you specify. + + As [user identifcation](#identifying-users) keeps user records up to date by + default, it's usually not necessary to explicitly update users in Trophy every + time one of their properties changes in your application. However the user + update API is there if you really need it. + + ## Retrieving User Information To fetch the details of a user that you've already identified with Trophy, use the [Get User API](/api-reference/endpoints/users/get-a-single-user).