Managing API keys
There are a few different operations you can perform on API keys from within your Trophy dashboard to manage your integration.Rotating keys
API keys can be rotated if you want to change them for any reason. At the point of rotation, the original API key will no longer function and any requests still using it will begin receiving `401` responses immediately.Revoking keys
API keys can also be revoked entirely at which point they become *Inactive*. At the point of revocation, the API key will no longer function and any requests still using it will begin receiving `401` responses immediately. Once revoked you can re-activate the API key at any time.Deleting API keys
If you're 100% sure you no longer need an API key, they can be deleted.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! # Client Libraries Source: https://docs.trophy.so/api-reference/client-libraries Use Trophy's type-safe SDKs to integrate with the API. Trophy currently offers the following SDKs for interacting with the Trophy API.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! # Get all achievements and their completion stats Source: https://docs.trophy.so/api-reference/endpoints/achievements/all-achievements openapi/application.yml get /achievements Get all achievements and their completion stats. **Rate Limits**What is Idempotency?
When describing APIs, [idempotence](https://en.wikipedia.org/wiki/Idempotence) is a property of a particular operation whereby subsequent invocations after the first have no additional effect on the state of the system. Trophy's [event tracking API](/api-reference/endpoints/metrics/send-a-metric-change-event) can be used to enforce idempotency preventing client retries from having unintended side effects such as overcounting user interactions, or awarding points to users multiple times for the same action. This is particularly important where rewards are tied to user actions to prevent users from 'gaming the system'.Sending Idempotent Requests
To ensure idempotency is respected when sending events to Trophy, include an `Idempotency-Key` header when using the [event tracking API](/api-reference/endpoints/metrics/send-a-metric-change-event). Additionally, all [client SDKs](/api-reference/client-libraries) support idempotency with built-in type safety. You can choose what to use as your idempotency key, but it should reflect the level of 'uniqueness' that you want Trophy to respect.How Idempotency Works
When Trophy detects an idempotency key has been sent with an event, it will first check if the user the event relates to has used it before. It will then proceed to take one of the following actions: * If the user has used the idempotency key before, Trophy will not process the event, returning a `202 Accepted` response. The response will reflect the current state of the system, but will not increase the users metric total, complete any achievements, award any points, extend the streak, etc. * If instead Trophy detects the user hasn't used the idempotency key before, it will process the event as usual, returning a `201 Created` response. Finally Trophy will store the idempotency key for lookup during any subsequent requests.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! # Introduction Source: https://docs.trophy.so/api-reference/introduction Learn about the Trophy API and get started building your integration. The Trophy Application API is a set of endpoints that provide simple interfaces for building gamification experiences and covers the full range of actions that an end user of your application can perform. It does not include global administrative functions or actions that should only be performed by your internal systems. If you are looking for admin functionality, please refer to the [Admin API](/admin-api/introduction). The Application API is accessible through [SDKs](/api-reference/client-libraries) available in most major programming languages or, for those who wish manage their own HTTP clients, is available at the following base URL. ```bash Base URL theme={null} https://api.trophy.so/v1 ```Get Started
Learn more about how to integrate with the Trophy Application API below.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! # Rate Limiting Source: https://docs.trophy.so/api-reference/rate-limiting Learn about the Trophy API and request rate limiting. Trophy operates a tiered rate limiting model for each API endpoint. All rate limits are scoped at the organisation level. Exceeding rate limits will result in your application receiving a `429 Too Many Requests` response.Rate Limit Tiers
| Tier | Rate Limit | | ------------------ | ---------- | |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! # Achievements Source: https://docs.trophy.so/features/achievements Learn how to use Achievements in a gamified product experience with Trophy.What Are Achievements?
Achievements are rewards that users can unlock as they use your platform. They can be used to reward users for making continued progress along core user journeys, or to motivate users to explore more nascent features. Achievements work best when designed to incentivize users to take actions that are likely to lead to increased retention.Achievement Types
Trophy offers four types of achievements, [Metric](#metric-achievements), [API](#api-achievements), [Streak](#streak-achievements) and [Composite achievements](#composite-achievements), detailed below.Metric Achievements
Metric achievements are tied to [Metrics](/features/metrics) and are best used when you want to incentivize users to take the same action over and over again. Let's take the example of a study platform that uses Trophy to encourage users to view more flashcards with metric achievements as follows: * 1,000 flashcards * 2,500 flashcards * 5,000 flashcards * 10,000 flashcards * 25,000 flashcards * 50,000 flashcards In this case you would create a metric called *Flashcards Flipped* and create achievements against the metric for each milestone. Since these achievements are directly tied to the *Flashcards Flipped* metric, Trophy will automatically track when users unlock these achievements as they [increment the metric](/features/events#tracking-metric-events). When achievements are unlocked, Trophy includes information about the unlocked achievements in the [Event API](/api-reference/endpoints/metrics/send-a-metric-change-event) response, and automatically triggers [Achievement Emails](/features/emails#achievement-emails) if configured. ```json Response [expandable] theme={null} { "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623", "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "total": 750, "achievements": [ { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "trigger": "metric", "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "metricName": "Flashcards Flipped", "metricValue": 500, "name": "500 Flashcards Flipped", "description": "Write 500 words in the app.", "achievedAt": "2020-01-01T00:00:00Z" } ], "currentStreak": { "length": 1, "frequency": "daily", "started": "2025-04-02", "periodStart": "2025-03-31", "periodEnd": "2025-04-05", "expires": "2025-04-12" }, "points": { "xp": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "key": "xp", "name": "XP", "description": null, "badgeUrl": null, "maxPoints": null, "total": 10, "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "bronze", "name": "Bronze", "description": "Starting level", "badgeUrl": null, "points": 0 }, "added": 10, "awards": [ { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "awarded": 10, "date": "2021-01-01T00:00:00Z", "total": 10, "trigger": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "type": "metric", "metricName": "Flashcards Flipped", "metricThreshold": 100, "points": 10 } } ] } }, "leaderboards": { "daily_champions": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535", "key": "daily_champions", "name": "Daily Champions", "description": null, "rankBy": "metric", "runUnit": null, "runInterval": 0, "maxParticipants": 100, "metricName": "Flashcards Flipped", "metricKey": "flashcards-flipped", "threshold": 10, "start": "2025-01-01", "end": null, "previousRank": 50, "rank": 12 } } } ```API Achievements
API achievements can only be completed once and are useful for rewarding users for taking specific actions. Common examples include: * A user completing their profile after signing up * A user linking their social account to a platform * A user sharing their product experience on social media API achievements serve as an easy way to reward users for completing any action that you think is important for retention. Just like metric achievements, API achievements can also trigger automated [Achievement Emails](/features/emails#achievement-emails) if configured.Streak Achievements
Streak achievements are directly tied to a user's [Streak](/features/streaks) and are automatically unlocked when users reach a particular streak length. You can create as many streak achievements as you like for increasing lengths of streak, for example 7 days, 30 days and 365 days to motivate users to use your app more and more. Just like metric and API achievements, you can add a custom name and assign a badge to streak achievements.Composite Achievements
Composite achievements unlock automatically when a user has completed all of the prerequisite achievements you select. They're ideal for creating tiered or mastery-level rewards that recognize users who have accomplished a specific set of milestones. For example, you could create a "Study Master" composite achievement that unlocks when a user has completed: * 1,000 flashcards * 7-day streak * Complete onboarding Composite achievements are useful for creating progression pathways and encouraging users to engage across different areas of your app. Just like other achievement types, they can trigger [Achievement Emails](/features/emails#achievement-emails) when unlocked.Creating Achievements
To create new achievements, head to the [achievements page](https://app.trophy.so/achievements) in the Trophy dashboard and hit the **New Achievement** button:Managing Achievements
Trophy has built in tools to help you test and control which achievements can be unlocked, by who and when, without affecting production.Achievement Statuses
Here's an overview of the different achievement statuses and what they mean. **Inactive** All achievements are created as inactive. Inactive achievements can't be completed and aren't returned in any achievement APIs. Users won't see them until you make them active. **Active** When you make an achievement active, it makes it 'live'. Users can complete it and it will be returned from all achievement APIs. **Locked** When you lock an achievement, users who haven't unlocked it yet won't be able to unlock it anymore, but users who have already unlocked it won't be affected. Locked achievements are only returned in APIs for users who have already achieved them.Achievement Workflow
Achievements can be moved through different statuses according to the following workflow: ```mermaid theme={null} flowchart LR A@{ shape: rounded, label: "Inactive" } B@{ shape: rounded, label: "Active" } C@{ shape: rounded, label: "Locked" } A-->B B<-->C style A fill:#FDFDEA,stroke:#F7F0D5 style B fill:#F2FAF7,stroke:#E2F6E6 style C fill:#eee,stroke:#ddd ```Completing Achievements
If you're using metric achievements, there's no need to explicitly *complete* achievements. Once you've set up [metric tracking](/features/events#tracking-metric-events) in your code, all achievements linked to the metric will be automatically tracked. Similarly, if you're using streak achievements, all achievements related to the user's streak will automatically be unlocked when a user reaches the respective streak length. Composite achievements are also completed automatically. They unlock as soon as a user has completed all of their prerequisite achievements. No additional API calls are needed. However if you're using any API achievements, you will have to mark them as completed for each user as appropriate. To do this, you can use the [Complete Achievement API](/api-reference/endpoints/achievements/mark-an-achievement-as-completed) using the `key` of the achievement you want to complete. This will return back a response that contains details of the achievement that was completed that can be used in any post-completion workflows, like showing an in-app notification. ```json Response theme={null} { "completionId": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "achievement": { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "trigger": "api", "name": "Finish onboarding", "description": "Complete the onboarding process.", "badgeUrl": "https://example.com/badge.png", "key": "finish-onboarding", "achievedAt": "2021-01-01T00:00:00Z" } } ```Backdating Achievements
By default, whenever you move an achievement to 'Active' [status](#managing-achievements), Trophy will check if any existing users meet the requirements of the achievement and complete it for them behind the scenes. This means when you release new achievements into production, or edit an existing live achievement, backdating will happen automatically.Using Badges
You can assign a badge to any achievement by uploading an image—Trophy serves it and returns the URL—or by providing your own image URL. Relevant API responses include that value in `badgeUrl` for use as the `src` on `Displaying Achievements
Trophy has a number of APIs that support displaying achievements within your applications. Here we'll look at the different ways to use them and the types of UI's you can build.All Achievements
To display a high-level overview of all achievements users can complete, use the [all achievements endpoint](/api-reference/endpoints/achievements/all-achievements). Use this data to build UI that gives users an idea of the progression pathways within your application. The all achievements endpoint returns a list of all achievements within your Trophy account. Each achievement returned also includes `completions` (the number of users who have completed the achievement) and `rarity` (the percentage of users who have completed the achievement) as follows: ```json Response [expandable] theme={null} [ { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "trigger": "api", "name": "Finish onboarding", "description": "Complete the onboarding process.", "badgeUrl": "https://example.com/badge.png", "key": "finish-onboarding", "completions": 8, "rarity": 80 }, { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123683", "trigger": "metric", "name": "500 Flashcards Flipped", "description": "View 500 flashcards in the app.", "badgeUrl": "https://example.com/badge.png", "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123683", "metricName": "Flashcards Flipped", "metricValue": 500, "completions": 6, "rarity": 60 }, { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123684", "trigger": "streak", "name": "10 days of exercise", "description": "Exercise at least once a day for 10 days in a row.", "badgeUrl": "https://example.com/badge.png", "streakLength": 10, "completions": 2, "rarity": 20 }, { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123685", "trigger": "achievement", "name": "Study Master", "description": "Complete all introductory milestones.", "badgeUrl": "https://example.com/badge.png", "achievementIds": [ "5100fe51-6bce-6j44-b0hs-bddc4e123682", "5100fe51-6bce-6j44-b0hs-bddc4e123683", "5100fe51-6bce-6j44-b0hs-bddc4e123684" ], "completions": 1, "rarity": 5 } ] ```User Achievements
If instead you're building user-specific UI elements, then use the [user achievements endpoint](/api-reference/endpoints/users/get-a-users-completed-achievements) to return achievements a specific user has completed.Achievement Analytics
If you have achievements set up for any of your [Metrics](/features/metrics), then the metric analytics page displays a chart that shows you the current progress of all Users as follows:Frequently Asked Questions
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! # Emails Source: https://docs.trophy.so/features/emails Learn how to use emails in a gamified product experience with Trophy. Trophy can send automated emails to users based on key triggers without requiring any code. Here we'll look at what these triggers are, and how they can form part of your product's gamification experience.Types Of Emails
Trophy supports 4 types of emails, each of which is designed to suit a common scenario in building gamification experiences. All emails are optional, but all four can be used simultaneously and can be controlled from the [Emails](https://app.trophy.so/emails/configure) page in the Trophy dashboard. * **Achievement emails** are sent to users each time they unlock an [Achievement](/features/achievements). * **Recap emails** are sent to users on a pre-defined frequency to summarize progress. Recap Emails can be configured to be sent daily, weekly, monthly or yearly depending on your use case. * **Reactivation emails** are sent to users after they become inactive with the goal of bringing them back to your app. * **Streak emails** are automatically sent to users reminding them to extend their [Streak](/features/streaks).Sending Emails
To start sending emails with Trophy, you'll need to verify your domain and add and activate email templates for the types you want to send.Domain Verification
Trophy supports sending emails from your own domain out-of-the-box. There are two ways to set this up, Single Sender Verification and DNS Verification. All domain settings can be found in the [Domains](https://app.trophy.so/emails/domains) page in the Trophy dashboard.Sender Verification (Basic)
During onboarding you'll be prompted to set up Sender Verification. This is a super simple way to quickly verify a single email address that you want to use with Trophy without needing to change any code or DNS settings. You'll be prompted to enter the email address, from name and reply-to email that you'd like Trophy to use when sending emails:DNS Verification (Advanced)
Email Triggers
On the [email configuration](https://app.trophy.so/emails/configure) page, each email type has its own section. Add templates under the relevant type and activate one to start sending.Recap Emails
**Recap** emails send weekly or monthly progress reports to users. You can change the frequency of these emails on the [integration](https://app.trophy.so/integration) page using the **Aggregation Period** setting.Reactivation Emails
**Reactivation** emails send win-back messages to users after they become inactive. These emails are sent according to the following timeline: * After 3 days of inactivity * After 5 days of inactivity * After 7 days of inactivity * After 14 days of inactivity * After 30 days of inactivityStreak Emails
**Streak** emails remind users to extend their streak before it expires. These emails are sent according to the streak frequency you configured on the [streaks page](https://app.trophy.so/streaks): * If your app uses a **daily streak**, this email will send four hours before the end of the day (in each user's timezone). * For **weekly streaks**, it will send on Friday morning. * For **monthly streaks**, it will send on the 25th of the month.Achievement Emails
**Achievement** emails congratulate users when they complete an [achievement](/features/achievements) you've configured in Trophy. These emails send between 5-9PM on the day the achievement is completed, or the next day at 5PM if it is past 9PM when the user completes the achievement.Limiting Emails to Specific Types of Users
Each email template can be limited to users with specific [custom user attribute](/features/users#custom-user-attributes) values. For each attribute you'd like to restrict the email to, click the plus icon next to the **User Filters** header for the email template, then select the attribute and enter the desired value. Only users that have **all** specified attribute values will receive emails from this template.Time Zones
If you specify a timezone for each user through [User Identification](/features/users#param-tz), Trophy will use that local time zone to schedule emails according to the logic specified above. If you do not provide time zones for the users you identify, Trophy will default to Eastern Time.Designing Emails
Trophy has a fully-featured block-based email builder that allows you to design templates, controlling all email copy and subject lines. On the [emails](https://app.trophy.so/emails/configure) page, add templates under each [email type](#email-triggers) section you want to use.Default Templates
By default, Trophy provides a template for each [email type](#types-of-emails) as a good starting point. The default templates can't be changed, but you can duplicate and customize these as you wish.Creating A New Template
To create a new email template, follow the steps below.Block Types
Trophy's email builder supports a number of different block types that serve different purposes. All the basic components you'd expect to find in an email editor like paragraphs, headers, and images are called [Basic Blocks](#basic-blocks). There is also a set of more powerful components like charts and streaks that leverage Trophy's user activity data and gamification features. These are called [Smart Blocks](#smart-blocks).Basic Blocks
Here's the full list of un-opinionated basic blocks that Trophy supports: * **Paragraph** - Good for short or longer text snippets. * **H1, H2, H3** - Useful for headings of varying sizes. * **Button** - Creates a call to action for users to take in emails. * **Card** - Can nest other blocks, focusing attention. * **Divider** - Good for separating content into logical sections. * **Emoji** - Include any supported emoji, controlling size. * **Image** - Upload any image and Trophy will render it in emails. * **Spacer** - Good for giving blocks room to stand out. * **Columns** - Useful for creating up to 3-column layouts with any content. * **Logo** - Will render your organization's logo, set on the [Branding](https://app.trophy.so/branding) page.Conditional Blocks
Trophy also has a powerful conditional rendering system powered by the *Conditional* block type. By nesting any other block inside a conditional block and setting up the conditions logic, you can create almost any email design that will show different blocks in emails based on the evaluation of conditions at send time. If you're familiar with the `if/else` logical operators then this will feel very familiar to you. Otherwise here's a quick diagram to explain how it works. ```mermaid theme={null} flowchart LR B@{ shape: diamond, label: "First condition true?" } C@{ shape: rounded, label: "Show first block" } D@{ shape: diamond, label: "Second condition true?" } E@{ shape: rounded, label: "Show second block" } F@{ shape: rounded, label: "Show default block" } B-- Yes --->C B-- No --->D D-- Yes --->E D-- No --->F ``` One common use case for the conditional block is to conditionally show a user their streak (one of Trophy's built-in [Smart Blocks](#smart-blocks)) and some streak-related motivational text only if they have an active streak. If the recipient isn't on a streak at the time the email is sent, then a simple message is displayed instead.Smart Blocks
Smart blocks are powerful components designed to support common gamification use cases and integrate with all of Trophy's features including metrics, achievements and streaks. You can find all smart blocks in the *Recommended Blocks* section, and they are always recognizable by theEmail Variables
Trophy provides an expansive set of email variables that can be used to insert highly relevant and personalized copy into the body of emails and subject lines. Variables bring context from your Trophy account, the recipient's progress data, and email specific settings to your email templates. Email variables can be inserted by typing `@` in any block that supports rich text, like headers, paragraphs, and buttons, and searching for your chosen variable. This will open up the variable editor window where you can configure variables as in the demo below.Advanced Usage
There are a couple of additional options to consider when using emails variables. **Prefix & Suffix** You can provide a prefix and suffix for text variables like the recipients name, or the name of a particular metric.Text Variations
Variations can be used to add randomness to text within emails sent by Trophy. This prevents emails from getting boring and helps improve open and click rates. Any block that supports text entry including H1, H2, H3 and paragraph support variations.Using The Editor
The email template editor is a blank canvas for designing emails that look great in the inbox. Using pre-configured [Blocks](#block-types) makes it really easy to create email templates that suit common gamification use cases. Here we'll walk through how to best use the editor to create awesome looking emails.Adding Blocks
To add a new block an email template hit theArranging Blocks
Blocks can be dragged up and down using the block menu.Text Formatting
The email editor offers rich text formatting including bold, italics, [hyperlinks](https://www.youtube.com/watch?v=dQw4w9WgXcQ) and `code` formatting.Font Style
On the [email configure page](https://app.trophy.so/emails/configure), you'll find a setting to change the font style used in all emails.Handling Unsubscribes
All emails that Trophy sends include an unsubscribe link and message. This is important for maintaining compliance with regulations and it's not possible to hide it.Email Analytics
Trophy has built-in analytics for all Emails that it sends. This includes: * Recipients (The total number of people that received the email) * Open rate (The percentage of recipients that opened the email) * Click rate (The percentage of recipients that clicked on at least one link in the email) * Retention rate (The percentage of users that opened the email that came back and used your platform after at least 2 days)Frequently Asked Questions
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! # Events Source: https://docs.trophy.so/features/events Events are data objects that represent individual user interactions against metrics in Trophy.What are Events?
Events represent individual user interactions against [Metrics](/features/metrics) in Trophy. One event corresponds to a single interaction made by a single user. When you [integrate metrics](#tracking-metric-events) into your platform, you're setting up your platform to continuously stream events to your Trophy metrics for each user interaction. These interactions then drive all the gamification features you set up around these metrics.Key Attributes
Event Value
The `value` of an event is the numerical amount that will be added to the user's total metric count as a result of the user interaction it relates to.Custom Event Attributes
Creating Attributes
To create a new custom event attribute, head to the metrics page in the Trophy dashboard and hit the *Add Event Attribute* button. Give the attribute a name and a unique key, you'll use the key when referencing the attribute in API calls.Setting Attributes
To set the value of a custom attribute on an event, pass its value in the `attributes` object in your metric tracking code.Using Attributes
Custom event attributes can be used to power more advanced triggers for achievements and points and can be used in email templates to customize copy and to control the data shown in charts.Advanced Feature Triggers
Custom event attributes can be used to set up achievements or points triggers that only track events with specific attribute values. Follow the links to the relevant pages below to learn more.Email Customization
If you use any Trophy [Emails](/features/emails), event attributes can be used to customize the data shown in certain email blocks. Firstly, when using metric-based variables in email copy you can use event attributes to further control what data the variable references. For example here's a case where we use an email variable to tell users what their total number of workouts they've done on different gym equipment is using a metric 'Workouts' and an attribute 'Equipment': Secondly, here's an example where we add a chart to an email that shows users how many workouts they've done on a bike over time: There's a huge number of possibilities here, so get creative!Tracking Metric Events
Each metric has a unique `key` which you can use to reference and track events against it in your code. You can find the `key` in the metric settings page. To start tracking user interactions as events against your Trophy metrics, use the [Metrics API](/api-reference/endpoints/metrics/send-a-metric-change-event) or one of our type-safe [Client SDKs](/api-reference/client-libraries) supported in most major programming languages. Here's an example where a fictional study platform is using a metric to track the number of flashcards flipped by each student. Each time an student interacts, the platform sends an event to Trophy telling it how many flashcards they viewed:Idempotent Events
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.Parallel Events
Trophy does not support parallel events to same metric for the same user. Instead, use the `value` parameter to increment the metric by the total amount of all individual events that you need to track.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! # Leaderboards Source: https://docs.trophy.so/features/leaderboards Learn how to use Leaderboards in a gamified product experience with Trophy.What are Leaderboards?
Leaderboards are social competitions between users of your application. Use leaderboards to increase engagement and foster social interaction.Types of Leaderboards
In this section we outline the different types of leaderboards supported in Trophy and when to use each one.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). Use perpetual leaderboards when you want to create all-time rankings of user activity.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. 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](/features/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 users in all time zones to make their final push.Tips for Weekly Leaderboards
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 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.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](/features/metrics) and rank users based on their total metric value. Use metric leaderboards if you only want to rank users based on a single interaction.Points Rankings
Points leaderboards are linked to an existing Trophy [Points System](/features/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.Ranking Breakdowns
If you have a large user base, it's best practice to split up leaderboard participants into smaller, more socially-connected groups. This often leads to higher engagement than when using global leaderboards. Leaderboards in Trophy can be configured to group users into smaller groups according to one or more [custom user attributes](/features/users#custom-user-attributes).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.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.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.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` 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.Displaying Leaderboards
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
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! # Metrics Source: https://docs.trophy.so/features/metrics Learn how to model user interactions using Trophy Metrics. Model any user interaction and trigger automated gamification flows with just a few lines of code.What are Metrics?
All gamification features are centered around user interactions. At Trophy, we use the term **Metrics** to refer to the data objects that model those interactions within your web or mobile app. Metrics are un-opinionated, meaning they can be used to model absolutely any user interaction you can think of. Examples could include: * Followers, likes or posts * Tasks completed * Miles ran * Lessons completed * Words written * ... Metrics are the building blocks of the infrastructure that powers Trophy's gamification features. Each user interaction that relates to a metric is stored as an [Event](/features/events). Events are stored and processed in chronological order. At any particular point in time, the combined state of a user's event history reflects their overall progress on your platform.Key Attributes
Here we describe the key attributes that allow you to create metrics to best fit your use case.Units
You can easily assign units to metrics in the dashboard for either: * Arbitrary numbers (tasks, posts, messages etc.) * Currencies (\$, £, €)Creating Metrics
To create a Metric, head over to the [Metrics](https://app.trophy.so/metrics) page within Trophy and hit the **New Metric** button:Metric Analytics
Trophy has a built-in analytics dashboard for each metric you create. It shows you: * The total value of all tracked events against the metric * The number of users actively making progress against the metric * The metric's [Achievement Completion Chart](#achievement-completion-chart)Achievement Completion Chart
The achievement completion chart shows the current state of the userbase in terms of the number of users who have completed each achievement that you've configured against this metric. [Learn more about achievements](/features/achievements).Frequently Asked Questions
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! # Overview Source: https://docs.trophy.so/features/overview 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.Gamification Concepts
Trophy's gamification concepts are flexible primitives built on the infrastructure concepts that support a wide range of common gamification use cases.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! # Points Source: https://docs.trophy.so/features/points Learn how to build points-based systems using TrophyWhat is a Points System?
Points systems are used to create counters that track users' interactions with [Metrics](/features/metrics), [Achievements](/features/achievements) and [Streaks](/features/streaks). You can then build features like 'XP' and 'Energy' around these counters within your product.Use Cases
Rewards
Points systems can be used to create features like 'XP' or 'Gems' that reward users for a number of interactions at different rates. In this way points can be used to weight the value of certain interactions differently to others to reward users for taking the actions you consider most closely correlated to retention.Metering
Points systems can also be used to create features like 'Energy' that meter usage of your product in a way that gives you control over promoting and restricting user activity. This allows you to control the rate at which users can use your product with a flexible mechanic that sits outside your codebase.Creating Points Systems
Trophy let's you set up multiple points systems for different use cases within your application. To create a points system, head to the [points page](https://app.trophy.so/points) and follow the steps below.Points Triggers
In Trophy, points are awarded to or deducted from users through triggers. These define the different mechanics that make up your points system. You can add as many triggers as you like to each points system you set up, allowing you to create different logic for how points are awarded or deducted for different points systems.Types of Triggers
There are multiple types of triggers in Trophy that can be used to award or deduct points in different ways.Metric Triggers
Points can be awarded or deducted continually as users increment [Metrics](/features/metrics). You can choose to award or deduct any arbitrary number of points at any arbitrary metric threshold, for example "award 10 points for every 3 tasks completed".Streak Triggers
Points can be awarded or deducted for reaching any arbitrary length of a [Streak](/features/streaks), for example "award 50 points for every 7 days streak".Achievement Triggers
Points can be awarded or deducted when users unlock specific [Achievements](/features/achievements), for example "award 100 points when users completed the `profile-completed` achievement".Time-based Triggers
Points can be awarded or deducted at repeating time intervals, every hour or every day. For example "award 10 points every 3 hours".User Identification Triggers
Points can be awarded when users are first identified in Trophy, useful for granting an initial amount of points when they sign up to your product.Creating Triggers
To create a new points trigger, head to the points system that you want to create a trigger for and follow the steps below.Balancing Points
Running an effective points system requires finding the optimal pace at which users earn points. Too fast, and users will get points fatigue, rendering them useless. Too slow, and users may get bored and churn. Trophy's preview tool can model different scenarios to help you determine how frequently users should earn points in each of your points systems.Points Boosts
Points boosts are multipliers that you can use to increase the number of points awarded to users during a specific time period. This section explains how boosts work and how they can be used to increase your application's retention and engagement.Boost Targeting
There are a few different ways you can use boosts in Trophy. * **Global boosts** multiply points earned by all users during the boost window, or can be scoped to a specific user cohort by using [custom user attributes](/features/users#custom-user-attributes). * **User-specific boosts** only multiply points earned by a single user within the boost window. Typically, global boosts are used to increase platform-wide engagement during key calendar events like Black Friday/Cyber Monday in e-commerce, New Year in fitness and exam season in ed-tech platforms. Conversely, user-specific boosts are commonly used to provide additional incentives for users to take actions that are correlated with higher retention.Creating Boosts
Boost Multipliers
Every boost has a single multiplier value that increases the total points earned by users affected by that boost. Boost multipliers must be positive numbers, but can be decimals to support scenarios where percentage boosts like '50% more points' may be required.Boost Stacking
Points boosts in Trophy stack through [multiplication](#boost-multipliers). This is to support allowing users to benefit from multiple boosts simultaneously. To demonstrate stacking consider a 2X, 1.5X and a 3X boost all active within the same time period. The resulting boost multiplier for a user that qualifies for all three boosts would be as follows: ```txt Boost Stacking Example theme={null} Overall Multiplier (3 boosts) = 2X * 1.5X * 3X = 9X ```Boost Rounding
Trophy supports [floating point metric event values](/features/events#event-value), but takes care of rounding points to integers automatically. However, when using decimal [boost multipliers](#boost-multipliers), there may be some scenarios where this default rounding is not enough to always produce integer points values. Therefore Trophy offers three rounding modes to provide additional control on rounding behavior specifically when boosts are involved in points calculations. * **Round Down**: By default, Trophy will round points down to the nearest integer when boost multiplication results in a decimal. * **Round Up**: Trophy rounds decimal points up to the nearest integer after boost multiplication. * **Round Nearest**: Trophy will round points to the nearest integer, up or down, based on the final value after boost multiplication. For example `1.2` is rounded to `1` and `1.7` is rounded to `2`.Points Levels
Points levels are discrete milestones you define on a points system in Trophy. Each level has a threshold. When a user's total points in the system exceeds this threshold, Trophy assigns them that level automatically. You do not need to maintain level logic in your own codebase. Use levels for rank tiers, progression UI, reward tiers, or analytics. Trophy keeps each user's current level in sync whenever they earn or lose points in that system.Configuring levels
To set up levels for a points system, open it from the [points page](https://app.trophy.so/points) in the Trophy dashboard and use the levels tab to add or manage levels.Displaying Levels
Most teams combine three approaches: a static picture of every level (for progression screens), the user’s current level (for headers and profile), and immediate feedback when an action pushes them into a new level.Displaying All Levels
Call the [get levels API](/api-reference/endpoints/points/get-points-levels) once per points system key (for example on app load or from your server when rendering a progression page). The response is an array of levels with `key`, `name`, `description`, optional `badgeUrl`, and the `points` threshold for each level. By binding your UI to the Trophy API response, you'll ensure that it automatically updates when you make changes to levels in the Trophy dashboard. ```json Response [expandable] theme={null} [ { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "bronze", "name": "Bronze", "description": "Starting level", "badgeUrl": "https://example.com/bronze.png", "points": 0 }, { "id": "2240fe51-6bce-4b44-b0ad-bddc4e123534", "key": "silver", "name": "Silver", "description": "Mid-tier level", "badgeUrl": null, "points": 50 }, { "id": "3340fe51-6bce-4b44-b0ad-bddc4e123534", "key": "gold", "name": "Gold", "description": "Top level", "badgeUrl": "https://example.com/gold.png", "points": 200 } ] ```Displaying User Level
The [user points API](/api-reference/endpoints/users/get-a-users-points) returns the user’s `total`, their current `level` object, and recent `awards`. The `level` field contains the user's current level, or null if no levels exist or they have not reached the points threshold for any level yet. Pair `total` with the ordered level list from the previous step to draw a progress bar between the current threshold and the next. ```json Response [expandable] theme={null} { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "key": "xp", "name": "XP", "description": null, "badgeUrl": null, "maxPoints": null, "total": 100, "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "silver", "name": "Silver", "description": "Mid-tier level", "badgeUrl": null, "points": 50 }, "awards": [ { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "awarded": 10, "date": "2021-01-01T00:00:00Z", "total": 100, "trigger": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "type": "metric", "points": 10, "metricName": "Flashcards Flipped", "metricThreshold": 1000 } } ] } ```Level Change Notifications
When you send a [metric change event](/api-reference/endpoints/metrics/send-a-metric-change-event), the response will include a `points` map keyed by your points system keys for each system that changed as a result of the event. The data contains a `level` key only when the user’s level changed because of this event. If their level stayed the same, that key is omitted, so you can safely treat a present `level` as a level change signal without extra bookkeeping. ```json Response [expandable] theme={null} { ..., "points": { "xp": { ..., "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "bronze", "name": "Bronze", "description": "Starting level", "badgeUrl": null, "points": 0 }, ... } } } ``` A typical pattern is to check the object for your system after a successful event, then trigger a toast, modal, or sound: ```ts theme={null} const pts = response.points?.xp; // use your points system key if (pts?.level) { // Level changed on this request — e.g. toast, modal, confetti if level up notifyLevelChange(pts.level.name, pts.total); } ``` The same `level` behavior applies when points change from an [achievement completion](/api-reference/endpoints/achievements/mark-an-achievement-as-completed). For server-driven notifications (email, push, CRM) that must not depend on the client seeing the HTTP response, subscribe to the [`points.level_changed`](/webhooks/events/points/points-level-changed) webhook instead. This webhook fires when a user’s level changes as a result of earning or losing points, and includes `previousLevel` and `newLevel`.Account-level analytics
The [get level summary API](/api-reference/endpoints/points/get-points-level-summary) returns how many users are currently at each level which is useful for admin dashboards, funnel views, or balancing progression. ```json Response [expandable] theme={null} [ { "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "bronze", "name": "Bronze", "description": "Starting level", "badgeUrl": "https://example.com/bronze.png", "points": 0 }, "users": 5012 }, { "level": { "id": "2240fe51-6bce-4b44-b0ad-bddc4e123534", "key": "silver", "name": "Silver", "description": "Mid-tier level", "badgeUrl": null, "points": 50 }, "users": 1501 }, { "level": { "id": "3340fe51-6bce-4b44-b0ad-bddc4e123534", "key": "gold", "name": "Gold", "description": "Top level", "badgeUrl": "https://example.com/gold.png", "points": 200 }, "users": 102 } ] ```Displaying Points
There are a few ways to use Trophy to fetch and display points in your app.Triggering Transactional UI
Firstly, any points awarded to or deducted from users as a result of a metric change event are returned in the response when using the [metric change event API](/api-reference/endpoints/metrics/send-a-metric-change-event). The response includes the user's new total points, how many points were awarded or deducted as a result of the event, and the details of the specific points triggers that fired. When [Points Levels](#points-levels) are enabled, each points object in that response may also include **`level`**: Trophy includes the user's **new** level **only when it changed** as a result of that event. The same optional `level` behavior applies when points change from an [achievement completion](/api-reference/endpoints/achievements/mark-an-achievement-as-completed). Example `POST /metrics/{key}/event` response (fields match the Trophy API spec; your keys under `points` and `leaderboards` depend on your account): ```json Response [expandable] theme={null} { "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623", "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "total": 750, "achievements": [ { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "trigger": "metric", "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "metricName": "Flashcards Flipped", "metricValue": 500, "name": "500 Flashcards Flipped", "description": "Write 500 words in the app.", "achievedAt": "2020-01-01T00:00:00Z" } ], "currentStreak": { "length": 1, "frequency": "daily", "started": "2025-04-02", "periodStart": "2025-03-31", "periodEnd": "2025-04-05", "expires": "2025-04-12" }, "points": { "xp": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "key": "xp", "name": "XP", "description": null, "badgeUrl": null, "maxPoints": null, "total": 10, "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "bronze", "name": "Bronze", "description": "Starting level", "badgeUrl": null, "points": 0 }, "added": 10, "awards": [ { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "awarded": 10, "date": "2021-01-01T00:00:00Z", "total": 10, "trigger": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "type": "metric", "metricName": "Flashcards Flipped", "metricThreshold": 100, "points": 10 } } ] } }, "leaderboards": { "daily_champions": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535", "key": "daily_champions", "name": "Daily Champions", "description": null, "rankBy": "metric", "runUnit": null, "runInterval": 0, "maxParticipants": 100, "metricName": "Flashcards Flipped", "metricKey": "flashcards-flipped", "threshold": 10, "start": "2025-01-01", "end": null, "previousRank": 50, "rank": 12 } } } ``` This makes it really simple to read the response and trigger any of the following transactional UI in your application: * Displaying in-app notifications and pop-ups * Playing sound effectsDisplaying User's Points
Trophy also has APIs that allow you fetch user's points data whenever you want. First, the [user points API](/api-reference/endpoints/users/get-a-users-points) returns the user's total points for a particular points system, their current **`level`** (or `null` if levels are not in use or they have not reached a level yet), and up to 100 of the most recent events that awarded points to or deducted points from them. You can use this API to display the user's total points anywhere in your platform as well as a 'Latest awards' section or similar. `GET /users/{id}/points/{key}` — example response body (Trophy API spec): ```json Response [expandable] theme={null} { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "key": "xp", "name": "XP", "description": null, "badgeUrl": null, "maxPoints": null, "total": 100, "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "silver", "name": "Silver", "description": "Mid-tier level", "badgeUrl": null, "points": 50 }, "awards": [ { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "awarded": 10, "date": "2021-01-01T00:00:00Z", "total": 100, "trigger": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "type": "metric", "points": 10, "metricName": "Flashcards Flipped", "metricThreshold": 1000 } } ] } ```Displaying Aggregate Data
Additionally there are a number of APIs that can be used to fetch and display points data at the account level. First, the [points summary API](/api-reference/endpoints/points/get-points-summary) returns aggregate points system data across your entire user base. Use this data to display a histogram of points for a particular points system and show users how they compare to others on the platform. When you use [Points Levels](#points-levels), the [level summary API](/api-reference/endpoints/points/get-points-level-summary) complements this with a per-level user count. `GET /points/{key}/summary` — example **200** response (Trophy API spec): ```json GET /points/{key}/summary — 200 response [expandable] theme={null} [ { "from": 0, "to": 0, "users": 5012 }, { "from": 1, "to": 100, "users": 1501 }, { "from": 101, "to": 200, "users": 1007 }, { "from": 201, "to": 300, "users": 584 }, { "from": 301, "to": 400, "users": 201 }, { "from": 401, "to": 500, "users": 102 }, { "from": 501, "to": 600, "users": 25 }, { "from": 601, "to": 700, "users": 0 }, { "from": 701, "to": 800, "users": 0 }, { "from": 801, "to": 900, "users": 0 }, { "from": 901, "to": 1000, "users": 0 } ] ``` Finally, the [points system API](/api-reference/endpoints/points/get-points) returns the system metadata and triggers. Example **200** response (Trophy API spec): ```json GET /points/{key} — 200 response [expandable] theme={null} { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "name": "XP System", "description": "Experience points for user engagement", "badgeUrl": "https://example.com/badge.png", "maxPoints": null, "triggers": [ { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "type": "metric", "points": 10, "status": "active", "metricId": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "metricName": "words written", "metricThreshold": 1000, "userAttributes": [ { "key": "plan-type", "value": "premium" }, { "key": "region", "value": "us-east" } ], "eventAttributes": [ { "key": "source", "value": "mobile-app" }, { "key": "platform", "value": "ios" } ], "created": "2021-01-01T00:00:00Z", "updated": "2021-01-01T00:00:00Z" }, { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123536", "type": "streak", "points": 10, "status": "active", "streakLengthThreshold": 7, "created": "2021-01-01T00:00:00Z", "updated": "2021-01-01T00:00:00Z" }, { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535", "type": "achievement", "points": 50, "status": "active", "achievementId": "0040fe51-6bce-4b44-b0ad-bddc4e123535", "achievementName": "finish onboarding", "userAttributes": [{ "key": "plan-type", "value": "premium" }], "created": "2021-01-01T00:00:00Z", "updated": "2021-01-01T00:00:00Z" } ] } ```Points Analytics
Trophy has built-in analytics to track points awards for each points system you configure across your users in real time including: * Total points earned by all users over time * Most points earned by a single user * Average points earned in the first 14 days (useful for understanding new user retention patterns and the impact of points) * A breakdown on the most commonly awarded points triggersGet 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! # Push Notifications Source: https://docs.trophy.so/features/push-notifications Learn how to use push notifications in a gamified product experience with Trophy. Trophy can send automated push notifications to users based on key triggers without requiring any code. Here we’ll look at what these triggers are, and how they can form part of your product’s gamification experience.Types Of Push Notifications
Trophy supports 4 types of push notifications, each of which is designed to suit a common scenario in building gamification experiences. All push notifications are optional, but all four can be used simultaneously and can be controlled from the [Push Notifications](https://app.trophy.so/push/configure) page in the Trophy dashboard. * **Achievement notifications** are sent to users each time they unlock an [Achievement](/features/achievements). * **Recap notifications** are sent to users on a pre-defined frequency to summarize progress. Recap notifications can be configured to be sent daily, weekly, monthly or yearly depending on your use case. * **Reactivation notifications** are sent to users after they become inactive with the goal of bringing them back to your app. * **Streak notifications** are automatically sent to users reminding them to extend their [Streak](/features/streaks).Supported Channels
Trophy supports sending push notifications using 3 channels which can all be configured on the [Channels](https://app.trophy.so/push/channels) page of the Trophy dashboard.Apple Push Notification Service (APNs)
Trophy supports sending push notifications to users via APNs through a certificate-based connection. To send push notifications using APNs, you'll need to provide Trophy with the following credentials from your Apple Developer Account: * **APN Signing Key**: Trophy uses this to securely send notifications via APNs * **Team ID**: The team ID of your Apple Developer Account * **Key ID**: The ID of your APNs authentication key * **Bundle ID**: Your app's unique bundle identifierFirebase Cloud Messaging (FCM)
Trophy supports sending push notifications to users via FCM. To achieve this you'll need to provide Trophy with your Firebase Service Account JSON in the following format: ```json FCM Service Account JSON theme={null} { "type": "service_account", "project_id": "XXX", "private_key_id": "XXX", "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n", "client_email": "XXX@XXX.com", "client_id": "XXX", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/XXX" } ```Expo Push Service
Trophy supports sending push notifications to users via Expo Push Service. Expo Push Service saves you having to integrate with FCM and APNs individually and automatically directs notifications through the relevant service based on your users platform. To achieve this you must provide Trophy with a few key details from your Expo account: * **Expo Project Name**: The name of your Expo project * **Expo Push Token**: Your authentication token for sending notifications via Expo (required if using [enhanced security](https://docs.expo.dev/push-notifications/sending-notifications/#additional-security)).Sending Push Notifications
Follow the steps below to start sending push notifications using Trophy.Designing Push Notifications
By default, Trophy provides a template for each [type of push notification](#types-of-push-notifications) as a good starting point. The default templates can’t be changed, but you can duplicate and customize these as you wish.Template Structure
Each push notification has a title and body, and Trophy's no-code push notification template editor allows you to fully customize both fields.Using Variables
Trophy provides an expansive set of variables that can be used to insert highly relevant and personalized data into your push notifications. Variables can be inserted by typing `@` in the title or body of any push notification, and searching for your chosen variable. This will open up the variable editor window where you can configure variables as in the demo below. You can also test different variable values and how your template behaves in different scenarios by using the preview sidebar.Using Variations
Variations can be used to add randomness to the title and body of push notifications sent by Trophy. This prevents notifications from getting boring and helps improve engagement rates. At send time, Trophy automatically picks one of your variations of the title and body at random and sends the notification to the user.Using Conditions
Trophy's push notification template builder supports using conditions to send different content to each recipient based on their unique context. All [template variables](#using-variables) can be used in conditions to control what content is used in the title and body of notifications sent by Trophy. At send time Trophy computes all conditions using each recipients unique context, delivering highly personalized and relevant notifications to each user.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! # Streaks Source: https://docs.trophy.so/features/streaks Learn how to use streaks in a gamified product experience with Trophy.What are Streaks?
A streak is a period of consecutive days, weeks or months that a user has performed a key action on your platform. Streaks have been shown to meaningfully increase retention, particularly when the user action being tracked aligns with the core value of your product.Streak Frequency
Streaks in Trophy can be **daily, weekly or monthly**. This means that a user must meet their [streak conditions](#streak-conditions) at least once every calendar day, week or month to maintain their streak. If you've [configured time zones](/features/users#param-tz) for your users, Trophy will automatically track each user's streak in their local time zone (including taking into account when users change time zones) and keep streaks in tact.Streak Conditions
In Trophy you can set the thresholds that a user must meet in order to extend their streak based on your configured [Metrics](/features/metrics). You can choose which metrics should be part of your streak, and for those that you chose, you can set a custom threshold that users must meet.Streak Freezes
Streak freezes help users keep their streaks for longer by allowing them to miss periods without it resetting to zero. This helps keep streaks motivating even if users don't maintain a perfect usage habit.Granting Initial Freezes
You can configure any number of arbitrary freezes to grant to new users when you first identify them with Trophy.Freeze Accumulation
As users use up streak freezes, they'll need a continuous supply of new ones to keep them going. To facilitate this, Trophy can automatically grant streak freezes to users over time. You can choose an arbitrary number of days over which to grant an arbitrary number of freezes to each user. If you've [configured time zones](/features/users#param-tz) for your users, Trophy will automatically consume freezes at midnight in the user's time zone when necessary to extend their streak, and if any new freezes are due to be granted to a user, they will be granted up to ten minutes later.Maximum Freeze Count
In Trophy you also configure the maximum number of freezes that each user can have, up to a limit of 100. [Freeze accumulation](#freeze-accumulation) will only ever grant freezes up to this limit.Tracking Streaks
Trophy automatically calculates streaks for all users based on the [metric events](/features/events#tracking-metric-events) you report to Trophy. There's no extra work required to track streaks, and you can start using them right away. Just make sure that streaks are enabled in the Trophy dashboard.Streak Personalization
Trophy can support users personalizing how their streak works within guardrails you set for them. To do this, turn on streak personalization in the [streaks page](https://app.trophy.so/streaks) of the Trophy dashboard. Once enabled, users will be able to customize the [streak conditions](#streak-conditions) that they must meet to extend their streak, including streak evaluation mode and the threshold for each metric, through user preferences.Managing Streaks
This section outlines some of the operations you can perform to manage user's streaks in your application.Restoring A Users Streak
To restore a user's streak, head to the user details page and use the 'Restore Streak' action. Restoring a user's streak sets it to the length it was when they last lost it.Displaying Streaks
Trophy exposes streak data in two ways, which can be used to build UI elements within your applications and display streaks to users.Metric Event Response
When you [increment a metric](/features/events#tracking-metric-events) for a user, the [metric API](/api-reference/endpoints/metrics/send-a-metric-change-event) response will include the user's current streak. ```json Response [expandable] theme={null} { "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623", "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "total": 750, "achievements": [ { "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "trigger": "metric", "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682", "metricName": "Flashcards Flipped", "metricValue": 500, "name": "500 Flashcards Flipped", "description": "Write 500 words in the app.", "achievedAt": "2020-01-01T00:00:00Z" } ], "currentStreak": { "length": 1, "frequency": "daily", "started": "2025-04-02", "periodStart": "2025-03-31", "periodEnd": "2025-04-05", "expires": "2025-04-12" }, "points": { "xp": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "key": "xp", "name": "XP", "description": null, "badgeUrl": null, "maxPoints": null, "total": 10, "level": { "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534", "key": "bronze", "name": "Bronze", "description": "Starting level", "badgeUrl": null, "points": 0 }, "added": 10, "awards": [ { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "awarded": 10, "date": "2021-01-01T00:00:00Z", "total": 10, "trigger": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534", "type": "metric", "metricName": "Flashcards Flipped", "metricThreshold": 100, "points": 10 } } ] } }, "leaderboards": { "daily_champions": { "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535", "key": "daily_champions", "name": "Daily Champions", "description": null, "rankBy": "metric", "runUnit": null, "runInterval": 0, "maxParticipants": 100, "metricName": "Flashcards Flipped", "metricKey": "flashcards-flipped", "threshold": 10, "start": "2025-01-01", "end": null, "previousRank": 50, "rank": 12 } } } ``` This can be used to transactionally trigger UI/UX elements including: * Showing in-app pop-ups * Playing sound effectsUser Streaks API
The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns the current streak for a single user, along with their recent streak history. Use the `historyPeriods` query parameter to control how many periods to return. ```json Response [expandable] theme={null} { "length": 1, "frequency": "weekly", "started": "2025-04-02", "periodStart": "2025-03-31", "periodEnd": "2025-04-05", "expires": "2025-04-12", "rank": 5, "streakHistory": [ { "periodStart": "2025-03-02", "periodEnd": "2025-03-08", "length": 9 }, { "periodStart": "2025-03-09", "periodEnd": "2025-03-15", "length": 0 }, { "periodStart": "2025-03-16", "periodEnd": "2025-03-22", "length": 0 }, { "periodStart": "2025-03-23", "periodEnd": "2025-03-29", "length": 1 }, { "periodStart": "2025-03-30", "periodEnd": "2025-04-05", "length": 2 }, { "periodStart": "2025-04-06", "periodEnd": "2025-04-12", "length": 3 }, { "periodStart": "2025-04-13", "periodEnd": "2025-04-19", "length": 4 } ] } ``` Use this data to display a user's streak history within your application.List Multiple User's Streaks
If you want to display streaks for multiple users at once, for example to support a friend streak or user group feature, then use the [list user streaks API](/api-reference/endpoints/streaks/get-streaks). ```json [expandable] theme={null} [ { "userId": "user-123", "streakLength": 15, "extended": "2025-01-01T05:03:00Z" }, { "userId": "user-456", "streakLength": 12, "extended": "2025-01-01T08:43:00Z" }, { "userId": "user-789", "streakLength": 0, "extended": null } ] ```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! # Users Source: https://docs.trophy.so/features/users Learn how to track interactions across your userbase using Trophy.What are Users?
Users are the individual people that use your product. You tell Trophy about your users through APIs and use the dashboard to design gamification experiences around them. Users must be individuals, they cannot be companies or organisations. To create organizational structures or user groupings, consider using a [custom user attribute](#custom-user-attributes).Key Attributes
Key attributes are properties of users controlled and managed by Trophy and are for things like `id` or `email`, some are required while others are optional.Required Attributes
Trophy only requires one key attribute, `id`. Every user you tell Trophy about must have an `id`, this is what identifies them as a unique person.Optional Attributes
Additionally, you can tell Trophy about any of the following optional key attributes and it will make them available to you as part of your gamification experience:Custom User Attributes
Creating Attributes
To create a new custom user attribute, head to the [attributes tab](https://app.trophy.so/users/attributes) of the users page in the Trophy dashboard and hit the *Add User Attribute* button. Give the attribute a name and a unique key. The key is what you'll use to reference the attribute in API calls.Setting Attributes
Attributes can be assigned values for specific users using their unique key either inline, as users increment metrics through the [metric increment API](/api-reference/endpoints/metrics/send-a-metric-change-event), or explicitly through the [user identification](/api-reference/endpoints/users/identify-a-user), [create user](/api-reference/endpoints/users/create-a-user), or [update user](/api-reference/endpoints/users/update-a-user) APIs.Using Attributes
Use custom user attributes across Trophy to personalize gamification features , aggregate and filter data returned from APIs, and to segment and compare user cohorts in analytics.Feature Personalization
Custom user attributes can be used to personalize achievements, customize the way points are earned by different users and more. Follow the links to the relevant pages below to learn more.Data Aggregation and Filtering
You can use custom user attributes to aggregate and filter data returned from some APIs to support a wide range of gamification use cases. In all cases, attributes are included in the `userAttributes` query parameter using a consistent schema: `?userAttributes=city:london,subscription-plan:pro` Here's a list of all APIs that support the `userAttributes` query parameter: * [Points Summary](/api-reference/endpoints/points/get-points-summary)Segmented Analytics
Custom user attributes can be used to segment and compare retention and engagement charts between user groups. This is useful to understand which cohorts are making full use of your gamification features, and which are struggling to engage and therefore require some attention.Identifying Users
When you tell Trophy about a user in your platform, we call this **identification**. There are two ways you can identify users with Trophy, [inline](#inline-identification) and [explicit](#explicit-identification) identification.Inline Identification
Inline identification is the easiest way of telling Trophy about your users as it doesn't require any specific user identification code. You simply tell Trophy about users as they go about normal use of your platform. In practice this means whenever you use the [Metric Event API](/api-reference/endpoints/metrics/send-a-metric-change-event), you pass along full details of the user who triggered the event. Here's an example where an API call is made to the metric events API, and the details of the user who made the interaction are passed along in the request body:```mermaid theme={null} flowchart LR A@{ shape: sm-circ } B@{ shape: diamond, label: "Is new user?" } C@{ shape: rounded, label: "Identify new user" } D@{ shape: rounded, label: "Update existing user" } E@{ shape: rounded, label: "Process event" } F@{ shape: framed-circle } A-->B B-- Yes --->C B-- No --->D C-->E D-->E E-->F ```
Identifying users in this way has two key benefits: * All new users that sign up for your platform and increment a metric are automatically tracked in Trophy without any explicit identification code written by you * Any changes to existing user properties like name or email address are automatically synced to Trophy the next time the user increments a metric In this way inline identification allows you to keep your entire userbase in constant sync with Trophy with the least amount of code required by you. This is why we recommend starting with inline identification first, then exploring explicit identification if you discover you need more control.
Explicit Identification
Explicit identification is when you write code in your application that explicitly tells Trophy about users separate from any metric interactions. This is useful if you want complete control over how and when Trophy learns about your users. Scenarios where you might want to use explicit identification might be: * You want to tell Trophy about new users immediately on sign-up, before they increment a metric * You track a lot of metrics in Trophy, and don't want to repeat inline identification code. * You want to only tell Trophy about a specific cohort of users, of which you control the conditions around In this case, you can tell Trophy about new users using the [User Identification API](/api-reference/endpoints/users/identify-a-user).Creating Users
To explicitly create a new user in Trophy, use the [Create User API](/api-reference/endpoints/users/create-a-user).Keeping Users Up To Date
To tell Trophy about an update to a user in your platform you can use the [Update User API](/api-reference/endpoints/users/update-a-user). Any properties that you pass to Trophy will be updated to the new values you specify.Setting User Preferences
Trophy has APIs to help you power a preference center that your users can use to control and customize how they interact with your gamification features. This section walks through all the preferences that you can expose to your users, and their function.Notification Preferences
You can use Trophy to send gamified [Emails](/features/emails) and [Push Notifications](/features/push-notifications) to your users. Trophy's [update preferences API](/api-reference/endpoints/users/update-user-preferences) allows you to build a preference center within your application that your users can interact with to control which notifications they receive, and through which channels.Streak Preferences
Trophy supports user preferences for streaks, allowing users to customize the conditions they must meet to extend their streak.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). This will return the full details of the user along with the `control` attribute that you can use to conditionally enroll users in any gamification features. Learn more about [Experimentation](/platform/experimentation). ```json Response {3} theme={null} { "id": "user-id", "control": false, "created": "2021-01-01T00:00:00Z", "email": "user@example.com", "name": "User", "subscribeToEmails": true, "tz": "Europe/London", "updated": "2021-01-01T00:00:00Z" } ```User Analytics
Basic Analytics
By default Trophy includes high-level user analytics including on the [Users page](https://app.trophy.so/users) including: * The total number of users that you've told Trophy about * The number of users that are active on a daily basis * The number of users that are active on a monthly basisTop Users
Additionally, on the [Dashboard](https://app.trophy.so), Trophy shows a *Top Users* list with the set of users who have made the most progress against your platform's metrics. These are your most engaged users, so it's useful to know who they are!Frequently Asked Questions
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! # Welcome to Trophy Source: https://docs.trophy.so/getting-started/introduction Trophy documentation for gamification APIs, quickstart guides and tutorials. Trophy is a developer-friendly toolkit for building gamified product experiences in any mobile or web app. It makes building features like [Achievements](/features/achievements), [Streaks](/features/streaks), [Points](/features/points) and [Leaderboards](/features/leaderboards) simple with just a few lines of code, and can send gamified [Emails](/features/emails) and [Push Notifications](/features/push-notifications) to increase your retention and engagement.Why Trophy
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! # Quick Start Source: https://docs.trophy.so/getting-started/quickstart Get up and running with Trophy in under 10 minutes Here you'll integrate your backend web application with Trophy and start building your first gamified feature.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! # How to Build a Gamified Fitness Tracker Source: https://docs.trophy.so/guides/gamified-fitness-platform Learn how to build a Strava-like fitness app with Next.js, featuring multi-sport tracking, city-based leaderboards, and normalized XP progression. In this tutorial, we'll build **TrophyFitness**, a consumer fitness application that tracks running, cycling, and swimming. We'll implement a complete gamification loop including weekly leaderboards, habit-forming streaks, and a leveled progression system. If you want to skip straight to the code, check out the [example repository](https://github.com/trophyso/example-fitness-platform) or the [live demo](https://fitness.examples.trophy.so).Table of Contents
* [Tech Stack](#tech-stack) * [Prerequisites](#prerequisites) * [Setup & Installation](#setup-installation) * [Designing the Data Model](#designing-the-data-model) * [How Trophy Works](#how-trophy-works) * [Setting Up Trophy](#setting-up-trophy) * [Server Actions](#server-actions) * [The Leveling System](#the-leveling-system) * [Building the Dashboard](#building-the-dashboard) * [Logging Workouts](#logging-workouts) * [Implementing Leaderboards](#implementing-leaderboards) * [Building the Achievements Page](#building-the-achievements-page) * [Building the Profile Page](#building-the-profile-page) * [The Result](#the-result)Tech Stack
* **Framework:** [Next.js 15](https://nextjs.org) (App Router) * **UI:** [Shadcn/UI](https://ui.shadcn.com) + TailwindCSS * **Icons:** [Lucide React](https://lucide.dev) * **Gamification:** [Trophy](https://trophy.so)Prerequisites
* A Trophy account (sign up [here](https://app.trophy.so/sign-up)). * Node.js 18+ installed.Setup & Installation
First, clone the starter repository or create a new Next.js app: ```bash theme={null} npx create-next-app@latest trophy-fitness ``` Install the required dependencies: ```bash theme={null} npm install @trophyso/node lucide-react clsx tailwind-merge ``` Configure your environment variables in `.env.local`: ```bash theme={null} TROPHY_API_KEY=your_api_key_here ```Designing the Data Model
For a multi-sport fitness app, we need to normalize efforts. A 10km cycle is not the same as a 10km run. We'll use three distinct metrics to track raw data, and a unified XP system for progression.1. The Metrics
We will track distance as the primary value. * `distance_run` (km) - with `pace` attribute (walk/run). * `distance_cycled` (km) * `distance_swum` (m) - with `style` attribute (freestyle/breaststroke).2. The Attributes
To enable local leaderboards, we'll tag every user with a `city` attribute.How Trophy Works
Before diving into the code, let's understand how Trophy powers our gamification layer. In Trophy, [Metrics](/features/metrics) represent different interactions users can make and drive features like [Achievements](/features/achievements), [Streaks](/features/streaks), and [Emails](/features/emails). ```mermaid theme={null} flowchart TD A@{ shape: rounded, label: "Events" } B@{ shape: rounded, label: "Metrics" } C@{ shape: rounded, label: "Achievements" } D@{ shape: rounded, label: "Streaks" } E@{ shape: rounded, label: "Leaderboards" } F@{ shape: rounded, label: "Points" } G@{ shape: rounded, label: "Emails" } A-.->B B-->C B-->D B-->E B-->F B-->G ``` When events are recorded for a specific user, any achievements linked to the specified metric will be unlocked if the requirements are met, streaks will be automatically calculated, leaderboards will update, and any configured emails will be scheduled. This is what makes building gamified experiences with Trophy so powerful—it does all the work behind the scenes.Setting Up Trophy
Here's how we'll configure Trophy for our fitness app:Server Actions
We'll create a `src/app/actions.ts` file to handle all interactions with the Trophy API. This keeps our API keys secure and allows us to leverage Next.js Server Actions. ```tsx src/app/actions.ts [expandable] theme={null} "use server"; import { TrophyApiClient, TrophyApi } from "@trophyso/node"; import { revalidatePath } from "next/cache"; const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY as string, }); export async function identifyUser(userId: string, name?: string, tz?: string) { try { const user = await trophy.users.identify(userId, { name, tz }); return { success: true, user }; } catch (error) { return { success: false, error: "Failed to identify user" }; } } export async function updateUserCity(userId: string, city: string) { try { await trophy.users.update(userId, { attributes: { city } }); revalidatePath("/leaderboards"); revalidatePath("/profile"); return { success: true }; } catch (error) { return { success: false, error: "Failed to update city" }; } } export async function getUserStats(userId: string) { try { // Fetch all user data in parallel const [streak, achievements, metrics, pointsResponse, pointsLevels] = await Promise.all([ trophy.users.streak(userId).catch(() => null), trophy.users .achievements(userId, { includeIncomplete: "true" }) .catch(() => []), trophy.users.allMetrics(userId).catch(() => []), trophy.users.points(userId, "xp").catch(() => null), trophy.points.levels("xp").catch(() => []), ]); return { streak, achievements, points: pointsResponse, pointsLevels, metrics, }; } catch (error) { console.error("Failed to fetch user stats:", error); return null; } } export async function logActivity(params: { type: "run" | "cycle" | "swim"; distance: number; userId: string; city?: string; pace?: string; style?: string; }) { const { type, distance, userId, city, pace, style } = params; let metricKey = ""; const eventAttributes: RecordThe Leveling System
Trophy stores each user's tier on the `xp` points system when you configure [Points Levels](/features/points#points-levels). The [user points](/api-reference/endpoints/users/get-a-users-points) payload includes a `level` object. The [list levels API](/api-reference/endpoints/points/get-points-levels) returns every tier and threshold so you can show progress toward the next one. Add a small helper next to your app constants in `src/lib/constants.ts`: ```tsx src/lib/constants.ts theme={null} export type ActivityType = "run" | "cycle" | "swim"; /** Shape of a level from Trophy (`GET /points/{key}/levels`). */ export type TrophyPointsLevel = { id: string; key: string; name: string; description: string | null; badgeUrl: string | null; points: number; }; /** * Derive progress from Trophy totals + levels. Prefer `currentLevel` from the user * points API when present; otherwise infer from `total` and threshold order. */ export function getLevelProgress( total: number, levels: TrophyPointsLevel[], currentLevel: TrophyPointsLevel | null | undefined, ) { const sorted = [...levels].sort((a, b) => a.points - b.points); if (sorted.length === 0) { return { currentLevel: null as TrophyPointsLevel | null, tierNumber: null as number | null, nextLevel: null as TrophyPointsLevel | null, progressToNextLevel: 0, xpToNext: null as number | null, }; } let current = currentLevel ?? null; if (!current) { for (let i = sorted.length - 1; i >= 0; i--) { if (total >= sorted[i].points) { current = sorted[i]; break; } } } const idx = current != null ? sorted.findIndex((l) => l.key === current.key) : -1; const tierNumber = idx >= 0 ? idx + 1 : null; const nextLevel = idx >= 0 && idx < sorted.length - 1 ? sorted[idx + 1] : null; let progressToNextLevel = 100; let xpToNext: number | null = null; if (nextLevel != null && current != null) { const span = nextLevel.points - current.points; const into = total - current.points; progressToNextLevel = span > 0 ? Math.min(100, Math.max(0, (into / span) * 100)) : 100; xpToNext = Math.max(0, nextLevel.points - total); } else if (nextLevel != null && current == null) { const span = nextLevel.points; progressToNextLevel = span > 0 ? Math.min(100, Math.max(0, (total / span) * 100)) : 0; xpToNext = Math.max(0, nextLevel.points - total); } return { currentLevel: current, tierNumber, nextLevel, progressToNextLevel, xpToNext, }; } ```Building the Dashboard
The dashboard aggregates all user stats. We fetch data server-side and derive progress bars from thresholds returned by the API. ```tsx src/app/page.tsx [expandable] theme={null} import { getUserStats, getUserIdFromCookies, getRecentActivities, } from "./actions"; import { getLevelProgress } from "@/lib/constants"; import { Zap, Flame, Footprints, Bike, Waves, Trophy, TrendingUp, } from "lucide-react"; import { Card, CardContent } from "@/components/ui/card"; import { Progress } from "@/components/ui/progress"; import { Button } from "@/components/ui/button"; import { LogActivityDialog } from "@/components/log-activity-dialog"; export default async function Dashboard() { const userId = await getUserIdFromCookies(); const [stats, recentActivities] = await Promise.all([ getUserStats(userId ?? ""), getRecentActivities(userId ?? ""), ]); const streakLength = stats?.streak?.length ?? 0; const totalXP = stats?.points?.total ?? 0; const levelProgress = getLevelProgress( totalXP, stats?.pointsLevels ?? [], stats?.points?.level, ); // Helper to get total for a metric key const getMetricTotal = (key: string) => stats?.metrics?.find((m) => m.key === key)?.current ?? 0; // Find the next badge to earn const nextAchievement = stats?.achievements?.find((a) => !a.achievedAt); return (
{/* Level & Streak Header */}
0 ? "text-orange-500" : "text-muted-foreground"}`}
/>
{streakLength}
day streak
{/* Stats Grid */}
{/* Repeat for Cycle and Swim... */}
{/* Next Badge Teaser */}
{nextAchievement && (
)}
);
}
```
Note the `LogActivityDialog` wrapper around the button—we'll build that next.
{levelProgress.tierNumber != null
? `Level ${levelProgress.tierNumber}`
: "Level"}
{levelProgress.currentLevel?.name ?? "XP"}
{totalXP} XP
{levelProgress.nextLevel != null && levelProgress.xpToNext != null && (
{levelProgress.xpToNext} XP to {levelProgress.nextLevel.name}
)}
{getMetricTotal("distance_run").toFixed(1)}
km run
Next Badge
{nextAchievement.name}
{nextAchievement.description}
Logging Workouts
The Log Workout button opens a dialog where users select their activity type, enter distance, and submit. This triggers the `logActivity` server action which sends the event to Trophy. First, install the required shadcn/ui components: ```bash theme={null} npx shadcn@latest add dialog tabs input label select ``` Then create the dialog component: ```tsx components/log-activity-dialog.tsx [expandable] theme={null} "use client"; import { useState, useTransition } from "react"; import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger, DialogDescription, } from "@/components/ui/dialog"; import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"; import { Button } from "@/components/ui/button"; import { Input } from "@/components/ui/input"; import { Label } from "@/components/ui/label"; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "@/components/ui/select"; import { Footprints, Bike, Waves, Loader2, Zap } from "lucide-react"; import { toast } from "sonner"; import { logActivity } from "@/app/actions"; import { ActivityType } from "@/lib/constants"; import { getUserCity } from "@/lib/city"; import { useUser } from "@/components/user-provider"; export function LogActivityDialog({ children }: { children: React.ReactNode }) { const { userId } = useUser(); const [open, setOpen] = useState(false); const [isPending, startTransition] = useTransition(); const [activeTab, setActiveTab] = useStateUser Context
The dialog needs access to the current user ID. Create a context provider: ```tsx components/user-provider.tsx [expandable] theme={null} "use client"; import { createContext, useContext, useEffect, useState, ReactNode } from "react"; import { getUserId, getUserName } from "@/lib/user"; import { identifyUser } from "@/app/actions"; interface UserContextType { userId: string | null; userName: string | null; isLoading: boolean; } const UserContext = createContextHelper Utilities
The user context relies on helper functions for managing user identity in localStorage: ```tsx lib/user.ts [expandable] theme={null} const USER_ID_KEY = "trophy-fitness-user-id"; const USER_NAME_KEY = "trophy-fitness-user-name"; const ADJECTIVES = ["Swift", "Mighty", "Blazing", "Iron", "Golden", "Thunder", "Lightning"]; const NOUNS = ["Runner", "Cyclist", "Swimmer", "Athlete", "Champion", "Tiger", "Eagle"]; function generateRandomName(): string { const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)]; const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)]; return `${adj}${noun}${Math.floor(Math.random() * 100)}`; } export function getUserId(): string { let userId = localStorage.getItem(USER_ID_KEY); if (!userId) { userId = crypto.randomUUID(); localStorage.setItem(USER_ID_KEY, userId); localStorage.setItem(USER_NAME_KEY, generateRandomName()); } // Sync to cookie for server-side access document.cookie = `${USER_ID_KEY}=${userId}; path=/; max-age=31536000; SameSite=Lax`; return userId; } export function getUserName(): string | null { return localStorage.getItem(USER_NAME_KEY); } ``` For city-based leaderboards, we infer the user's city from their timezone: ```tsx lib/city.ts [expandable] theme={null} const TIMEZONE_TO_CITY: RecordImplementing Leaderboards
We'll build a tabbed interface that allows users to switch between activities (Run/Cycle/Swim) and scopes (Global vs. Local City). ```tsx src/app/leaderboards/page.tsx [expandable] theme={null} "use client"; import { useState, useEffect, useMemo } from "react"; import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"; import { getLeaderboard } from "@/app/actions"; import { Trophy, Globe, MapPin } from "lucide-react"; import { getUserCity } from "@/lib/city"; export default function LeaderboardsPage() { const [scope, setScope] = useState<"global" | "city">("global"); const [activeTab, setActiveTab] = useState("run"); const [data, setData] = useState([]); // Get user's city from localStorage const city = useMemo(() => getUserCity(), []); useEffect(() => { // Determine the leaderboard key based on tab and scope const baseKey = `weekly-distance-${activeTab}`; const key = scope === "city" ? `${baseKey}-cities` : baseKey; const cityParam = scope === "city" ? city : undefined; getLeaderboard(key, cityParam).then(setData); }, [scope, activeTab, city]); return (
{/* Scope Toggle */}
{index + 1}
{entry.userName || "Anonymous"}
{entry.value} {activeTab === "swim" ? "m" : "km"}
Building the Achievements Page
A dedicated space to show off badges is essential for long-term retention. We'll use the `stats.achievements` data to render a grid of badges, visually distinguishing between earned (colorful) and locked (grayscale) states. ```tsx src/app/achievements/page.tsx [expandable] theme={null} import { getUserStats, getUserIdFromCookies } from "@/app/actions"; import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"; import { Card, CardContent } from "@/components/ui/card"; import { Award, Lock } from "lucide-react"; export default async function AchievementsPage() { const userId = await getUserIdFromCookies(); const stats = await getUserStats(userId ?? ""); // Helper to split achievements const earned = stats?.achievements?.filter((a) => a.achievedAt) ?? []; const locked = stats?.achievements?.filter((a) => !a.achievedAt) ?? []; const AchievementCard = ({ achievement, isEarned }) => (
{isEarned ? (
{achievement.name}
{achievement.description}
Building the Profile Page
Finally, the profile page brings it all together. It shows the user's "Lifetime Stats," their current XP progression, and allows them to update their settings (like their city). ```tsx src/app/profile/page.tsx [expandable] theme={null} import { getUserStats, getUserIdFromCookies } from "@/app/actions"; import { getLevelProgress } from "@/lib/constants"; import { Avatar, AvatarFallback } from "@/components/ui/avatar"; import { Card, CardContent } from "@/components/ui/card"; import { Progress } from "@/components/ui/progress"; import { CitySetting } from "@/components/city-setting"; export default async function ProfilePage() { const userId = await getUserIdFromCookies(); const stats = await getUserStats(userId ?? ""); const levelProgress = getLevelProgress( stats?.points?.total ?? 0, stats?.pointsLevels ?? [], stats?.points?.level, ); // Helper to safely get metric totals const getTotal = (key: string) => stats?.metrics?.find((m) => m.key === key)?.current ?? 0; return (
{/* Header */}
ME
{/* Progress Card */}
{/* Lifetime Stats */}
{/* Repeat for other sports... */}
{/* Settings Component (Client Component) */}
);
}
```
Athlete Profile
{levelProgress.currentLevel?.name ?? "Athlete"}
Experience Points
{stats?.points?.total ?? 0} XP
{getTotal("distance_run").toFixed(1)}
km run