| title | Trophy quick start |
|---|---|
| description | Integrate Trophy into your backend in under 10 minutes and start tracking events, completing achievements, and powering gamified features. |
| og:description | Follow this quick start guide to integrate Trophy into your backend and add gamified features like achievements and streaks into your app. |
import SdkInstallCommand from "../snippets/sdk-install-command.mdx"; import AddEnvVarBlock from "../snippets/add-env-var-block.mdx"; import TrophyClientInitBlock from "../snippets/trophy-client-init-block.mdx"; import MetricChangeRequestBlock from "../snippets/metric-change-request-block.mdx"; import MetricChangeResponseBlock from "../snippets/metric-change-response-block.mdx";
Here you'll integrate your backend web application with Trophy and start building your first gamified feature.
These instructions are for those who want to implement Trophy by hand. If instead you prefer to use coding agents, switch tabs above.<Steps>
<Step title="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.
</Step>
<Step title="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!
<SdkInstallCommand />
Alternatively, you can directly call the API using any server-side HTTP client.
</Step>
<Step title="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:
<AddEnvVarBlock />
Then initialize the Trophy API client in your backend using that API key:
<TrophyClientInitBlock />
Make sure all Trophy SDK calls use this client for authentication.
</Step>
<Step title="Create your first metric">
All gamification features are driven by user interactions. In Trophy, you use [Metrics](/features/metrics) to define and model those interactions and [Events](/features/events) 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 hit the _New Metric_ button:
<Frame>
<video
autoPlay
muted
loop
playsInline
className="w-full aspect-video"
src="../assets/features/metrics/create_new_metric.mp4"
></video>
</Frame>
Give the metric a name and hit _Save_.
</Step>
<Step title="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.
<Frame>
<video
autoPlay
muted
loop
playsInline
className="w-full aspect-video"
src="../assets/quick-start/copy_metric_key.mp4"
></video>
</Frame>
To track an event against this metric when a user interacts with your product, call the [metric change event API](/api-reference/endpoints/metrics/send-a-metric-change-event), passing along details of the user that made the interaction. In this example the metric key would be `flashcards-flipped`:
<MetricChangeRequestBlock />
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.
</Step>
<Step title="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:
<CardGroup>
<Card title="Achievements" icon="trophy" href="/features/achievements">
Reward users for continued progress or taking specific actions.
</Card>
<Card title="Streaks" icon="flame" href="/features/streaks">
Motivate users to build regular usage habits.
</Card>
<Card title="Points" icon="sparkle" href="/features/points">
Build sophisticated points systems to reward and retain users.
</Card>
<Card
title="Leaderboards"
icon={
<svg
width="20"
height="18"
viewBox="0 0 20 18"
fill="none"
xmlns="http://www.w3.org/2000/svg"
className="text-primary dark:text-primary-light"
>
<path
d="M2 16H6V8H2V16ZM8 16H12V2H8V16ZM14 16H18V10H14V16ZM0 16V8C0 7.45 0.195833 6.97917 0.5875 6.5875C0.979167 6.19583 1.45 6 2 6H6V2C6 1.45 6.19583 0.979167 6.5875 0.5875C6.97917 0.195833 7.45 0 8 0H12C12.55 0 13.0208 0.195833 13.4125 0.5875C13.8042 0.979167 14 1.45 14 2V8H18C18.55 8 19.0208 8.19583 19.4125 8.5875C19.8042 8.97917 20 9.45 20 10V16C20 16.55 19.8042 17.0208 19.4125 17.4125C19.0208 17.8042 18.55 18 18 18H2C1.45 18 0.979167 17.8042 0.5875 17.4125C0.195833 17.0208 0 16.55 0 16Z"
fill="currentColor"
/>
</svg>
}
href="/features/leaderboards">
Create friendly competitions to increase user engagement.
</Card>
<Card title="Emails" icon="mail" href="/features/emails">
Deliver personalized lifecycle emails to users at the perfect moment.
</Card>
<Card title="Push Notifications" icon="bell" href="/features/push-notifications">
Drive automated notification flows using personalized gamification data.
</Card>
</CardGroup>
Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
</Step>
</Steps>
<Steps>
<Step title="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.
</Step>
<Step title="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`
<Tip>
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.
</Tip>
<Tabs>
<Tab title="Claude">
1. Open [Claude Connectors](https://claude.ai/settings/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](https://claude.ai/customize/skills) using `https://docs.trophy.so/skill.md` so Claude consistently uses Trophy's capability summary.
</Tab>
<Tab title="Claude Code">
Add Trophy MCP:
```bash
claude mcp add --transport http Trophy https://docs.trophy.so/mcp
```
Verify:
```bash
claude mcp list
```
Optional: add Trophy Agent Skill:
```bash
npx skills add https://docs.trophy.so
```
</Tab>
<Tab title="Cursor">
Open MCP settings and add this to your `mcp.json`:
```json
{
"mcpServers": {
"Trophy": {
"url": "https://docs.trophy.so/mcp"
}
}
}
```
Optional: add Trophy Agent Skill:
```bash
npx skills add https://docs.trophy.so
```
</Tab>
<Tab title="VS Code">
Create `.vscode/mcp.json`:
```json
{
"servers": {
"Trophy": {
"type": "http",
"url": "https://docs.trophy.so/mcp"
}
}
}
```
Optional: add Trophy Agent Skill:
```bash
npx skills add https://docs.trophy.so
```
</Tab>
</Tabs>
</Step>
<Step title="Tell your agent to perform initial setup">
Here's a prompt you can use with your coding agent to perform initial Trophy setup:
<Prompt
description="Perform initial Trophy setup"
icon="paperclip"
iconType="solid"
actions={["copy", "cursor"]}
>
I'm adding gamification to my app using Trophy.
Before making changes, verify the connected `Trophy` MCP server or Agent Skill is available and use it as the primary source of truth for Trophy integration details.
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).
2. Add `TROPHY_API_KEY` to environment config in a secure way (no secrets committed to git), and wire it into the Trophy client initialization.
3. Add code to track a metric change event for the metric `<metric>` using the Trophy API client, wiring all required user attributes like ID, and using placeholders for all optional attributes like name, email and tz.
4. Add basic error handling and logging around Trophy API calls.
5. Add or update a short README section explaining how the integration works and how to extend it.
Constraints:
- Use Trophy MCP tool results for all Trophy-specific implementation decisions.
- If Trophy Agent Skill context is available in this environment, follow it.
- Do not rely on prior memory for Trophy API behavior when MCP or Agent provides an answer.
- Keep secrets out of source control.
- Use existing project patterns and naming conventions.
- Show me a concise summary of changed files and how to test the setup.
- Suggest next steps based on the gamification features Trophy supports.
</Prompt>
<Note>
Make sure to replace `<metric>` with the metric you set up during onboarding.
</Note>
This will:
1. Add the relevant [Trophy SDK](/api-reference/client-libraries) 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.
</Step>
<Step title="Grab your API key">
Once the set up is complete, [create an API key](https://app.trophy.so/integration) from the integration page of the Trophy dashboard and add it to your environment.
</Step>
<Step title="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:
<Prompt
description="Build your first gamification feature"
icon="paperclip"
iconType="solid"
actions={["copy", "cursor"]}
>
Prepare to continue my Trophy integration from the existing setup.
First, verify the connected `Trophy` MCP server or Agent skill is available and use it as the source of truth for feature-specific integration details.
Before implementing anything, ask me which gamification feature I want to build, providing options based on what the Trophy MCP or Agent Skill says Trophy supports.
After I choose one option:
1. Implement only that selected feature using the relevant Trophy APIs and existing project patterns.
2. Add the required server-side calls/endpoints/actions that use Trophy APIs and a minimal UI or API response surface.
3. Document any new env vars, routes, and usage steps.
If I ask for a feature Trophy does not support, do not implement a workaround.
Instead, tell me it's not currently supported and ask me to contact Trophy support at support@trophy.so to submit a feature request.
Keep changes production-minded:
- Follow existing architecture and naming conventions.
- Handle API failures gracefully.
- Return a clear list of changed files and manual verification steps.
</Prompt>
For ideas on what to build next, explore:
<CardGroup>
<Card title="Achievements" icon="trophy" href="/features/achievements">
Reward users for continued progress or taking specific actions.
</Card>
<Card title="Streaks" icon="flame" href="/features/streaks">
Motivate users to build regular usage habits.
</Card>
<Card title="Points" icon="sparkle" href="/features/points">
Build sophisticated points systems to reward and retain users.
</Card>
<Card
title="Leaderboards"
icon={
<svg
width="20"
height="18"
viewBox="0 0 20 18"
fill="none"
xmlns="http://www.w3.org/2000/svg"
className="text-primary dark:text-primary-light"
>
<path
d="M2 16H6V8H2V16ZM8 16H12V2H8V16ZM14 16H18V10H14V16ZM0 16V8C0 7.45 0.195833 6.97917 0.5875 6.5875C0.979167 6.19583 1.45 6 2 6H6V2C6 1.45 6.19583 0.979167 6.5875 0.5875C6.97917 0.195833 7.45 0 8 0H12C12.55 0 13.0208 0.195833 13.4125 0.5875C13.8042 0.979167 14 1.45 14 2V8H18C18.55 8 19.0208 8.19583 19.4125 8.5875C19.8042 8.97917 20 9.45 20 10V16C20 16.55 19.8042 17.0208 19.4125 17.4125C19.0208 17.8042 18.55 18 18 18H2C1.45 18 0.979167 17.8042 0.5875 17.4125C0.195833 17.0208 0 16.55 0 16Z"
fill="currentColor"
/>
</svg>
}
href="/features/leaderboards">
Create friendly competitions to increase user engagement.
</Card>
<Card title="Emails" icon="mail" href="/features/emails">
Deliver personalized lifecycle emails to users at the perfect moment.
</Card>
<Card title="Push Notifications" icon="bell" href="/features/push-notifications">
Drive automated notification flows using personalized gamification data.
</Card>
</CardGroup>
Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
</Step>
</Steps>
Want to get in touch with the Trophy team? Reach out to us via email. We're here to help!