> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Install a Trophy SDK, authenticate, identify a user, and send your first metric event in about five minutes.

Here you'll integrate your application with Trophy and send your first metric event in about five minutes. Everything in Trophy is powered by the user activity you send as events, so this is the first step whatever you're building.

> [tab] Using AI
>
> These instructions are for using Trophy with AI assistants that support MCP — for example Claude, ChatGPT, Cursor, or Claude Code.
>
> **1. Create your Trophy account**
>
> First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs\&utm_medium=quickstart) if you don't have one already. Complete onboarding to get your account set up.
>
> **2. 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](/mcp/docs-mcp-server/installation.md), [Account MCP installation](/mcp/account-mcp-server/installation.md).
>
> > [!TIP]
> >
> > Use the [Docs MCP](/mcp/docs-mcp-server/introduction.md) as on-demand docs context and the [Account MCP](/mcp/account-mcp-server/introduction.md) for account changes. Use both for [best practice](/mcp/best-practice.md).
>
> **3. 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
>
> I'm integrating Trophy into my app.
>
> Before making changes, verify the connected Trophy MCP Servers are available. Use the Docs MCP server as the primary source of truth for Trophy integration details, and the Account MCP server to configure my account.
>
> Please do the full initial setup end-to-end:
>
> 1. Detect the backend language/framework in this repo and install the relevant official Trophy SDK (or use HTTP calls if no SDK is available). Report to Trophy support if no SDK is available.
> 2. Add `TROPHY_API_KEY` to environment config in a secure way (no secrets committed to git), and wire it into the Trophy SDK client initialization.
> 3. Add code to set up metric event tracking for the chosen user activity (ask if not known yet) using the Trophy SDK client, wiring all required user attributes like ID, and using placeholders for all optional attributes like name, email, tz and signUpDate, unless already known or required by the use case.
> 4. Add basic error handling and logging around Trophy SDK calls.
> 5. Add or update a short README section explaining how the integration works and how to extend it.
>
> Constraints:
>
> * Use Docs MCP tool results for all Trophy-specific implementation decisions and integrations.
> * Do not rely on prior memory for Trophy SDK behavior when MCP provides an answer.
> * Keep secrets out of source control.
> * Use existing project patterns and naming conventions.
> * Show a concise summary of changed files and how to test the setup.
> * Suggest next steps based on my use case: agentic messaging, in-app features, or both.
>
> This will:
>
> 1. Add the relevant [Trophy SDK](/api-reference/client-libraries.md) to your app based on your tech stack
> 2. Add a new `TROPHY_API_KEY` variable to your environment settings
> 3. Add code to track metric events for the chosen user activity using the Trophy SDK client - required for all Trophy features.
>
> Once your first event is sent, see [next steps](#next-steps) to choose what to build.

> [tab] Manual
>
> These instructions are for those who want to implement Trophy by hand. If instead you prefer to use AI, switch tabs above.
>
> **1. Create your Trophy account**
>
> First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs\&utm_medium=quickstart) if you don't already have one and head into the [Trophy dashboard](https://app.trophy.so).
>
> 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!
>
> ```bash Node theme={null}
> npm install @trophyso/node
> ```
>
> ```bash Ruby theme={null}
> gem install trophy_api_client
> ```
>
> ```bash Python theme={null}
> pip install trophy
> ```
>
> ```bash PHP theme={null}
> composer require trophyso/php
> ```
>
> ```bash Java (Gradle) theme={null}
> implementation 'so.trophy:trophy-java:1.0.0'
> ```
>
> ```bash Java (Maven) theme={null}
> <dependency>
>   <groupId>so.trophy</groupId>
>   <artifactId>trophy-java</artifactId>
>   <version>1.0.0</version>
> </dependency>
> ```
>
> ```bash Go theme={null}
> go get github.com/trophy-so/trophy-go
> ```
>
> ```bash .NET (C#) theme={null}
> // .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.
>
> **3. Set up environment**
>
> Head to the [integration page](https://app.trophy.so/integration) of the Trophy dashboard and create a new API key.
>
> Add your API key as an environment variable in your backend application:
>
> ```bash theme={null}
> TROPHY_API_KEY='*******'
> ```
>
> Then initialize the Trophy API client in your backend using that API key:
>
> ```typescript Node theme={null}
> import { TrophyApiClient } from "@trophyso/node";
>
> const trophy = new TrophyApiClient({
>   apiKey: process.env.TROPHY_API_KEY as string,
> });
> ```
>
> ```ruby Ruby theme={null}
> client = TrophyApiClient::Client.new(
>   :api_key => ENV["TROPHY_API_KEY"]
> )
> ```
>
> ```python Python theme={null}
> from trophy import Trophy
>
> client = Trophy(
>     api_key=os.environ.get("TROPHY_API_KEY"),
> )
> ```
>
> ```php PHP theme={null}
> use Trophy\TrophyClient;
>
> $trophy = new TrophyClient([
>     'apiKey' => getenv('TROPHY_API_KEY')
> ]);
> ```
>
> ```java Java (Gradle) theme={null}
> TrophyApiClient client = TrophyApiClient.builder()
>     .apiKey(System.getenv("TROPHY_API_KEY"))
>     .build();
> ```
>
> ```java Java (Maven) theme={null}
> TrophyApiClient client = TrophyApiClient.builder()
>     .apiKey(System.getenv("TROPHY_API_KEY"))
>     .build();
> ```
>
> ```go Go theme={null}
> client, err := trophy.NewClient(
>     option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
> )
> ```
>
> ```csharp .NET (C#) theme={null}
> var trophy = new TrophyClient(
>     Environment.GetEnvironmentVariable("TROPHY_API_KEY")
> );
> ```
>
> Make sure all Trophy SDK calls use this client for authentication.
>
> **4. Create your first metric**
>
> Everything in Trophy is driven by user interactions. In Trophy, you use [Metrics](/features/metrics.md) to define and model those interactions and [Events](/features/events.md) to track them.
>
> Here you'll create your first metric to get started. In the Trophy dashboard, head into the [metrics page](https://app.trophy.so/metrics) and click the *New Metric* button:
>
> <video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/jV5zFWvq5WvABxJP/assets/features/metrics/create_new_metric.mp4?fit=max&auto=format&n=jV5zFWvq5WvABxJP&q=85&s=00fea4dc1abfe966da5799a8c72ee98f" />
>
> Give the metric a name and click *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.
>
> <video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-cep/c4lcu5R4FPc7k25i/assets/quick-start/copy_metric_key.mp4?fit=max&auto=format&n=c4lcu5R4FPc7k25i&q=85&s=4a6a602dc10afa6c7d6f90f947345342" />
>
> To track an event against this metric when a user interacts with your product, call the [metric change event API](/api-reference/endpoints/events/submit-a-metric-event.md), passing along details of the user that made the interaction. In this example the metric key would be `flashcards-flipped`:
>
> ```bash cURL theme={null}
> curl -X POST https://api.trophy.so/v1/metrics/flashcards-flipped/event \
>      -H "X-API-KEY: $TROPHY_API_KEY" \
>      -H "Idempotency-Key: flashcard-view-42" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "user": {
>     "id": "18",
>     "email": "user@example.com",
>     "tz": "Europe/London"
>   },
>   "value": 1
> }'
> ```
>
> ```typescript Node theme={null}
> import { TrophyApiClient } from "@trophyso/node";
> import type { EventResponse } from "@trophyso/node/api";
>
> const trophy = new TrophyApiClient({
>   apiKey: process.env.TROPHY_API_KEY as string,
> });
>
> // user.id is required. email and tz are optional but recommended
> // (tz is required for correct streak calendar days).
> const response: EventResponse = await trophy.metrics.event(
>   "flashcards-flipped",
>   {
>     user: {
>       id: "18",
>       email: "user@example.com",
>       tz: "Europe/London",
>     },
>     value: 1,
>     // Protects against duplicate events from the same flashcard
>     idempotencyKey: "flashcard-view-42",
>   }
> );
> ```
>
> ```python Python theme={null}
> from trophy import Trophy
> from trophy.types import EventRequestUser
>
> client = Trophy(
>     api_key=os.environ.get("TROPHY_API_KEY"),
> )
>
> # user.id is required. email and tz are optional but recommended
> # (tz is required for correct streak calendar days).
> response = client.metrics.event(
>     key="flashcards-flipped",
>     user=EventRequestUser(
>         id="18",
>         email="user@example.com",
>         tz="Europe/London",
>     ),
>     value=1.0,
>     idempotencyKey="flashcard-view-42", # Protects against duplicate events from the same flashcard
> )
> ```
>
> ```php PHP theme={null}
> use Trophy\TrophyClient;
> use Trophy\Types\EventRequestUser;
> use Trophy\Types\MetricsEventRequest;
>
> $trophy = new TrophyClient([
>     'apiKey' => getenv('TROPHY_API_KEY')
> ]);
>
> // user.id is required. email and tz are optional but recommended
> // (tz is required for correct streak calendar days).
> $user = new EventRequestUser([
>     'id' => '18',
>     'email' => 'user@example.com',
>     'tz' => 'Europe/London',
> ]);
>
> $request = new MetricsEventRequest([
>     'user' => $user,
>     'value' => 1,
>     // Protects against duplicate events from the same flashcard
>     'idempotencyKey' => 'flashcard-view-42',
> ]);
>
> $response = $trophy->metrics->event("flashcards-flipped", $request);
> ```
>
> ```java Java theme={null}
> TrophyApiClient client = TrophyApiClient.builder()
>     .apiKey(System.getenv("TROPHY_API_KEY"))
>     .build();
>
> // user.id is required. email and tz are optional but recommended
> // (tz is required for correct streak calendar days).
> MetricsEventRequest request = MetricsEventRequest.builder()
>       .user(
>         EventRequestUser.builder()
>           .id("18")
>           .email("user@example.com")
>           .tz("Europe/London")
>           .build()
>       )
>       .value(1)
>       // Protects against duplicate events from the same flashcard
>       .idempotencyKey("flashcard-view-42")
>       .build();
>
> EventResponse response = client.metrics().event("flashcards-flipped", request);
> ```
>
> ```go Go theme={null}
> client, err := trophy.NewClient(
>     option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
> )
> if err != nil {
>     log.Fatal(err)
> }
>
> // user.id is required. email and tz are optional but recommended
> // (tz is required for correct streak calendar days).
> response, err := client.Metrics.Event(
>     "flashcards-flipped",
>     &api.MetricsEventRequest{
>         User: &api.EventRequestUser{
>             Id: "18",
>             Email: "user@example.com",
>             Tz: "Europe/London",
>         },
>         Value: 1,
>         // Protects against duplicate events from the same flashcard
>         IdempotencyKey: "flashcard-view-42",
>     },
> )
> ```
>
> ```csharp C# theme={null}
> var trophy = new TrophyClient(
>     Environment.GetEnvironmentVariable("TROPHY_API_KEY")
> );
>
> // user.id is required. email and tz are optional but recommended
> // (tz is required for correct streak calendar days).
> var user = new EventRequestUser {
>    Id = "18",
>    Email = "user@example.com",
>    Tz = "Europe/London"
> };
>
> var request = new MetricsEventRequest {
>    User = user,
>    Value = 1,
>    // Protects against duplicate events from the same flashcard
>    IdempotencyKey = "flashcard-view-42"
> };
>
> var response = await trophy.Metrics.EventAsync("flashcards-flipped", request);
> ```
>
> ```ruby Ruby theme={null}
> client = TrophyApiClient::Client.new(
>   :api_key => ENV["TROPHY_API_KEY"]
> )
>
> # user.id is required. email and tz are optional but recommended
> # (tz is required for correct streak calendar days).
> result = client.metrics.event(
>   :key => 'flashcards-flipped',
>   :user => {
>     :id => '18',
>     :email => 'user@example.com',
>     :tz => 'Europe/London'
>   },
>   :value => 1,
>   :idempotencyKey => 'flashcard-view-42' # Protects against duplicate events from the same flashcard
> )
> ```
>
> By making this call, you're telling Trophy that a specific user made an interaction with your product. Trophy records the user's activity and automatically processes anything you've configured against the metric.
>
> > [!TIP]
> >
> > Include the user's `email` and `tz` (IANA time zone) attributes where you can. Trophy uses them to reach users and to work out each user's local day.
>
> Use the response to react to changes in the user's progress and power UI elements:
>
> ```json Response [expandable] theme={null}
> {
>   "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": "Flip 500 flashcards in the app.",
>       "badgeUrl": null,
>       "userAttributes": [],
>       "achievedAt": "2020-01-01T00:00:00Z"
>     }
>   ],
>   "currentStreak": {
>     "length": 1,
>     "frequency": "daily",
>     "started": "2025-04-02",
>     "periodStart": "2025-03-31",
>     "periodEnd": "2025-04-05",
>     "expires": "2025-04-12",
>     "extended": true
>   },
>   "points": {
>     "xp": {
>       "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
>       "key": "xp",
>       "name": "XP",
>       "description": null,
>       "badgeUrl": null,
>       "maxPoints": null,
>       "total": 10,
>       "level": {
>         "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
>         "key": "bronze",
>         "name": "Bronze",
>         "description": "Starting level",
>         "badgeUrl": null,
>         "points": 0
>       },
>       "added": 10,
>       "awards": [
>         {
>           "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
>           "awarded": 10,
>           "date": "2021-01-01T00:00:00Z",
>           "total": 10,
>           "trigger": {
>             "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
>             "type": "metric",
>             "metricName": "Flashcards Flipped",
>             "metricThreshold": 100,
>             "points": 10,
>             "status": "active",
>             "userAttributes": [],
>             "created": "2021-01-01T00:00:00Z",
>             "updated": "2021-01-01T00:00:00Z"
>           }
>         }
>       ]
>     }
>   },
>   "leaderboards": {
>     "daily_champions": {
>       "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
>       "key": "daily_champions",
>       "name": "Daily Champions",
>       "description": null,
>       "status": "active",
>       "rankBy": "metric",
>       "runUnit": "day",
>       "runInterval": 1,
>       "maxParticipants": 100,
>       "breakdownAttributes": [],
>       "metricName": "Flashcards Flipped",
>       "metricKey": "flashcards-flipped",
>       "threshold": 10,
>       "start": "2025-01-01",
>       "end": null,
>       "startTime": null,
>       "endTime": null,
>       "previousRank": 50,
>       "rank": 12
>     }
>   },
>   "idempotencyKey": "flashcard-view-42",
>   "idempotentReplayed": false
> }
> ```
>
> Once your first event is sent, see [next steps](#next-steps) to choose what to build.

## Next steps

Now that Trophy is receiving events, choose what you want to build. You can use agentic messaging, in-app features, or both on the same events.

### Send agentic messages

Deploy a 1:1 AI lifecycle agent for every user that sends personalized email and push at the right moment. Agentic messaging is set up together with the Trophy team. [Book a call](https://trophy.so/contact-sales?utm_source=docs\&utm_medium=quickstart) to get started.

> [card] [Agentic messaging](/agentic-messaging/overview.md)
>
> How 1:1 lifecycle agents replace sequences and journeys.

> [card] [Rollout](/agentic-messaging/rollout.md)
>
> What you'll set up with the Trophy team before going live.

> [card] [Channels](/agentic-messaging/channels.md)
>
> Connect email and push so agents can reach your users.

### Build in-app features

Add features to your app that give users a reason to come back, powered by the events you're already sending.

> [card] [Milestones](/features/milestones.md)
>
> Celebrate continued progress or specific actions.

> [card] [Streaks](/features/streaks.md)
>
> Motivate users to build regular usage habits.

> [card] [Points](/features/points.md)
>
> Build points systems with levels and boosts.

> [card] [Leaderboards](/features/leaderboards.md)
>
> Create friendly competition between users.

Using an AI assistant? Paste one of these prompts to build your first in-app feature:

> [accordion] Prompts for AI assistants
>
> Daily streak
>
> Build a daily streak feature with Trophy.
>
> Use the Docs MCP as the source of truth for how streaks work, and the Account MCP to configure my account.
>
> Goals:
>
> 1. Drive the streak from a core user activity already tracked (or that we should track) as a Trophy metric.
> 2. Ensure every user identify/upsert and metric event includes the user's `tz` attribute (IANA timezone). This is required for streaks to evaluate calendar days correctly for each user.
> 3. Configure the streak feature in Trophy using a sensible threshold for the chosen metric.
> 4. Enable streak freezes and streak pauses if they fit this product; otherwise omit them and say why.
> 5. Wire any app-side reads or UI needed to show the user's current streak, freezes, and pause state.
> 6. Summarize what was configured, what code changed, and how to verify the streak end to end. Explicitly explain back why sending `tz` matters for a functioning streak feature.
>
> Milestones library
>
> Build a milestones library with Trophy. Milestones are called achievements in the Trophy API, SDKs and MCP tools.
>
> Use the Docs MCP as the source of truth for achievement types and triggers, and the Account MCP to configure my account.
>
> Goals:
>
> 1. Create a set of achievements tied to core user actions tracked as Trophy metric events.
> 2. Add any one-time API-triggered achievements (and other achievement types) that fit the product.
> 3. Wire app-side handling for unlocks and a minimal way to list completed vs incomplete achievements.
> 4. Summarize what was configured, what code changed, and how to verify unlocks end to end.
>
> XP system
>
> Build an XP points system with Trophy.
>
> Use the Docs MCP as the source of truth for points systems, triggers, and levels, and the Account MCP to configure my account.
>
> Goals:
>
> 1. Create a points system that awards XP for a few key user actions tracked as Trophy metrics.
> 2. Configure triggers in the points system to award XP for the chosen user actions.
> 3. Configure levels and boosts if relevant for the use case.
> 4. Wire app-side reads or UI needed to show the user's XP total and level progress.
> 5. Summarize what was configured, what code changed, and how to verify points awards end to end.
>
> Weekly leaderboard
>
> Build a repeating weekly leaderboard with Trophy.
>
> Use the Docs MCP as the source of truth for leaderboards, and the Account MCP to configure my account.
>
> Goals:
>
> 1. Create a weekly recurring leaderboard driven by a core user action tracked as a Trophy metric.
> 2. Configure ranking logic based on the chosen metric and configure the weekly reset schedule for the leaderboard.
> 3. Wire app-side reads or UI needed to show rankings for the current week and the current user's place.
> 4. Summarize what was configured, what code changed, and how to verify rankings end to end.

Or, explore the [API reference](/api-reference/introduction.md) 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](mailto:support@trophy.so). We're here to help!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.