Quick Start

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

Using AI
Manual

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

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.

Configure MCP servers

For the best AI setup experience, connect Trophy through MCP:

Docs MCP server URL: https://docs.trophy.so/mcp (live documentation context)
Account MCP server URL: https://mcp.trophy.so (account actions — see MCP; requires x-trophy-api-key)

Use the Docs MCP as on-demand docs context and the Account MCP for account changes. Use both for best practice.

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

Open in Cursor

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

This will:

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

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.

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

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

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

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.

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!

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

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

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:

import { TrophyApiClient } from "@trophyso/node";

const trophy = new TrophyApiClient({
  apiKey: process.env.TROPHY_API_KEY as string,
});

client = TrophyApiClient::Client.new(
  :api_key => ENV["TROPHY_API_KEY"]
)

from trophy import Trophy

client = Trophy(
    api_key=os.environ.get("TROPHY_API_KEY"),
)

use Trophy\TrophyClient;

$trophy = new TrophyClient([
    'apiKey' => getenv('TROPHY_API_KEY')
]);

TrophyApiClient client = TrophyApiClient.builder()
    .apiKey(System.getenv("TROPHY_API_KEY"))
    .build();

TrophyApiClient client = TrophyApiClient.builder()
    .apiKey(System.getenv("TROPHY_API_KEY"))
    .build();

client, err := trophy.NewClient(
    option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
)

var trophy = new TrophyClient(
    Environment.GetEnvironmentVariable("TROPHY_API_KEY")
);

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

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.

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

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.

Get Support

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

Getting Started

Features

Platform

Account

Achievements

Streaks

Points

Leaderboards

Emails

Push Notifications

Achievements

Streaks

Points

Leaderboards

Emails

Push Notifications

Get Support

Achievements

Streaks

Points

Leaderboards

Emails

Push Notifications

Achievements

Streaks

Points

Leaderboards

Emails

Push Notifications

​Get Support

Get Support