Skip to main content
The guide outlines the full process of adding a streaks feature to your web or mobile app using Trophy. For illustration purposes we’ll use the example of a study platform that uses a daily streak to incentivize and reward users for viewing flashcards.
To see a fully working example of this in practice, check out the live demo or github repo.

​
Pre-requisites

  • A Trophy account
  • About 10 minutes

​
Trophy Setup

In Trophy, Metrics are the building blocks of gamification and model the different interactions users make with your product. In this guide the interaction we’re interested in is flashcards-viewed, but you can create a metric that best represents the interaction you want to drive streaks from. In the Trophy dashboard, head to the metrics page and create a metric.
Once you’ve created your metric, head to the streaks page and select the streak frequency you want (daily, weekly or monthly). Then select the metric you created in the dropdown. In Trophy you track user interactions by sending Events from your code to Trophy APIs against a specific metric. When events are recorded for a specific user, Trophy will automatically check if the event is against a metric that is selected in your streak settings and update the user’s streak accordingly. This is what makes building gamified experiences with Trophy so easy, it does all the work for you behind the scenes.

​
Installing Trophy SDK

To interact with Trophy from your code you’ll use the Trophy SDK available in most major programming languages. Install the Trophy SDK: 
npm install @trophyso/node
Next, grab your API key from the Trophy integration page and add this as a server-side only environment variable. 
TROPHY_API_KEY='*******'
Make sure you don’t expose your API key in client-side code.

​
Tracking User Interactions

To track an event (user interaction) against your metric, use the metric change API. 
curl -X POST https://app.trophy.so/api/metrics/flashcards-flipped/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 750
}'
By including the user’s timezone in the tz attribute, Trophy will automatically track streaks according to the user’s local clock and handle awkward edge cases where users change time zones.
The response to this API call is the complete set of changes to any features you’ve built with Trophy, including the latest data on the users streak.
Response
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  ...,
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  },
  ...
}
Validate this is working by checking the Trophy dashboard.

​
Displaying Streaks

You have a number of options for displaying streaks in your application. Here we’ll look at the most common options.

​
Pop-up Notifications

We can use the response of the metric change API to show pop-up notifications (or ‘toasts’) when user extends their streak. Here’s an example of this in action:
Streak Extended Pop-up
// Sends event to Trophy
const response = await viewFlashcard();

if (!response) {
  return;
}

// Show toast if user has extended their streak
if (response.currentStreak?.extended) {
  toast({
    title: "You're on a roll!",
    description: `Keep going to keep your ${response.currentStreak.length} day streak!`,
  });
}
If you want to play sound effects, use the HTML5 Audio API and feel free to steal these audio files we recommend.

​
Displaying User Streaks

To fetch data on a user’s streak use the user streak API. 
curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/streak \
  --header 'X-API-KEY: <api-key>'
This API not only returns data on the user’s current streak like length and expires, but it can also return historical streak data which can be used to display any kind of streak UI you like through the historyPeriods parameter.
Response
{
  "length": 1,
  "frequency": "weekly",
  "started": "2025-04-02",
  "periodStart": "2025-03-31",
  "periodEnd": "2025-04-05",
  "expires": "2025-04-12",
  "streakHistory": [
    {
      "periodStart": "2025-03-30",
      "periodEnd": "2025-04-05",
      "length": 1
    },
    {
      "periodStart": "2025-04-06",
      "periodEnd": "2025-04-12",
      "length": 2
    },
    {
      "periodStart": "2025-04-13",
      "periodEnd": "2025-04-19",
      "length": 3
    },
    {
      "periodStart": "2025-04-20",
      "periodEnd": "2025-04-26",
      "length": 0
    },
    {
      "periodStart": "2025-04-27",
      "periodEnd": "2025-05-03",
      "length": 1
    },
    {
      "periodStart": "2025-05-04",
      "periodEnd": "2025-05-10",
      "length": 2
    },
    {
      "periodStart": "2025-05-11",
      "periodEnd": "2025-05-17",
      "length": 3
    }
  ]
}
Here’s an example of a git-style streak calendar built using the data in the response above:
Check this example repo for a React component that drives this UI using data from Trophy.

​
Analytics

The streaks page in Trophy shows data on active streaks, the average length of streaks and longest streaks.

​
Streak Freezes

Trophy also supports streak freezes which can help prevent users from losing their streak if they accidentally miss a period. Learn more about streak freezes in the dedicated streak freezes docs.

​
Get Support

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