Quick Start

Get up and running with Trophy in under 10 minutes

Here you’ll integrate your backend web application with Trophy and start building your first gamified feature.

I'm doing this myself

These instructions are for those who want to implement Trophy by hand. If instead you prefer to use coding agents, switch tabs above.

1. Create your Trophy account

   First, create a new account if you don’t already have one and head into the Trophy dashboard.

   Head through onboarding to get your account set up.

2. Add the Trophy SDK to your backend

   We have SDK libraries available in most major programming languages but if you don’t see yours listed, let us know and we’ll make one!

   Node

   npm install @trophyso/node
   

   Alternatively, you can directly call the API using any server-side HTTP client.

3. Set up environment

   Head to the integration page of the Trophy dashboard and create a new API key.

   Add your API key as an environment variable in your backend application:

   TROPHY_API_KEY='*******'
   

   Then initialize the Trophy API client in your backend using that API key:

   Node

   import { TrophyApiClient } from "@trophyso/node";
   
   const trophy = new TrophyApiClient({
     apiKey: process.env.TROPHY_API_KEY as string,
   });
   

   Make sure all Trophy SDK calls use this client for authentication.

4. Create your first metric

   All gamification features are driven by user interactions. In Trophy, you use Metrics to define and model those interactions and Events to track them.

   Here you’ll create your first metric to get started. In the Trophy dashboard, head into the metrics page and hit the New Metric button:

   Give the metric a name and hit Save.

5. Integrate the metric into your backend

   Once you’ve created your metric, head to the configure tab and copy it’s unique API reference key.

   To track an event against this metric when a user interacts with your product, call the metric change event API, passing along details of the user that made the interaction. In this example the metric key would be flashcards-flipped:

   cURL

   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": "[e-mail]",
       "tz": "Europe/London"
     },
     "value": 750
   }'
   

   By making this call, you’re telling Trophy that a specific user made an interaction with your product. As a result, Trophy will process any gamification features like achievements or streaks that you’ve configured against the metric automatically.

6. Continue building your gamification experience

   With a metric integrated into your backend, you’re ready to start adding gamification features to your product.

   Follow the links below to learn more about each feature you can build with Trophy:

   Achievements

   Reward users for continued progress or taking specific actions.

   Streaks

   Motivate users to build regular usage habits.

   Points

   Build sophisticated points systems to reward and retain users.

   Leaderboards

   Create friendly competitions to increase user engagement.

   Emails

   Deliver personalized lifecycle emails to users at the perfect moment.

   Push Notifications

   Drive automated notification flows using personalized gamification data.

   Or, explore our API reference to get familiar with what Trophy can do.

I'm using AI

These instructions are for those who prefer to develop using coding agents like Cursor and Claude Code.

1. Create your Trophy account

   First, create a new account if you don’t already have one and head into the Trophy dashboard.

   Head through onboarding to get your account set up.

2. Configure Trophy MCP or Agent Skill

   For the best AI setup experience, connect Trophy through MCP, Agent Skill, or both:

   • MCP server URL: https://docs.trophy.so/mcp
   • Agent skill URL: https://docs.trophy.so/skill.md

   MCP gives your agent live access to Trophy docs. Agent Skill gives it structured instructions about Trophy capabilities. Using both usually gives the best results.

   Claude

   1. Open Claude Connectors.
   2. Select Add custom connector.
   3. Add:
      • Name: Trophy
      • URL: https://docs.trophy.so/mcp
   4. In chat, use the plus button to enable the Trophy connector.
   5. Optional but recommended: add Trophy Agent Skill in Claude Skills settings using https://docs.trophy.so/skill.md so Claude consistently uses Trophy’s capability summary.

   Claude Code

   Add Trophy MCP:

   claude mcp add --transport http Trophy https://docs.trophy.so/mcp
   

   Verify:

   claude mcp list
   

   Optional: add Trophy Agent Skill:

   npx skills add https://docs.trophy.so
   

   Cursor

   Open MCP settings and add this to your mcp.json:

   {
     "mcpServers": {
       "Trophy": {
         "url": "https://docs.trophy.so/mcp"
       }
     }
   }
   

   Optional: add Trophy Agent Skill:

   npx skills add https://docs.trophy.so
   

   VS Code

   Create .vscode/mcp.json:

   {
     "servers": {
       "Trophy": {
         "type": "http",
         "url": "https://docs.trophy.so/mcp"
       }
     }
   }
   

   Optional: add Trophy Agent Skill:

   npx skills add https://docs.trophy.so
   
3. Tell your agent to perform initial setup

   Here’s a prompt you can use with your coding agent to perform initial Trophy setup:

   Perform initial Trophy setup

   CopiedCopy promptOpen in Cursor

   Make sure to replace <metric> with the metric you set up during onboarding.

   This will:

   1. Add the relevant Trophy SDK to your app based on your tech stack
   2. Add a new TROPHY_API_KEY variable to your environment settings
   3. Add code to send events to Trophy based on the metric you set up during onboarding.
4. Grab your API key

   Once the set up is complete, create an API key from the integration page of the Trophy dashboard and add it to your environment.

5. Build your first gamification feature

   Once initial setup is complete, use this follow-up prompt to prepare your agent for the next step and have it ask you what to build next:

   Build your first gamification feature

   CopiedCopy promptOpen in Cursor

   For ideas on what to build next, explore:

   Achievements

   Reward users for continued progress or taking specific actions.

   Streaks

   Motivate users to build regular usage habits.

   Points

   Build sophisticated points systems to reward and retain users.

   Leaderboards

   Create friendly competitions to increase user engagement.

   Emails

   Deliver personalized lifecycle emails to users at the perfect moment.

   Push Notifications

   Drive automated notification flows using personalized gamification data.

   Or, explore our API reference to get familiar with what Trophy can do.

Get Support

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