How To Build A Streaks Feature

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 add your metric to the streak conditions and set the threshold users must meet (e.g. at least 1 to extend their streak each period). You can also add multiple metrics and choose whether users must meet all of them or just one—see the streak conditions docs for details. 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 whether they’ve met their streak conditions for the current period 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

gem install trophy_api_client

pip install trophy

composer require trophyso/php

implementation 'so.trophy:trophy-java:1.0.0'

<dependency>
  <groupId>so.trophy</groupId>
  <artifactId>trophy-java</artifactId>
  <version>1.0.0</version>
</dependency>

go get github.com/trophy-so/trophy-go

// .NET Core CLI
dotnet add package Trophy

// Nuget Package Manager
nuget install Trophy

// Visual Studio
Install-Package Trophy

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
}'

trophy.metrics.event("flashcards-flipped", {
  user: {
    id: "18",
    email: "user@example.com",
    tz: "Europe/London",
  },
  value: 750,
});

client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=750.0,
)

$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com'
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 750
]);

$trophy->metrics->event("flashcards-flipped", $request);

MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .build()
      )
      .value(750)
      .build();

EventResponse response = client.metrics().event("flashcards-flipped", request);

response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
        },
        Value: 750,
    },
)

var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com"
};

var request = new MetricsEventRequest {
   User = user,
   Value = 750
};

await trophy.Metrics.EventAsync("flashcards-flipped", request);

result = client.metrics.event(
  :key => 'flashcards-flipped',
  :user => {
    :id => '18',
    :email => 'user@example.com'
  },
  :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>'

trophy.users.streak("user-id", {
  historyPeriods: 14
});

client.users.streak(
    id="user-id",
    history_periods=14,
)

$request = new UsersStreakRequest([
    'history_periods' => 14
]);

$trophy->users->streak("user-id", $request);

UsersStreakRequest request = UsersStreakRequest.builder()
      .historyPeriods(14)
      .build();

UsersStreakResponse response = client.users().streak("user-id", request);

response, err := client.Users.Streak(
    "user-id",
    &api.UsersStreakRequest{
        HistoryPeriods: 14,
    },
)

var request = new UsersStreakRequest {
   HistoryPeriods = 14
};

await trophy.Users.StreaksAsync("user-id", request);

result = client.users.streak(
  :id => 'user-id',
  :history_periods => 14
)

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!

Feature Guides

Use Cases

How To Build A Streaks Feature

Pre-requisites

Trophy Setup

Installing Trophy SDK

Tracking User Interactions

Displaying Streaks

Pop-up Notifications

Displaying User Streaks

Analytics

Streak Freezes

Get Support

​Pre-requisites

​Trophy Setup

​Installing Trophy SDK

​Tracking User Interactions

​Displaying Streaks

​Pop-up Notifications

​Displaying User Streaks

​Analytics

​Streak Freezes

​Get Support

Pre-requisites

Trophy Setup

Installing Trophy SDK

Tracking User Interactions

Displaying Streaks

Pop-up Notifications

Displaying User Streaks

Analytics

Streak Freezes

Get Support