Quick Start

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

Using AI
Manual

These instructions are for using Trophy with AI assistants that support MCP — for example Claude, ChatGPT, Cursor, or Claude Code.

Create your Trophy account

First, create a new account if you don’t have one already. Complete onboarding to get your account set up.

Connect Trophy MCP servers

Connect both Trophy MCP servers in your AI client for the best experience:

Docs MCP server URL: https://docs.trophy.so/mcp (live documentation context)
Account MCP server URL: https://mcp.trophy.so/mcp (account actions — OAuth sign-in required)

Setup guides: Docs MCP installation, Account MCP installation.

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

Ask your AI to perform initial setup

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

Perform initial Trophy setup

Open in Cursor

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 track metric events for the chosen user activity using the Trophy SDK client - required for all gamification features.

Build your first gamification feature

Once initial setup is complete, pick a common use case and paste the matching prompt into your AI assistant:

Daily streak

Achievements library

XP system

Weekly leaderboard

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

These instructions are for those who want to implement Trophy by hand. If instead you prefer to use AI, 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