From 01562f34464c947dcf3fe57318df6a78e87207d7 Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Fri, 27 Mar 2026 11:55:11 +0000 Subject: [PATCH 1/6] Update quickstart with LLM pathway --- getting-started/quickstart.mdx | 360 ++++++++++++++++++-------- snippets/trophy-client-init-block.mdx | 55 ++++ 2 files changed, 305 insertions(+), 110 deletions(-) create mode 100644 snippets/trophy-client-init-block.mdx diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx index 5060ac2..18040a9 100644 --- a/getting-started/quickstart.mdx +++ b/getting-started/quickstart.mdx @@ -6,121 +6,261 @@ description: Get up and running with Trophy in under 10 minutes 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. - - - 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. - - - - 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! - - - - Alternatively, you can directly call the API using any server-side HTTP library. - - - - Add your API key that you created during onboarding (or [create a new one](https://app.trophy.so/integration)) as an environment variable in your backend application: - - - - Make sure to pass this API key to the Trophy SDK or to your API client to authenticate. - - - - All gamification features are driven by user interactions. In Trophy, you use [Metrics](/platform/metrics) to define and model those interactions and [Events](/platform/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: - - - - - - Give the metric a name and hit _Save_. - - - - 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](/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`: - - - - 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. - - - - 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: - - - - Reward users for continued progress or taking specific actions. - - - Motivate users to build regular usage habits. - - - Build sophisticated points systems to reward and retain users. - - - - - } - href="/platform/leaderboards"> - Create friendly competitions to increase user engagement. - - - Deliver personalized lifecycle emails to users at the perfect moment. - - - Drive automated notification flows using personalized gamification data. - - - - Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do. - - - + + + + + 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. + + + + 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! + + + + Alternatively, you can directly call the API using any server-side HTTP client. + + + + 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: + + + + Then initialize the Trophy API client in your backend using that API key: + + + + Make sure all Trophy SDK calls use this client for authentication. + + + All gamification features are driven by user interactions. In Trophy, you use [Metrics](/platform/metrics) to define and model those interactions and [Events](/platform/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: + + + + + + Give the metric a name and hit _Save_. + + + + 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](/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`: + + + + 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. + + + + 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: + + + + Reward users for continued progress or taking specific actions. + + + Motivate users to build regular usage habits. + + + Build sophisticated points systems to reward and retain users. + + + + + } + href="/platform/leaderboards"> + Create friendly competitions to increase user engagement. + + + Deliver personalized lifecycle emails to users at the perfect moment. + + + Drive automated notification flows using personalized gamification data. + + + + Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do. + + + + + + + + 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. + + + + Download the [llms-full.txt](/llms-full.txt) - this is the full text content of this documentation site as a `.txt` file. + + + To get the best results, always attach this file to prompts when using coding agents. + + + + Copy and paste this prompt into Cursor, Claude Code, or your coding agent of choice. + + + I'm adding gamification to my app using Trophy. + + 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 `` 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: + - Reference the attached context for all information on Trophy integration specifics. + - 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. + + + + Make sure to replace `` with the metric you set up during onboarding and attach the Trophy context you downloaded in the previous step. + + + 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. + + + 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. + + + 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: + + + Prepare to continue my Trophy integration from the existing setup. + + First, do not implement a feature immediately. Instead, ask me which gamification feature I want to build next and present these options: + - Streaks + - Points (XP, Gems, Energy etc) + - Achievements + - Leaderboards + + After I choose one option: + 1. Implement only that selected feature using Trophy APIs and existing project patterns. + 2. Add the required server-side calls/endpoints/actions that use Trohpy APIs and a minimal UI or API response surface. + 3. Add tests (or a test script) where feasible. + 4. 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. + + + For ideas on what to build next, explore: + + + + Reward users for continued progress or taking specific actions. + + + Motivate users to build regular usage habits. + + + Build sophisticated points systems to reward and retain users. + + + + + } + href="/platform/leaderboards"> + Create friendly competitions to increase user engagement. + + + Deliver personalized lifecycle emails to users at the perfect moment. + + + Drive automated notification flows using personalized gamification data. + + + + Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do. + + + + ## Get Support diff --git a/snippets/trophy-client-init-block.mdx b/snippets/trophy-client-init-block.mdx new file mode 100644 index 0000000..8e9b5cd --- /dev/null +++ b/snippets/trophy-client-init-block.mdx @@ -0,0 +1,55 @@ + +```typescript Node +import { TrophyApiClient } from "@trophyso/node"; + +const trophy = new TrophyApiClient({ + apiKey: process.env.TROPHY_API_KEY as string, +}); +``` + +```ruby Ruby +client = TrophyApiClient::Client.new( + :api_key => ENV["TROPHY_API_KEY"] +) +``` + +```python Python +from trophy import Trophy + +client = Trophy( + api_key=os.environ.get("TROPHY_API_KEY"), +) +``` + +```php PHP +use Trophy\TrophyClient; + +$trophy = new TrophyClient([ + 'apiKey' => getenv('TROPHY_API_KEY') +]); +``` + +```java Java (Gradle) +TrophyApiClient client = TrophyApiClient.builder() + .apiKey(System.getenv("TROPHY_API_KEY")) + .build(); +``` + +```java Java (Maven) +TrophyApiClient client = TrophyApiClient.builder() + .apiKey(System.getenv("TROPHY_API_KEY")) + .build(); +``` + +```go Go +client, err := trophy.NewClient( + option.WithAPIKey(os.Getenv("TROPHY_API_KEY")), +) +``` + +```csharp .NET (C#) +var trophy = new TrophyClient( + Environment.GetEnvironmentVariable("TROPHY_API_KEY") +); +``` + From 2c8ab2728ff4feb58f0641ddd5caae69069075e5 Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Fri, 27 Mar 2026 12:05:43 +0000 Subject: [PATCH 2/6] Highlight concepts card on home page --- getting-started/introduction.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/getting-started/introduction.mdx b/getting-started/introduction.mdx index 8ac325c..5dabda8 100644 --- a/getting-started/introduction.mdx +++ b/getting-started/introduction.mdx @@ -8,6 +8,9 @@ Trophy is a developer-friendly toolkit for building gamified product experiences It makes building features like [Achievements](/platform/achievements), [Streaks](/platform/streaks), [Points](/platform/points) and [Leaderboards](/platform/leaderboards) simple with just a few lines of code, and can send gamified [Emails](/platform/emails) and [Push Notifications](/platform/push-notifications) to increase your retention and engagement. + + Get familiar with the mental model of gamification in Trophy. + - Use Trophy to build practical solutions to common gamification use cases. - - - Learn the key concepts behind building gamification experiences with Trophy. + Use Trophy to build solutions to common gamification use cases. Explore the Trophy API and see what's possible. From a22f0bef43c8a1785aeda8fda2a4cbda2680fcd6 Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Fri, 27 Mar 2026 13:14:02 +0000 Subject: [PATCH 3/6] typo --- getting-started/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx index 18040a9..8288102 100644 --- a/getting-started/quickstart.mdx +++ b/getting-started/quickstart.mdx @@ -203,7 +203,7 @@ Here you'll integrate your backend web application with Trophy and start buildin After I choose one option: 1. Implement only that selected feature using Trophy APIs and existing project patterns. - 2. Add the required server-side calls/endpoints/actions that use Trohpy APIs and a minimal UI or API response surface. + 2. Add the required server-side calls/endpoints/actions that use Trophy APIs and a minimal UI or API response surface. 3. Add tests (or a test script) where feasible. 4. Document any new env vars, routes, and usage steps. From 0a3542fefe5d14f3dfc7d97080b024e4a48db298 Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Fri, 27 Mar 2026 13:15:16 +0000 Subject: [PATCH 4/6] Explicit url --- getting-started/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx index 8288102..aecd103 100644 --- a/getting-started/quickstart.mdx +++ b/getting-started/quickstart.mdx @@ -139,7 +139,7 @@ Here you'll integrate your backend web application with Trophy and start buildin - Download the [llms-full.txt](/llms-full.txt) - this is the full text content of this documentation site as a `.txt` file. + Download the [llms-full.txt](https://docs.trophy.so/llms-full.txt) - this is the full text content of this documentation site as a `.txt` file. To get the best results, always attach this file to prompts when using coding agents. From a3d7cd7a379a86c949e7ce766be987c3c62e6472 Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Fri, 27 Mar 2026 13:27:37 +0000 Subject: [PATCH 5/6] spellcheck --- snippets/trophy-client-init-block.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/snippets/trophy-client-init-block.mdx b/snippets/trophy-client-init-block.mdx index 8e9b5cd..ea40089 100644 --- a/snippets/trophy-client-init-block.mdx +++ b/snippets/trophy-client-init-block.mdx @@ -1,3 +1,5 @@ +{/* vale off */} + ```typescript Node import { TrophyApiClient } from "@trophyso/node"; From b8fdb3671f5c86af2649c86d2f5f81fc440398ee Mon Sep 17 00:00:00 2001 From: Charlie Hopkins-Brinicombe Date: Fri, 27 Mar 2026 14:55:01 +0000 Subject: [PATCH 6/6] Update ai quickstart to point to using mcp/agent skills --- getting-started/quickstart.mdx | 108 ++++++++++++++++++++++++++++----- 1 file changed, 93 insertions(+), 15 deletions(-) diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx index aecd103..6973e7b 100644 --- a/getting-started/quickstart.mdx +++ b/getting-started/quickstart.mdx @@ -14,6 +14,8 @@ Here you'll integrate your backend web application with Trophy and start buildin + These instructions are for those who want to implement Trophy by hand. If instead you prefer to use coding agents, switch tabs above. + 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). @@ -131,6 +133,8 @@ Here you'll integrate your backend web application with Trophy and start buildin + These instructions are for those who prefer to develop using coding agents like Cursor and Claude Code. + 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). @@ -138,15 +142,88 @@ Here you'll integrate your backend web application with Trophy and start buildin Head through onboarding to get your account set up. - - Download the [llms-full.txt](https://docs.trophy.so/llms-full.txt) - this is the full text content of this documentation site as a `.txt` file. - + + 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` + - To get the best results, always attach this file to prompts when using coding agents. + 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. + + + + 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. + + + 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 + ``` + + + 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 + ``` + + + 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 + ``` + + - Copy and paste this prompt into Cursor, Claude Code, or your coding agent of choice. + Here's a prompt you can use with your coding agent to perform initial Trophy setup: 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. @@ -164,7 +243,9 @@ Here you'll integrate your backend web application with Trophy and start buildin 5. Add or update a short README section explaining how the integration works and how to extend it. Constraints: - - Reference the attached context for all information on Trophy integration specifics. + - 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. @@ -172,7 +253,7 @@ Here you'll integrate your backend web application with Trophy and start buildin - Make sure to replace `` with the metric you set up during onboarding and attach the Trophy context you downloaded in the previous step. + Make sure to replace `` with the metric you set up during onboarding. This will: @@ -195,17 +276,14 @@ Here you'll integrate your backend web application with Trophy and start buildin > Prepare to continue my Trophy integration from the existing setup. - First, do not implement a feature immediately. Instead, ask me which gamification feature I want to build next and present these options: - - Streaks - - Points (XP, Gems, Energy etc) - - Achievements - - Leaderboards + 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 Trophy APIs and existing project patterns. + 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. Add tests (or a test script) where feasible. - 4. Document any new env vars, routes, and usage steps. + 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.