> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Inicio rápido
> Instala un SDK de Trophy, autentícate, identifica a un usuario y envía tu primer evento de métrica en aproximadamente cinco minutos.
Aquí integrarás tu aplicación con Trophy y comenzarás a construir tu primera función gamificada en aproximadamente cinco minutos.
Estas instrucciones son para usar Trophy con asistentes de IA que admiten MCP, por ejemplo Claude, ChatGPT, Cursor o Claude Code.
Primero, [crea una nueva cuenta](https://app.trophy.so/sign-up?utm_source=docs\&utm_medium=quickstart) si aún no tienes una. Completa la incorporación para configurar tu cuenta.
Conecta ambos servidores MCP de Trophy en tu cliente de IA para obtener la mejor experiencia:
* URL del servidor MCP de documentación: `https://docs.trophy.so/mcp` (contexto de documentación en vivo)
* URL del servidor MCP de cuenta: `https://mcp.trophy.so/mcp` (acciones de cuenta — inicio de sesión OAuth requerido)
Guías de configuración: [Instalación del MCP de documentación](/es/mcp/docs-mcp-server/installation), [Instalación del MCP de cuenta](/es/mcp/account-mcp-server/installation).
Usa el [MCP de documentación](/es/mcp/docs-mcp-server/introduction) como contexto de documentación bajo demanda y el [MCP de cuenta](/es/mcp/account-mcp-server/introduction) para cambios de cuenta. Usa ambos para [mejores prácticas](/es/mcp/best-practice).
Aquí hay un prompt que puedes usar con tu asistente de IA para realizar la configuración inicial de Trophy:
Estoy agregando gamificación a mi aplicación usando Trophy.
Antes de realizar cambios, verifica que los servidores MCP de Trophy conectados estén disponibles. Usa el servidor MCP de documentación como la fuente principal de verdad para los detalles de integración de Trophy, y el servidor MCP de cuenta para configurar mi cuenta.
Por favor, realiza la configuración inicial completa de principio a fin:
1. Detecta el lenguaje/framework del backend en este repositorio e instala el SDK oficial de Trophy correspondiente (o usa llamadas HTTP si no hay SDK disponible). Informa al soporte de Trophy si no hay SDK disponible.
2. Agrega `TROPHY_API_KEY` a la configuración de entorno de forma segura (sin secretos confirmados en git), e intégralo en la inicialización del cliente del SDK de Trophy.
3. Agrega código para configurar el seguimiento de eventos de métricas para la actividad de usuario elegida (pregunta si aún no se conoce) usando el cliente del SDK de Trophy, conectando todos los atributos de usuario requeridos como ID, y usando marcadores de posición para todos los atributos opcionales como nombre, email, tz y signUpDate, a menos que ya sean conocidos o requeridos por el caso de uso.
4. Agrega manejo básico de errores y registro de eventos en torno a las llamadas del SDK de Trophy.
5. Agrega o actualiza una sección breve del README explicando cómo funciona la integración y cómo extenderla.
Restricciones:
* Usa los resultados de la herramienta Docs MCP para todas las decisiones de implementación e integraciones específicas de Trophy.
* No confíes en la memoria previa para el comportamiento del SDK de Trophy cuando MCP proporcione una respuesta.
* Mantén los secretos fuera del control de código fuente.
* Usa los patrones y convenciones de nomenclatura existentes del proyecto.
* Muestra un resumen conciso de los archivos modificados y cómo probar la configuración.
* Sugiere los siguientes pasos basados en las funciones de gamificación que Trophy soporta y el caso de uso.
Esto hará lo siguiente:
1. Agregará el [SDK de Trophy](/es/api-reference/client-libraries) correspondiente a tu aplicación según tu stack tecnológico
2. Agregará una nueva variable `TROPHY_API_KEY` a tu configuración de entorno
3. Agregará código para rastrear eventos de métricas para la actividad de usuario elegida usando el cliente del SDK de Trophy - requerido para todas las funciones de gamificación.
Una vez completada la configuración inicial, elige un caso de uso común y pega el prompt correspondiente en tu asistente de IA:
Crea una funcionalidad de racha diaria con Trophy.
Usa el MCP de Documentación como fuente de verdad para cómo funcionan las rachas, y el MCP de Cuenta para configurar mi cuenta.
Objetivos:
1. Impulsar la racha desde una actividad principal del usuario que ya se rastree (o que deberíamos rastrear) como una métrica de Trophy.
2. Asegurar que cada identificación/actualización de usuario y evento de métrica incluya el atributo `tz` del usuario (zona horaria IANA). Esto es necesario para que las rachas evalúen correctamente los días calendario para cada usuario.
3. Configurar la funcionalidad de racha en Trophy usando un umbral sensato para la métrica elegida.
4. Habilitar congelaciones de racha y pausas de racha si encajan con este producto; de lo contrario, omitirlas y explicar por qué.
5. Conectar cualquier lectura del lado de la aplicación o interfaz necesaria para mostrar la racha actual del usuario, congelaciones y estado de pausa.
6. Resumir qué se configuró, qué código cambió y cómo verificar la racha de principio a fin. Explicar explícitamente por qué enviar `tz` es importante para que funcione correctamente la funcionalidad de racha.
Crea una biblioteca de logros con Trophy.
Usa el MCP de Documentación como fuente de verdad para tipos de logros y activadores, y el MCP de Cuenta para configurar mi cuenta.
Objetivos:
1. Crear un conjunto de logros vinculados a acciones principales del usuario rastreadas como eventos de métrica de Trophy.
2. Agregar cualquier logro activado por API de una sola vez (y otros tipos de logros) que encajen con el producto.
3. Conectar el manejo del lado de la aplicación para desbloqueos y una forma mínima de listar logros completados vs incompletos.
4. Resumir qué se configuró, qué código cambió y cómo verificar los desbloqueos de principio a fin.
Crea un sistema de puntos XP con Trophy.
Usa el MCP de Documentación como fuente de verdad para sistemas de puntos, activadores y niveles, y el MCP de Cuenta para configurar mi cuenta.
Objetivos:
1. Crear un sistema de puntos que otorgue XP por algunas acciones clave del usuario rastreadas como métricas de Trophy.
2. Configurar activadores en el sistema de puntos para otorgar XP por las acciones de usuario elegidas.
3. Configurar niveles y bonificaciones si son relevantes para el caso de uso.
4. Implementar las lecturas del lado de la aplicación o la interfaz necesarias para mostrar el total de XP del usuario y el progreso de nivel.
5. Resumir qué se configuró, qué código cambió y cómo verificar las asignaciones de puntos de extremo a extremo.
Crea una clasificación semanal recurrente con Trophy.
Usa el MCP de Documentación como fuente de verdad para clasificaciones, y el MCP de Cuenta para configurar mi cuenta.
Objetivos:
1. Crear una clasificación recurrente semanal impulsada por una acción central del usuario rastreada como una métrica de Trophy.
2. Configurar la lógica de clasificación basada en la métrica elegida y configurar el calendario de reinicio semanal para la clasificación.
3. Implementar las lecturas del lado de la aplicación o la interfaz necesarias para mostrar las clasificaciones de la semana actual y la posición del usuario actual.
4. Resumir qué se configuró, qué código cambió y cómo verificar las clasificaciones de extremo a extremo.
Para más ideas sobre qué construir a continuación, explora:
Recompensa a los usuarios por el progreso continuo o por realizar acciones específicas.
Motiva a los usuarios a crear hábitos de uso regular.
Crea sistemas de puntos sofisticados para recompensar y retener usuarios.
}
href="/es/features/leaderboards"
>
Crea competencias amistosas para aumentar la participación de los usuarios.
Envía correos electrónicos de ciclo de vida personalizados a los usuarios en el momento perfecto.
Impulsa flujos de notificación automatizados usando datos de gamificación personalizados.
Estas instrucciones son para quienes desean implementar Trophy manualmente. Si en cambio prefieres usar IA, cambia de pestaña arriba.
Primero, [crea una nueva cuenta](https://app.trophy.so/sign-up?utm_source=docs\&utm_medium=quickstart) si aún no tienes una y dirígete al [panel de Trophy](https://app.trophy.so).
Completa la configuración inicial para configurar tu cuenta.
Tenemos bibliotecas SDK disponibles en los principales lenguajes de programación, pero si no ves el tuyo en la lista, ¡avísanos y crearemos uno!
```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}
so.trophy
trophy-java
1.0.0
```
```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
```
Alternativamente, puedes llamar directamente a la API usando cualquier cliente HTTP del lado del servidor.
Dirígete a la [página de integración](https://app.trophy.so/integration) del panel de Trophy y crea una nueva clave API.
Añade tu clave API como variable de entorno en tu aplicación backend:
```bash theme={null}
TROPHY_API_KEY='*******'
```
Luego inicializa el cliente de la API de Trophy en tu backend usando esa clave API:
```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")
);
```
Asegúrate de que todas las llamadas del SDK de Trophy usen este cliente para la autenticación.
Todas las funciones de gamificación se basan en las interacciones de los usuarios. En Trophy, usas [Métricas](/es/features/metrics) para definir y modelar esas interacciones y [Eventos](/es/features/events) para rastrearlos.
Aquí crearás tu primera métrica para comenzar. En el panel de Trophy, dirígete a la [página de métricas](https://app.trophy.so/metrics) y haz clic en el botón *Nueva Métrica*:
Dale un nombre a la métrica y haz clic en *Guardar*.
Una vez que hayas creado tu métrica, ve a la pestaña de configuración y copia su clave de referencia API única.
Para rastrear un evento contra esta métrica cuando un usuario interactúa con tu producto, llama a la [API de evento de cambio de métrica](/es/api-reference/endpoints/events/submit-a-metric-event), pasando los detalles del usuario que realizó la interacción. En este ejemplo, la clave de métrica sería `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
)
```
Al realizar esta llamada, le estás indicando a Trophy que un usuario específico realizó una interacción con tu producto. Como resultado, Trophy procesará automáticamente cualquier función de gamificación como logros o rachas que hayas configurado para la métrica.
Utiliza la respuesta para reaccionar a los cambios en el estado de gamificación del usuario y alimentar elementos de la interfaz:
```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
}
```
Con una métrica integrada en tu backend, estás listo para comenzar a agregar funciones de gamificación a tu producto.
Sigue los enlaces a continuación para conocer más sobre cada función que puedes construir con Trophy:
Recompensa a los usuarios por su progreso continuo o por realizar acciones específicas.
Motiva a los usuarios a desarrollar hábitos de uso regulares.
Construye sistemas de puntos sofisticados para recompensar y retener usuarios.
}
href="/es/features/leaderboards"
>
Crea competencias amistosas para aumentar la participación de los usuarios.
Envía correos electrónicos personalizados del ciclo de vida a los usuarios en el momento perfecto.
Impulsa flujos de notificaciones automatizadas utilizando datos de gamificación personalizados.
O explora nuestra [referencia de API](/es/api-reference/introduction) para familiarizarte con lo que Trophy puede hacer.
Obtener Soporte
¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
## Related topics
- [Inicio rápido](/es/webhooks/quickstart.md)
- [Bienvenido a Trophy](/es/getting-started/introduction.md)
- [Introducción](/es/webhooks/introduction.md)
- [Puntos](/es/features/points.md)
- [Experimentación](/es/platform/experimentation.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.