Conversation
cbrinicombe13
commented
Mar 24, 2026
cbrinicombe13
commented
- Add docs for points levels
- Update badge docs to also describe custom URL option
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
| src="../assets/guides/example-apps/example-fitness-app/points-triggers.png" | ||
| /> | ||
| </Frame> | ||
|
|
There was a problem hiding this comment.
if we're updating the guide here, we should also update the actual fitness platform repo right? were you gonna do that or should I
There was a problem hiding this comment.
I guess we can do yeah, do you wanna do it since you built it and probably know it better than me?
platform/points.mdx
Outdated
|
|
||
| Points levels are discrete milestones you define on a points system in Trophy. | ||
|
|
||
| Each level has a threshold that when a user's total points in that system reaches (through the [points triggers](#points-triggers) you configure), Trophy assigns them that level automatically. You do not need to maintain tier logic in your own codebase. |
There was a problem hiding this comment.
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 tier logic in your own codebase.
platform/points.mdx
Outdated
|
|
||
| Each level has a threshold that when a user's total points in that system reaches (through the [points triggers](#points-triggers) you configure), Trophy assigns them that level automatically. You do not need to maintain tier logic in your own codebase. | ||
|
|
||
| Use levels for rank tiers, progression UI, messaging when someone advances, or analytics. Trophy keeps each user's current level in sync whenever they earn or lose points in that system. |
There was a problem hiding this comment.
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.
platform/points.mdx
Outdated
|
|
||
| ### 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 add manage levels. |
There was a problem hiding this comment.
and use the levels tab to add or manage levels.
platform/points.mdx
Outdated
|
|
||
| ### Displaying Levels | ||
|
|
||
| Most teams combine three pieces: a static picture of every tier (for progression screens), the user’s current tier (for headers and profile), and immediate feedback when an action pushes them into a new tier. |
There was a problem hiding this comment.
pieces -> approaches ?
platform/points.mdx
Outdated
|
|
||
| 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 tier changed because of this event. If their tier stayed the same, that key is omitted, so you can safely treat a present `level` as a level-up (or tier change) signal without extra bookkeeping. |
There was a problem hiding this comment.
we should never use "tier", it's confusing. when the user's level changed, if their level stayed the same
There was a problem hiding this comment.
Seeing a bunch of references to tiers across this PR, IMO all should be updated to 'levels' except in the case of definitions ("Levels are a way to group users into tiers based on their points totals...")
platform/points.mdx
Outdated
| ```ts | ||
| const pts = response.points?.xp; // use your points system key | ||
|
|
||
| if (pts?.level != null) { |
There was a problem hiding this comment.
better is if (pts?.level) IMO
platform/points.mdx
Outdated
|
|
||
| if (pts?.level != null) { | ||
| // Tier changed on this request — e.g. toast, modal, confetti | ||
| notifyLevelUp(pts.level.name, pts.total); |
There was a problem hiding this comment.
this is not necessary a level up. Could be a level down.
platform/points.mdx
Outdated
| 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 and up to 100 of the most recent events that awarded points to or deducted points from them. | ||
| 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 tier yet), and up to 100 of the most recent events that awarded points to or deducted points from them. |
platform/points.mdx
Outdated
| 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. | ||
| 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-tier user count. |
2 participants
