From 8433fd2e0a2b086a1097fb0aecdf5ecb75f4bf20 Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Wed, 28 Oct 2026 23:17:48 +0000 Subject: [PATCH 1/4] Add english files --- .../rewards/create-reward-triggers.mdx | 10 + .../endpoints/rewards/create-rewards.mdx | 10 + .../rewards/delete-reward-triggers.mdx | 10 + .../endpoints/rewards/delete-rewards.mdx | 10 + .../rewards/get-a-reward-trigger.mdx | 10 + admin-api/endpoints/rewards/get-a-reward.mdx | 10 + .../rewards/list-reward-triggers.mdx | 10 + admin-api/endpoints/rewards/list-rewards.mdx | 10 + .../rewards/update-reward-triggers.mdx | 10 + .../endpoints/rewards/update-rewards.mdx | 10 + .../endpoints/rewards/redeem-a-reward.mdx | 10 + .../endpoints/users/get-a-users-rewards.mdx | 10 + docs.json | 30 + features/achievements.mdx | 4 + features/leaderboards.mdx | 4 + features/overview.mdx | 5 +- features/points.mdx | 12 +- features/rewards.mdx | 253 + features/streaks.mdx | 4 + getting-started/introduction.mdx | 3 +- guides/how-to-build-an-xp-feature.mdx | 4 + openapi/admin.json | 10292 ++++++++++------ openapi/application.json | 651 +- platform/data-sync.mdx | 1 + .../admin-create-reward-request-block.mdx | 168 + ...in-create-reward-trigger-request-block.mdx | 108 + ...c-event-rewards-response-excerpt-block.mdx | 31 + snippets/redeem-reward-request-block.mdx | 80 + snippets/redeem-reward-response-block.mdx | 37 + snippets/user-rewards-request-block.mdx | 61 + snippets/user-rewards-response-block.mdx | 28 + .../webhook-reward-awarded-payload-block.mdx | 41 + .../webhook-reward-redeemed-payload-block.mdx | 41 + webhooks/events/points/points-changed.mdx | 4 + webhooks/events/rewards/reward-awarded.mdx | 11 + webhooks/events/rewards/reward-redeemed.mdx | 10 + 36 files changed, 7911 insertions(+), 4092 deletions(-) create mode 100644 admin-api/endpoints/rewards/create-reward-triggers.mdx create mode 100644 admin-api/endpoints/rewards/create-rewards.mdx create mode 100644 admin-api/endpoints/rewards/delete-reward-triggers.mdx create mode 100644 admin-api/endpoints/rewards/delete-rewards.mdx create mode 100644 admin-api/endpoints/rewards/get-a-reward-trigger.mdx create mode 100644 admin-api/endpoints/rewards/get-a-reward.mdx create mode 100644 admin-api/endpoints/rewards/list-reward-triggers.mdx create mode 100644 admin-api/endpoints/rewards/list-rewards.mdx create mode 100644 admin-api/endpoints/rewards/update-reward-triggers.mdx create mode 100644 admin-api/endpoints/rewards/update-rewards.mdx create mode 100644 api-reference/endpoints/rewards/redeem-a-reward.mdx create mode 100644 api-reference/endpoints/users/get-a-users-rewards.mdx create mode 100644 features/rewards.mdx create mode 100644 snippets/admin-create-reward-request-block.mdx create mode 100644 snippets/admin-create-reward-trigger-request-block.mdx create mode 100644 snippets/metric-event-rewards-response-excerpt-block.mdx create mode 100644 snippets/redeem-reward-request-block.mdx create mode 100644 snippets/redeem-reward-response-block.mdx create mode 100644 snippets/user-rewards-request-block.mdx create mode 100644 snippets/user-rewards-response-block.mdx create mode 100644 snippets/webhook-reward-awarded-payload-block.mdx create mode 100644 snippets/webhook-reward-redeemed-payload-block.mdx create mode 100644 webhooks/events/rewards/reward-awarded.mdx create mode 100644 webhooks/events/rewards/reward-redeemed.mdx diff --git a/admin-api/endpoints/rewards/create-reward-triggers.mdx b/admin-api/endpoints/rewards/create-reward-triggers.mdx new file mode 100644 index 00000000..dc697578 --- /dev/null +++ b/admin-api/endpoints/rewards/create-reward-triggers.mdx @@ -0,0 +1,10 @@ +--- +title: Create reward triggers +openapi: "/openapi/admin.json POST /rewards/{rewardId}/triggers" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/create-rewards.mdx b/admin-api/endpoints/rewards/create-rewards.mdx new file mode 100644 index 00000000..982e1e53 --- /dev/null +++ b/admin-api/endpoints/rewards/create-rewards.mdx @@ -0,0 +1,10 @@ +--- +title: Create rewards +openapi: "/openapi/admin.json POST /rewards" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/delete-reward-triggers.mdx b/admin-api/endpoints/rewards/delete-reward-triggers.mdx new file mode 100644 index 00000000..ca9e3220 --- /dev/null +++ b/admin-api/endpoints/rewards/delete-reward-triggers.mdx @@ -0,0 +1,10 @@ +--- +title: Delete reward triggers +openapi: "/openapi/admin.json DELETE /rewards/{rewardId}/triggers" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/delete-rewards.mdx b/admin-api/endpoints/rewards/delete-rewards.mdx new file mode 100644 index 00000000..639707f2 --- /dev/null +++ b/admin-api/endpoints/rewards/delete-rewards.mdx @@ -0,0 +1,10 @@ +--- +title: Delete rewards +openapi: "/openapi/admin.json DELETE /rewards" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/get-a-reward-trigger.mdx b/admin-api/endpoints/rewards/get-a-reward-trigger.mdx new file mode 100644 index 00000000..ce6e0502 --- /dev/null +++ b/admin-api/endpoints/rewards/get-a-reward-trigger.mdx @@ -0,0 +1,10 @@ +--- +title: Get a reward trigger by ID +openapi: "/openapi/admin.json GET /rewards/{rewardId}/triggers/{id}" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/get-a-reward.mdx b/admin-api/endpoints/rewards/get-a-reward.mdx new file mode 100644 index 00000000..74f41ab0 --- /dev/null +++ b/admin-api/endpoints/rewards/get-a-reward.mdx @@ -0,0 +1,10 @@ +--- +title: Get a reward by ID +openapi: "/openapi/admin.json GET /rewards/{id}" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/list-reward-triggers.mdx b/admin-api/endpoints/rewards/list-reward-triggers.mdx new file mode 100644 index 00000000..12c5417a --- /dev/null +++ b/admin-api/endpoints/rewards/list-reward-triggers.mdx @@ -0,0 +1,10 @@ +--- +title: List reward triggers +openapi: "/openapi/admin.json GET /rewards/{rewardId}/triggers" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/list-rewards.mdx b/admin-api/endpoints/rewards/list-rewards.mdx new file mode 100644 index 00000000..f0e4b88b --- /dev/null +++ b/admin-api/endpoints/rewards/list-rewards.mdx @@ -0,0 +1,10 @@ +--- +title: List rewards +openapi: "/openapi/admin.json GET /rewards" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/update-reward-triggers.mdx b/admin-api/endpoints/rewards/update-reward-triggers.mdx new file mode 100644 index 00000000..ed360b95 --- /dev/null +++ b/admin-api/endpoints/rewards/update-reward-triggers.mdx @@ -0,0 +1,10 @@ +--- +title: Update reward triggers +openapi: "/openapi/admin.json PATCH /rewards/{rewardId}/triggers" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/admin-api/endpoints/rewards/update-rewards.mdx b/admin-api/endpoints/rewards/update-rewards.mdx new file mode 100644 index 00000000..7834b300 --- /dev/null +++ b/admin-api/endpoints/rewards/update-rewards.mdx @@ -0,0 +1,10 @@ +--- +title: Update rewards +openapi: "/openapi/admin.json PATCH /rewards" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/api-reference/endpoints/rewards/redeem-a-reward.mdx b/api-reference/endpoints/rewards/redeem-a-reward.mdx new file mode 100644 index 00000000..3b9e92d0 --- /dev/null +++ b/api-reference/endpoints/rewards/redeem-a-reward.mdx @@ -0,0 +1,10 @@ +--- +title: Redeem a reward +openapi: "/openapi/application.json POST /rewards/{key}/redeem" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/api-reference/endpoints/users/get-a-users-rewards.mdx b/api-reference/endpoints/users/get-a-users-rewards.mdx new file mode 100644 index 00000000..286742e3 --- /dev/null +++ b/api-reference/endpoints/users/get-a-users-rewards.mdx @@ -0,0 +1,10 @@ +--- +title: Get a user's rewards +openapi: "/openapi/application.json GET /users/{id}/rewards" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + \ No newline at end of file diff --git a/docs.json b/docs.json index b5036328..0b6cf1b5 100644 --- a/docs.json +++ b/docs.json @@ -96,6 +96,7 @@ "features/streaks", "features/points", "features/leaderboards", + "features/rewards", "features/emails", "features/push-notifications" ] @@ -197,6 +198,12 @@ "api-reference/endpoints/leaderboards/get-leaderboard" ] }, + { + "group": "Rewards", + "pages": [ + "api-reference/endpoints/rewards/redeem-a-reward" + ] + }, { "group": "Users", "pages": [ @@ -213,6 +220,7 @@ "api-reference/endpoints/users/get-a-users-points-boosts", "api-reference/endpoints/users/get-a-users-points-summary", "api-reference/endpoints/users/get-a-users-leaderboard", + "api-reference/endpoints/users/get-a-users-rewards", "api-reference/endpoints/users/get-a-users-wrapped", "api-reference/endpoints/users/get-user-preferences", "api-reference/endpoints/users/update-user-preferences" @@ -316,6 +324,21 @@ "admin-api/endpoints/leaderboards/delete-leaderboards" ] }, + { + "group": "Rewards", + "pages": [ + "admin-api/endpoints/rewards/list-rewards", + "admin-api/endpoints/rewards/get-a-reward", + "admin-api/endpoints/rewards/update-rewards", + "admin-api/endpoints/rewards/create-rewards", + "admin-api/endpoints/rewards/delete-rewards", + "admin-api/endpoints/rewards/list-reward-triggers", + "admin-api/endpoints/rewards/get-a-reward-trigger", + "admin-api/endpoints/rewards/update-reward-triggers", + "admin-api/endpoints/rewards/create-reward-triggers", + "admin-api/endpoints/rewards/delete-reward-triggers" + ] + }, { "group": "Tenants", "pages": [ @@ -391,6 +414,13 @@ "webhooks/events/leaderboards/leaderboard-finished" ] }, + { + "group": "Rewards", + "pages": [ + "webhooks/events/rewards/reward-awarded", + "webhooks/events/rewards/reward-redeemed" + ] + }, { "group": "Emails", "pages": [ diff --git a/features/achievements.mdx b/features/achievements.mdx index 7b5c079f..0344b0d3 100644 --- a/features/achievements.mdx +++ b/features/achievements.mdx @@ -403,6 +403,10 @@ If you have achievements set up for any of your [Metrics](/features/metrics), th +## Rewarding Achievements {#rewarding-achievements} + +To give users something when they unlock an achievement, like bonus points they claim or a prize you fulfill yourself, add an achievement trigger to a [reward](/features/rewards#achievement-triggers). If you just want points added automatically, use a [points trigger](/features/points#achievement-triggers) instead. + ## Get Support {#get-support} Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help! diff --git a/features/leaderboards.mdx b/features/leaderboards.mdx index 004b90bc..decd8fc9 100644 --- a/features/leaderboards.mdx +++ b/features/leaderboards.mdx @@ -425,6 +425,10 @@ This chart is a histogram of users' scores in a particular leaderboard. This is +## Rewarding Leaderboard Winners {#rewarding-leaderboard-winners} + +To give users something when they finish a leaderboard run at a particular rank, add a leaderboard trigger to a [reward](/features/rewards#leaderboard-triggers). Winners can then redeem the reward in your product. + ## Get Support {#get-support} Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help! diff --git a/features/overview.mdx b/features/overview.mdx index d6705c7c..ff63b9ab 100644 --- a/features/overview.mdx +++ b/features/overview.mdx @@ -35,7 +35,7 @@ Trophy's gamification concepts are flexible primitives built on the infrastructu Motivate users to build regular usage habits. - Reward users with sophisticated points systems. + Give users points for in-app interactions. Create friendly competitions to increase user engagement. + + Award users with redeemable points and custom rewards. + Deliver personalized lifecycle emails to users to increase retention. diff --git a/features/points.mdx b/features/points.mdx index 4ed5f064..5b5a8058 100644 --- a/features/points.mdx +++ b/features/points.mdx @@ -21,12 +21,16 @@ Points systems are used to create counters that track users' interactions with [ ## Use Cases {#use-cases} -### Rewards {#rewards} +### Automatic Rewards {#rewards} -Points systems can be used to create features like 'XP' or 'Gems' that reward users for a number of interactions at different rates. +Points systems can be used to create features like 'XP' or 'Gems' that automatically reward users for a number of interactions at different rates. Points are added to the user's balance as soon as a [points trigger](#points-triggers) fires. 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. + + Use a points trigger when points should be applied to a user's balance automatically. If users need to claim a reward before it's applied, or you want to hand out something other than points, use [Rewards](/features/rewards) instead. + + ### Metering {#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. @@ -80,6 +84,10 @@ In Trophy, points are awarded to or deducted from users through triggers. These 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. + + Points triggers add points to a user's balance automatically. If you need users to redeem points before they're applied, use a [points reward](/features/rewards#points-rewards) instead. Points granted by redeemed rewards still count towards the points system's balance, history and levels. + + ### Types of Triggers {#types-of-triggers} There are multiple types of triggers in Trophy that can be used to award or deduct points in different ways. diff --git a/features/rewards.mdx b/features/rewards.mdx new file mode 100644 index 00000000..c594f405 --- /dev/null +++ b/features/rewards.mdx @@ -0,0 +1,253 @@ +--- +title: Rewards +description: Learn how to use Rewards in a gamified product experience with Trophy. +og:description: Award users prizes, bonus points or custom perks when they hit + milestones, then let them redeem those rewards when they're ready. +icon: gift +--- + +import RedeemRewardRequest from "../snippets/redeem-reward-request-block.mdx"; +import RedeemRewardResponse from "../snippets/redeem-reward-response-block.mdx"; +import UserRewardsRequest from "../snippets/user-rewards-request-block.mdx"; +import UserRewardsResponse from "../snippets/user-rewards-response-block.mdx"; +import MetricEventRewardsResponseExcerpt from "../snippets/metric-event-rewards-response-excerpt-block.mdx"; +import WebhookRewardAwardedPayload from "../snippets/webhook-reward-awarded-payload-block.mdx"; +import WebhookRewardRedeemedPayload from "../snippets/webhook-reward-redeemed-payload-block.mdx"; +import AdminCreateRewardRequest from "../snippets/admin-create-reward-request-block.mdx"; +import AdminCreateRewardTriggerRequest from "../snippets/admin-create-reward-trigger-request-block.mdx"; + +## What are Rewards? {#what-are-rewards} + +Rewards let you give users something when they hit a milestone, and let them choose when to claim it. + +A reward is **awarded** automatically when a user meets one of its [triggers](#reward-triggers), for example unlocking an achievement or reaching a streak length. It is only **fulfilled** when it is **redeemed**, which you do by calling the [redeem endpoint](/api-reference/endpoints/rewards/redeem-a-reward) when the user claims it in your product. + +Awarding a reward never changes a user's points balance on its own. + +## Rewards or Points Triggers? {#rewards-or-points-triggers} + +Rewards and [points triggers](/features/points#points-triggers) can both give users points when something happens, but they work differently. + +| | Points triggers | Rewards | +| --- | --- | --- | +| Points are added to the user's balance | Automatically, as soon as the trigger fires | Only when the reward is redeemed | +| Needs a redemption step in your product | No | Yes | +| Can grant something other than points | No | Yes, with custom rewards | +| Webhooks | `points.changed` | `reward.awarded` and `reward.redeemed` | + + + If you want points to be applied to a user's balance automatically and don't need a redemption step, use a [points trigger](/features/points#points-triggers). Use rewards when users need to claim something, or when you need to fulfill it yourself. + + +## Use Cases {#use-cases} + +### Claimable bonuses {#claimable-bonuses} + +Award users bonus points for hitting a milestone, but let them tap a 'Claim' button in your product to receive them. The claim moment is a natural place for a celebration screen or animation. + +### Prizes and perks {#prizes-and-perks} + +Use custom rewards to hand out things that live outside Trophy, like a discount code, a free month or a physical prize. Trophy tells you when the reward is awarded and redeemed, and your system handles the rest. + +## Reward Types {#reward-types} + +### Points Rewards {#points-rewards} + +Points rewards grant a set number of points from a [points system](/features/points) when they are redeemed. + +Points are granted at the reward's points value at the time of redemption, and respect any [boosts](/features/points#points-boosts) and the points system's maximum. If the maximum would be exceeded part way through redeeming several awards, the awards that fit are redeemed and the rest stay unredeemed so they can be retried. + +### Custom Rewards {#custom-rewards} + +Custom rewards do nothing inside Trophy when they are redeemed apart from sending the `reward.redeemed` [webhook](#webhooks). Use them when you want to fulfill the reward yourself. + +## Creating Rewards {#creating-rewards} + +To create a reward, head to the [rewards page](https://app.trophy.so/rewards) and follow the steps below. + + + New rewards are created as 'Inactive' with no triggers so you can configure and test them before they go live. + + + + + Give the reward a name and a unique key. The key is what you'll use to reference the reward in APIs, and can't be changed after the reward is created. + + + Choose between a [points reward](#points-rewards) and a [custom reward](#custom-rewards). + + + For a points reward, choose the points system and the number of points to grant when the reward is redeemed. You can also add a description which is returned from APIs to be displayed in your application. + + + Limit how many times each user can be awarded the reward. See [redemption limits](#redemption-limits). + + + Restrict the reward to users with specific [custom user attributes](/features/users#custom-user-attributes). See [user filters](#user-filters). + + + Add one or more [triggers](#reward-triggers) and then change the reward's status to active to make it live. + + + +You can also create rewards and their triggers programmatically with the Admin API: + + + +## Reward Triggers {#reward-triggers} + +Rewards are awarded through triggers. You can add as many triggers as you like to a reward, and each can be activated and deactivated independently. + + + Triggers work independently of each other. Each active trigger can award the reward on its own, so a user does **not** need to meet all of a reward's triggers. For example, a reward with a streak trigger and an achievement trigger is awarded when the user reaches the streak length, and again when they complete the achievement. Any [redemption limit](#redemption-limits) applies across all of a reward's triggers combined. + + +### Types of Triggers {#types-of-triggers} + +#### Metric Triggers {#metric-triggers} + +The reward is awarded every time the user's total for a [metric](/features/metrics) grows by the threshold you set, for example "award every 10 tasks completed". Counting starts from when the trigger was activated. + +Activating the trigger again, or changing its metric, threshold or event attributes, starts a new count. + +#### Streak Triggers {#streak-triggers} + +The reward is awarded every time the user's current [streak](/features/streaks) grows by the streak length you set, for example "award every 7 days". The period the trigger was activated in counts as the first period, and changing the streak length starts a new count. + +A streak that ended before the trigger was activated, or broke after it, does not offset the count. + + + Streak triggers award repeatedly. Set a [redemption limit](#redemption-limits) of 1 to award the reward only once. + + +#### Achievement Triggers {#achievement-triggers} + +The reward is awarded once, when the user completes a specific [achievement](/features/achievements). Users who completed the achievement before the trigger existed are not awarded. + +#### Leaderboard Triggers {#leaderboard-triggers} + +The reward is awarded to the user who finishes a [leaderboard](/features/leaderboards) run at exactly the rank you set. For leaderboards with breakdown attributes, the user at that rank in each segment is awarded. + +### Creating Triggers {#creating-triggers} + +To add a trigger, open the reward from the [rewards page](https://app.trophy.so/rewards) and follow the steps below. + + + All new reward triggers are created as 'Inactive' to allow testing before deployment to production. A trigger's type can only be changed while it's inactive. + + + + + Choose a [trigger type](#types-of-triggers). + + + - For a **Metric** trigger, choose the metric and the threshold. + - For a **Streak** trigger, set the streak length. + - For an **Achievement** trigger, choose the achievement. + - For a **Leaderboard** trigger, choose the leaderboard and the rank. + + + - To limit a **Metric** trigger to events with specific [custom event attributes](/features/events#custom-event-attributes), add one or more filters in the **Event Attributes** section. When you set multiple event attribute filters, all of them must match. + - To limit any trigger to users with specific [custom user attributes](/features/users#custom-user-attributes), add attributes and the desired values in the **User Attributes** section. + + + Once you're happy the trigger will behave as expected, change its status to active to make it live. + + + +Triggers can also be added with the Admin API: + + + +### When Rewards Are Not Awarded {#when-rewards-are-not-awarded} + +Rewards are only awarded for things users do after a trigger is active. This means: + +- **Existing achievement completions don't award rewards.** If a user completed an achievement before you added an achievement trigger, they aren't awarded the reward. +- **Backdated achievements don't award rewards.** When you activate or edit an achievement, or set a user's `signUpDate`, Trophy [completes achievements for users who already qualify](/features/achievements#backdating-achievements). These silent completions don't award rewards. +- **Past progress doesn't count.** Metric and streak triggers count from when the trigger was activated, so progress users made before then isn't awarded. + +Inactive rewards and inactive triggers stop new awards, but existing awards can still be redeemed. Archived rewards are not awarded, listed or redeemed. + +## Redemption Limits {#redemption-limits} + +Set a redemption limit on a reward to cap how many times each user can be awarded it. Once a user reaches the limit they stop being awarded the reward. + +## User Filters {#user-filters} + +Add user attribute filters to a reward, or to individual triggers, to control who can be awarded. A user must match the reward's filters and the trigger's filters to be awarded. + +## Tracking a User's Rewards {#tracking-a-users-rewards} + +### Rewards Awarded by an Event {#rewards-awarded-by-an-event} + +When a [metric event](/api-reference/endpoints/events/submit-a-metric-event) or an [achievement completion](/api-reference/endpoints/achievements/mark-an-achievement-as-completed) awards a reward, the response includes it in the `rewards` array. This is the same shape as the response from the user rewards endpoint. Replaying an event with the same [idempotency key](/api-reference/idempotency) returns an empty array. + +Use this to show a "You earned a reward" message the moment it happens. + + + +Awards from other sources, such as leaderboard triggers when a run finishes, are not returned from API calls. Use the [`reward.awarded` webhook](#webhooks) or the user rewards endpoint to find them. + +### Listing a User's Rewards {#listing-a-users-rewards} + +Use the [user rewards endpoint](/api-reference/endpoints/users/get-a-users-rewards) to list the rewards a user has been awarded. Filter by `redeemed` to show only rewards waiting to be claimed, and by date range to page through history. + + + + + +Each award includes the trigger that earned it as it is configured now, with only the fields for its current type. + +## Redeeming Rewards {#redeeming-rewards} + +When a user claims a reward in your product, call the [redeem endpoint](/api-reference/endpoints/rewards/redeem-a-reward) with the reward's key and the user's ID. + + + +Trophy redeems all of the user's unredeemed awards for that reward at once, oldest first, and returns them in `redemptions`. For points rewards, the response also includes the combined `points` granted and any `leaderboards` the user's rank changed on. + + + +Redeeming still works for inactive rewards, but not for archived or deleted ones. The request returns an error when it can't redeem anything: + +- `404` if the user was never awarded the reward. +- `409` if every award has already been redeemed. + +If the points maximum is reached part way through, the awards that fit are redeemed and the rest stay unredeemed so you can retry later. + +## Webhooks {#webhooks} + +Trophy sends two [webhooks](/webhooks/introduction) for rewards: + +- [`reward.awarded`](/webhooks/events/rewards/reward-awarded) fires when a user is awarded a reward. Nothing has been applied yet. +- [`reward.redeemed`](/webhooks/events/rewards/reward-redeemed) fires when the reward is redeemed, once for each award. For custom rewards, this is your cue to fulfill the reward. + +Both include the reward, the redemption and the trigger that earned it. + + + + + +## Rewards and Points {#rewards-and-points} + +Points granted by redeeming a reward behave like any other points: + +- They show up in the user's points history and [points summary](/api-reference/endpoints/users/get-a-users-points-summary). +- They update [points leaderboards](/features/leaderboards) for that points system. +- They are not included in the `points` returned from metric events and achievement completions, since nothing is granted until redemption. + +## Rewards Analytics {#rewards-analytics} + +Each reward in the Trophy dashboard has built-in analytics including: + +- Awards over time +- Redemptions over time +- Awards broken down by trigger type +- For points rewards, an estimate of the points awarded and the points actually redeemed (including boosts and the points maximum) + +Filter by user attributes to compare how different groups of users engage with a reward. Points granted by rewards also appear as their own row in the points source chart. + +## Get Support {#get-support} + +Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help! diff --git a/features/streaks.mdx b/features/streaks.mdx index 7ec2608e..2fefcc7e 100644 --- a/features/streaks.mdx +++ b/features/streaks.mdx @@ -332,6 +332,10 @@ If you want to display streaks for multiple users at once, for example to suppor ] ``` +## Rewarding Streaks {#rewarding-streaks} + +To give users something when they reach a streak length, like bonus points they claim or a prize you fulfill yourself, add a streak trigger to a [reward](/features/rewards#streak-triggers). If you just want points added automatically, use a [points trigger](/features/points#streak-triggers) instead. + ## Get Support {#get-support} Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help! diff --git a/getting-started/introduction.mdx b/getting-started/introduction.mdx index 1b2f02ab..2635a899 100644 --- a/getting-started/introduction.mdx +++ b/getting-started/introduction.mdx @@ -61,7 +61,8 @@ All gamification features are powered by [metric events](/features/events). Here The response includes changes to gamification state as a result of the event including: - The user's new total value for the metric - Any newly unlocked achievements -- New points totals and rewards +- New points totals +- Any rewards awarded - An updated streak object - Any new leaderboard positions diff --git a/guides/how-to-build-an-xp-feature.mdx b/guides/how-to-build-an-xp-feature.mdx index 96c26c60..f76da604 100644 --- a/guides/how-to-build-an-xp-feature.mdx +++ b/guides/how-to-build-an-xp-feature.mdx @@ -62,6 +62,10 @@ Once you've created your metric, head to the [points page](https://app.trophy.so Once created, you'll be taken to the configure page for the XP system where you can create 'triggers' for each of the ways you want to reward users with XP. + + Points triggers add XP to a user's balance automatically. If you want users to claim XP before it's applied, use a [points reward](/features/rewards#points-rewards) instead. + + -Pulsa _Invitar_ y añade la dirección de correo electrónico de los miembros del equipo que deseas invitar. Si eres administrador de la cuenta, puedes añadir otros administradores; de lo contrario, solo podrás añadir otros miembros. +Haz clic en _Invitar_ y añade la dirección de correo electrónico de los miembros del equipo que deseas invitar. Si eres administrador de la cuenta, puedes añadir otros administradores; de lo contrario, solo podrás añadir otros miembros. -Cuando estés conforme, pulsa _Enviar invitaciones_ y cada miembro del equipo recibirá una invitación por correo electrónico a Trophy. +Cuando estés conforme, haz clic en _Enviar invitaciones_ y cada miembro del equipo recibirá una invitación por correo electrónico a Trophy. ## Gestionar roles de usuario {#manage-user-roles} diff --git a/es/features/metrics.mdx b/es/features/metrics.mdx index 22140a3d..88090c35 100644 --- a/es/features/metrics.mdx +++ b/es/features/metrics.mdx @@ -39,7 +39,7 @@ Puedes asignar fácilmente unidades a las métricas en el panel para: ## Crear Métricas {#creating-metrics} -Para crear una métrica, dirígete a la página de [Métricas](https://app.trophy.so/metrics) dentro de Trophy y presiona el botón **Nueva Métrica**: +Para crear una métrica, dirígete a la página de [Métricas](https://app.trophy.so/metrics) dentro de Trophy y haz clic en el botón **Nueva Métrica**: