Skip to main content
The guide outlines the full process of adding an achievements feature to your web or mobile app using Trophy. For illustration purposes we’ll use the example of a study platform that uses achievements 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 build achievements around. In the Trophy dashboard, head to the metrics page and create a metric.
Once you’ve created your metric, head to the achievements page and create the achievements you want. You can find all the details on the types of achievements and the different use cases in the achievements docs. For the purposes of this guide we’ve set up a couple of achievements based on an increasing number of flashcards flipped:
  • 10 flashcards
  • 50 flashcards
  • 100 flashcards
  • 250 flashcards
  • 1,000 flashcards
We’ve also set up a few achievements related to Streaks, but we won’t go into detail on these in this guide.
For a full guide on adding a streaks feature to your web or mobile app, check out our full guide.
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, any achievements linked to the specified metric will be completed automatically if the requirements are met. 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
}'
The response to this API call is the complete set of changes to any features you’ve built with Trophy, including any achievements that were unlocked as a result of the event.
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"
    }
  ],
  ...
}
Validate this is working by checking the Trophy dashboard.

​
Displaying Achievements

You have a number of options for displaying achievements 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 users complete achievements. Here’s an example of this in action:
Achievement Completed Pop-up
// Sends event to Trophy
const response = await viewFlashcard();

if (!response) {
  return;
}

// Show toasts if the user has unlocked any new achievements
response.achievements.forEach((achievement) => {
  toast({
    title: achievement.name,
    description: achievement.description,
    image: {
      src: achievement.badgeUrl,
      alt: achievement.name,
    },
  });
});
If you want to play sound effects, use the HTML5 Audio API and feel free to steal these audio files we recommend.

​
Displaying User Achievements

To fetch all achievements a user has completed, use the user achievements API. 
curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/achievements \
  --header 'X-API-KEY: <api-key>'
You can also fetch incomplete achievements at the same time by passing includeIncomplete as 'true'.

​
Displaying All Achievements

If instead you want to display all achievements you’ve set up in Trophy as part of a globally accessible UI that isn’t linked to a particular user, you can use the all achievements API. 
curl --request GET \
  --url https://api.trophy.so/v1/achievements \
  --header 'X-API-KEY: <api-key>'

​
Achievement Completion Stats

Both the user achievements API and the all achievements API include completion statistics like completions (the number of users that have completed an achievement) and rarity (the percentage of users that have completed an achievement).

​
Analytics

The achievements page in Trophy shows how many users have completed each achievement you’ve set up.
Additionally the analytics page on any metric in Trophy includes a chart that shows the progress of users through your achievements.

​
Get Support

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