Skip to main content

​
What is a Points System?

Points systems are used to create counters that track users’ interactions with Metrics, Achievements and 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 and follow the steps below.
1

Hit New Points System

Give the new points system a name, and a unique key. The key is what you’ll use to reference the points system in APIs and in email templates if relevant.
2

Add a description (Optional)

You can also give the points system a description which is returned from APIs to be displayed in your application.
3

Configure max points (Optional)

If you want to limit the number of points that each user can have in your new system, set a value in the ‘max points’ field.
Any points triggers that you configure against this points system will respect the maximum set.
4

Assign a badge (Optional)

You can also optionally upload a badge or logo to represent the points system. A src friendly URL to the image is returned from APIs for display in your application.

​
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. 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, for example “award 50 points for every 7 days streak”. Achievement Triggers Points can be awarded or deducted when users unlock specific 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.
All new points triggers are created as ‘Inactive’ to allow testing and balancing before deployment to production.
1

Choose a trigger type

Choose how you want points to be awarded or deducted as described by the available trigger types.
2

Set up trigger

Once you’ve chosen the points trigger type, you need to set up the trigger settings.
  • If you chose the Metric trigger, you’ll need to choose the metric and the threshold amount at which to award or deduct points.
  • If you chose the Streak trigger, you’ll need to set the streak length that should award or deduct points.
  • If you chose the Achievement trigger, you’ll need to choose the achievement that should award or deduct points when completed.
  • If you chose the Time trigger, you’ll need to choose the time unit you want to award or deduct points on (hours or days) and the number of those time units that you want to award or deduct points after.
  • If you chose the First User Identification trigger, you won’t need to add any additional configuration.
3

Set points to award/deduct

Once your trigger is configured, set the number of points to award or deduct when fired.
4

Add attribute filters (Optional)

You can assign attribute filters to a points trigger to further restrict when they apply.
  • To limit a Metric trigger to only apply to events with specific custom event attributes, select an attribute and enter a value in the Event Attribute section.
  • To limit any type of trigger to only apply to a user with one or more specific custom user attributes, add attributes and the desired values in the User Attributes section.
5

Hit save

Save the new points trigger.
6

Activate

Once you’re happy that your new trigger will behave as expected, change its status to active to make it live.

​
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.

​
Displaying Points

There are a few ways to use Trophy to fetch and display points in your app.
Check out our guides on adding an XP feature or an energy feature to your web or mobile 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. 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.
Response
{
  "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",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "total": 10,
      "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 effects

​
Displaying User’s Points

Trophy also has APIs that allow you fetch user’s points data whenever you want. First, the user points API 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. 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.
Then, the user points summary API can be used to fetch historical points data for a particular user. Data can be aggregated daily, weekly or monthly between a start and end date. Use this API to display points progress charts to users over any time frame.

​
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 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.
This API can also be filtered to only return data for users with specific custom user attributes.
Finally, the points system API returns data about a particular points system, including all its triggers that award points to or deduct points from users. Use this API to show users how they can earn points on your platform. Any new triggers you add will automatically be returned from this API helping to reduce code changes in your platform, and shifting operations to Trophy.

​
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 triggers

​
Get Support

Want to get in touch with the Trophy team? Reach out to us via email. We’re here to help!