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. diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx index 5060ac2..6973e7b 100644 --- a/getting-started/quickstart.mdx +++ b/getting-started/quickstart.mdx @@ -6,121 +6,339 @@ 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). + + + 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). - Head through onboarding to get your account set up. + 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! + + + 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. + Alternatively, you can directly call the API using any server-side HTTP client. - - - 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: + + + 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: - + - Make sure to pass this API key to the Trophy SDK or to your API client to authenticate. + Then initialize the Trophy API client in your backend using that API key: - - - 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. - - - + + + 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. + + + + + + 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). + + Head through onboarding to get your account set up. + + + + 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` + + + 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 + ``` + + + + + 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. + 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: + - 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. + + + + Make sure to replace `` with the metric you set up during onboarding. + + + 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, 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. + + + 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..ea40089 --- /dev/null +++ b/snippets/trophy-client-init-block.mdx @@ -0,0 +1,57 @@ +{/* vale off */} + + +```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") +); +``` +