Skip to content

Commit ce73810

Browse files
Merge pull request #91 from trophyso/agent-experience
Update docs based on agent experience review
2 parents 75f2665 + ceb87ad commit ce73810

18 files changed

Lines changed: 886 additions & 191 deletions

‎api-reference/client-libraries.mdx‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
---
22
title: Client Libraries
3-
description: Use Trophy's type-safe SDKs to integrate with the API.
4-
og:description: Use Trophy's type-safe SDKs to integrate with the API and start
5-
building gamified product experiences.
3+
description: Official Trophy SDKs for Node, Go, Java, .NET, PHP, Python, and Ruby with install commands and GitHub repositories.
4+
og:description: Official Trophy SDKs for Node, Go, Java, .NET, PHP, Python, and Ruby with install commands and GitHub repositories.
65
icon: code-xml
76
---
87

‎api-reference/errors.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Error Codes
3+
description: Common Trophy API HTTP status codes.
4+
og:description: Common Trophy API HTTP status codes.
5+
icon: circle-x
6+
---
7+
8+
This page summarizes the HTTP status codes you will see most often when integrating with the Trophy Application API. For endpoint-specific behaviour and response schemas, see the [API reference](/api-reference/introduction).
9+
10+
## Authentication errors {#authentication-errors}
11+
12+
| Status | When it happens | What to do |
13+
| --- | --- | --- |
14+
| `401 Unauthorized` | The `X-API-KEY` header is missing or invalid | Create or rotate an application API key and verify [authentication](/api-reference/authentication) set up|
15+
16+
## Rate limiting {#rate-limiting}
17+
18+
| Status | When it happens | What to do |
19+
| --- | --- | --- |
20+
| `429 Too Many Requests` | Your organisation exceeded the endpoint [rate limit](/api-reference/rate-limiting) | Back off and retry; request a higher limit if needed |
21+
22+
## Retry guidance {#retry-guidance}
23+
24+
- Retry `429` and `5xx` with exponential backoff.
25+
- On retry, send the same idempotency key for the same logical action so Trophy does not double-count.
26+
- Do not retry `401` until the API key is fixed.
27+
28+
## Get Support {#get-support}
29+
30+
Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!

‎api-reference/introduction.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Introduction
3-
description: Learn about the Trophy API and get started building your integration.
3+
description: Authenticate, handle errors and rate limits, use idempotency, and explore Trophy Application API SDKs.
44
subtitle: Learn about the Trophy API and get started building your integration.
55
---
66

@@ -36,6 +36,9 @@ Learn more about how to integrate with the Trophy Application API below.
3636
<Card title="Idempotency" icon="repeat" href="/api-reference/idempotency">
3737
Learn how to prevent unintended side effects when retrying requests.
3838
</Card>
39+
<Card title="Errors" icon="circle-exclamation" href="/api-reference/errors">
40+
Common HTTP status codes for auth, rate limits, and metric events.
41+
</Card>
3942
<Card title="SDKs" icon="code-xml" href="/api-reference/client-libraries">
4043
Use Trophy’s type-safe SDKs to integrate with the API.
4144
</Card>

‎docs.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,8 @@
8181
"group": "Getting Started",
8282
"pages": [
8383
"getting-started/introduction",
84-
"getting-started/quickstart"
84+
"getting-started/quickstart",
85+
"getting-started/production-checklist"
8586
]
8687
},
8788
{
@@ -155,6 +156,7 @@
155156
"api-reference/authentication",
156157
"api-reference/rate-limiting",
157158
"api-reference/idempotency",
159+
"api-reference/errors",
158160
"api-reference/client-libraries"
159161
]
160162
},
@@ -488,7 +490,8 @@
488490
"group": "Primeros pasos",
489491
"pages": [
490492
"es/getting-started/introduction",
491-
"es/getting-started/quickstart"
493+
"es/getting-started/quickstart",
494+
"es/getting-started/production-checklist"
492495
]
493496
},
494497
{
@@ -562,6 +565,7 @@
562565
"es/api-reference/authentication",
563566
"es/api-reference/rate-limiting",
564567
"es/api-reference/idempotency",
568+
"es/api-reference/errors",
565569
"es/api-reference/client-libraries"
566570
]
567571
},

‎es/api-reference/client-libraries.mdx‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
---
22
title: Bibliotecas de Cliente
3-
description: Utiliza los SDK con tipado seguro de Trophy para integrar con la API.
4-
og:description: Utiliza los SDK con tipado seguro de Trophy para integrar con la
5-
API y empezar a crear experiencias de producto gamificadas.
3+
description: SDKs oficiales de Trophy para Node, Go, Java, .NET, PHP, Python y Ruby con comandos de instalación y repositorios de GitHub.
4+
og:description: SDKs oficiales de Trophy para Node, Go, Java, .NET, PHP, Python y Ruby con comandos de instalación y repositorios de GitHub.
65
icon: code-xml
76
---
87

‎es/api-reference/errors.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Códigos de error
3+
description: Códigos de estado HTTP comunes de la API de Trophy.
4+
og:description: Códigos de estado HTTP comunes de la API de Trophy.
5+
icon: circle-x
6+
---
7+
8+
Esta página resume los códigos de estado HTTP que verá con mayor frecuencia al integrar con la API de la aplicación Trophy. Para el comportamiento específico de cada endpoint y los esquemas de respuesta, consulte la [referencia de la API](/es/api-reference/introduction).
9+
10+
## Errores de autenticación {#authentication-errors}
11+
12+
| Estado | Cuándo ocurre | Qué hacer |
13+
| --- | --- | --- |
14+
| `401 Unauthorized` | Falta el encabezado `X-API-KEY` o no es válido | Cree o rote una clave de API de aplicación y verifique la configuración de [autenticación](/es/api-reference/authentication)|
15+
16+
## Límite de solicitudes {#rate-limiting}
17+
18+
| Estado | Cuándo ocurre | Qué hacer |
19+
| --- | --- | --- |
20+
| `429 Too Many Requests` | Su organización excedió los [Límites de velocidad](/es/api-reference/rate-limiting) del endpoint | Reduzca la frecuencia y reintente; solicite un límite más alto si es necesario |
21+
22+
## Orientación para reintentos {#retry-guidance}
23+
24+
- Reintente `429` y `5xx` con backoff exponencial.
25+
- Al reintentar, envíe la misma clave de idempotencia para la misma acción lógica para que Trophy no cuente dos veces.
26+
- No reintente `401` hasta que se corrija la clave de API.
27+
28+
## Obtener soporte {#get-support}
29+
30+
¿Quiere ponerse en contacto con el equipo de Trophy? Comuníquese con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudar!

‎es/api-reference/introduction.mdx‎

Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,50 @@
11
---
22
title: Introducción
3-
description: Aprende sobre la API de Trophy y comienza a construir tu integración.
4-
subtitle: Aprende sobre la API de Trophy y comienza a construir tu integración.
3+
description: Autentíquese, gestione errores y límites de velocidad, utilice
4+
idempotencia y explore los SDK de la API de la aplicación Trophy.
5+
subtitle: Aprenda sobre la API de Trophy y comience a desarrollar su integración.
56
---
6-
La API de aplicaciones de Trophy es un conjunto de endpoints que proporcionan interfaces simples para crear experiencias de gamificación y cubre toda la gama de acciones que un usuario final de tu aplicación puede realizar.
77

8-
No incluye funciones administrativas globales ni acciones que solo deberían ser realizadas por tus sistemas internos. Si buscas funcionalidad administrativa, consulta la [API de administración](/es/admin-api/introduction).
8+
La API de la aplicación Trophy es un conjunto de endpoints que proporcionan interfaces simples para construir experiencias de gamificación y cubre toda la gama de acciones que un usuario final de su aplicación puede realizar.
99

10-
La API de aplicaciones es accesible a través de [SDKs](/es/api-reference/client-libraries) disponibles en la mayoría de los lenguajes de programación principales o, para quienes deseen gestionar sus propios clientes HTTP, está disponible en la siguiente URL base.
10+
No incluye funciones administrativas globales ni acciones que solo deben ser realizadas por sus sistemas internos. Si busca funcionalidad administrativa, consulte la [API de administración](/es/admin-api/introduction).
11+
12+
La API de la aplicación es accesible a través de [SDK](/es/api-reference/client-libraries) disponibles en la mayoría de los principales lenguajes de programación o, para aquellos que deseen gestionar sus propios clientes HTTP, está disponible en la siguiente URL base.
1113

1214
```bash Base URL
1315
https://api.trophy.so/v1
1416
```
1517

18+
<Tip>
1619
La referencia completa de la API está disponible públicamente en [/openapi](https://api.trophy.so/v1/openapi).
20+
</Tip>
1721

18-
## Comienza {#get-started}
22+
## Comience {#get-started}
1923

20-
Aprende más sobre cómo integrar la API de aplicaciones de Trophy a continuación.
24+
Aprenda más sobre cómo integrar con la API de la aplicación Trophy a continuación.
2125

2226
<CardGroup>
2327
<Card title="Autenticación" icon="key" href="/es/api-reference/authentication">
24-
Integra de forma segura tus aplicaciones con la API de Trophy utilizando claves de API.
28+
Autentíquese con claves de API de aplicación con alcance de usuario o claves de API de administración a nivel de cuenta.
2529
</Card>
2630
<Card
2731
title="Límite de solicitudes"
2832
icon="circle-gauge"
2933
href="/es/api-reference/rate-limiting"
3034
>
31-
Aprende sobre la API de Trophy y la Límite de solicitudes de solicitudes.
35+
Aprenda sobre la API de Trophy y el límite de solicitudes.
36+
</Card>
37+
<Card title="Idempotencia" icon="repeat" href="/es/api-reference/idempotency">
38+
Aprenda cómo prevenir efectos secundarios no deseados al reintentar solicitudes.
39+
</Card>
40+
<Card title="Errores" icon="circle-exclamation" href="/es/api-reference/errors">
41+
Códigos de estado HTTP comunes para autenticación, límites de velocidad y eventos métricos.
3242
</Card>
33-
<Card title="SDKs" icon="code-xml" href="/es/api-reference/client-libraries">
34-
Utiliza los SDKs con tipado seguro de Trophy para integrar con la API.
43+
<Card title="SDK" icon="code-xml" href="/es/api-reference/client-libraries">
44+
Use los SDK de tipo seguro de Trophy para integrar con la API.
3545
</Card>
3646
</CardGroup>
3747

38-
## Obtener soporte {#get-support}
48+
## Obtenga soporte {#get-support}
3949

40-
¿Quieres ponerte en contacto con el equipo de Trophy? Comunícate con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
50+
¿Desea ponerse en contacto con el equipo de Trophy? Comuníquese con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudar!
Lines changed: 130 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,152 @@
11
---
22
title: Bienvenido a Trophy
3-
description: Documentación de Trophy para APIs de gamificación, guías de inicio
4-
rápido y tutoriales.
3+
description: Trophy es la capa de gamificación para aplicaciones de consumo.
4+
Crea puntos, logros, rachas y clasificaciones en minutos con las API y SDK
5+
prediseñadas de Trophy.
6+
og:description: Trophy es la capa de gamificación para aplicaciones de consumo.
7+
Crea puntos, logros, rachas y clasificaciones en minutos con las API y SDK
8+
prediseñadas de Trophy.
59
---
610

7-
Trophy es un conjunto de herramientas fácil de usar para desarrolladores que permite crear experiencias de producto gamificadas en cualquier aplicación móvil o web.
11+
import SdkInstallCommand from "../../snippets/sdk-install-command.mdx";
12+
import VerifiedFirstEvent from "../../snippets/verified-first-event.mdx";
13+
import MetricChangeResponseBlock from "../../snippets/metric-change-response-block.mdx";
814

9-
Facilita la creación de funciones como [Logros](/es/features/achievements), [Rachas](/es/features/streaks), [Puntos](/es/features/points) y [Clasificaciones](/es/features/leaderboards) con solo unas pocas líneas de código, y puede enviar [correos electrónicos](/es/features/emails) y [Notificaciones push](/es/features/push-notifications) gamificados para aumentar tu retención y engagement.
15+
Trophy es la capa de gamificación para aplicaciones de consumo. Crea puntos, logros, rachas y clasificaciones en minutos con las API y SDK prediseñadas de Trophy.
16+
17+
## Primeros pasos {#getting-started}
18+
19+
Instala un SDK de Trophy para rastrear la actividad de los usuarios y potenciar puntos, logros, rachas y clasificaciones en tu aplicación.
20+
21+
<SdkInstallCommand />
22+
23+
<CardGroup cols={3}>
24+
<Card title="Inicio rápido" icon="circle-play" href="/es/getting-started/quickstart">
25+
Configura una cuenta de Trophy y crea tu primera funcionalidad en cinco minutos.
26+
</Card>
27+
<Card title="Usa la API REST" icon="code" href="/es/api-reference/introduction">
28+
Aprende a usar la API REST para integrar Trophy en tu aplicación.
29+
</Card>
30+
<Card
31+
title="Ver un ejemplo completo"
32+
icon="github"
33+
href="https://github.com/trophyso/example-study-platform/tree/demo"
34+
>
35+
Aplicación de ejemplo completa con un stack de gamificación completo usando Trophy.
36+
</Card>
37+
</CardGroup>
38+
39+
## Uso de agentes de IA {#using-ai-agents}
40+
41+
Conecta los servidores MCP de Trophy para que los agentes puedan leer documentación en tiempo real y configurar tu cuenta durante la integración.
42+
43+
<Tip>
44+
Se recomienda usar los servidores MCP de Trophy para una experiencia de configuración y desarrollo más rápida.
45+
</Tip>
46+
47+
<CardGroup cols={3}>
48+
<Card title="MCP de documentación" icon="book-open" href="/es/mcp/docs-mcp-server/introduction">
49+
Búsqueda de documentación en tiempo real para agentes de IA.
50+
</Card>
51+
<Card title="MCP de cuenta" icon="cog" href="/es/mcp/account-mcp-server/introduction">
52+
Configura tu cuenta de Trophy usando agentes de IA.
53+
</Card>
54+
<Card title="Mejores prácticas" icon="circle-check" href="/es/mcp/best-practice">
55+
Configuración recomendada para usar ambos servidores MCP juntos.
56+
</Card>
57+
</CardGroup>
58+
59+
## Envía tu primer evento {#send-your-first-event}
60+
61+
Todas las funciones de gamificación están impulsadas por [eventos de métricas](/es/features/events). Aquí te mostramos cómo enviar tu primer evento usando un SDK de Trophy:
62+
63+
<VerifiedFirstEvent />
64+
65+
La respuesta incluye los cambios en el estado de gamificación como resultado del evento, incluyendo:
66+
- El nuevo valor total de la métrica del usuario
67+
- Cualquier logro desbloqueado recientemente
68+
- Nuevos totales de Puntos y recompensas
69+
- Un objeto de Racha actualizado
70+
- Cualquier nueva posición en las Clasificaciones
71+
72+
Usa esta respuesta para reaccionar a los cambios en el estado de gamificación del usuario e impulsar elementos de UI.
73+
74+
<MetricChangeResponseBlock />
75+
76+
## Construye según el caso de uso {#build-by-use-case}
77+
78+
Para obtener más información sobre cómo construir funciones de gamificación comunes usando Trophy, consulta las siguientes guías:
1079

1180
<CardGroup>
12-
<Card title="Conceptos de Trophy" icon="book-open" href="/es/features">
13-
Familiarízate con el modelo mental de gamificación en Trophy.
81+
<Card title="Logros" icon="trophy" href="/es/guides/how-to-build-an-achievements-feature">
82+
Desbloquea logros a partir del progreso o acciones únicas.
83+
</Card>
84+
<Card title="Rachas" icon="flame" href="/es/guides/how-to-build-a-streaks-feature">
85+
Impulsa ciclos de hábitos diarios o semanales con detección de zona horaria integrada.
86+
</Card>
87+
<Card title="Puntos" icon="sparkle" href="/es/guides/how-to-build-an-xp-feature">
88+
Otorga puntos desde acciones dentro de la aplicación y configura niveles e impulsos.
1489
</Card>
1590
<Card
16-
title="Inicio rápido"
17-
icon="circle-play"
18-
href="/es/getting-started/quickstart"
91+
title="Clasificaciones"
92+
icon={
93+
<svg
94+
width="20"
95+
height="18"
96+
viewBox="0 0 20 18"
97+
fill="none"
98+
xmlns="http://www.w3.org/2000/svg"
99+
className="text-primary dark:text-primary-light"
100+
>
101+
<path
102+
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"
103+
fill="currentColor"
104+
/>
105+
</svg>
106+
}
107+
href="/es/guides/how-to-build-a-leaderboards-feature"
19108
>
20-
Integra Trophy en tu backend en menos de 10 minutos.
109+
Crea clasificaciones recurrentes o únicas.
21110
</Card>
22-
<Card title="Guías" icon="rocket" href="/es/guides">
23-
Usa Trophy para crear soluciones prácticas a casos de uso comunes de gamificación.
111+
<Card title="Correos electrónicos" icon="mail" href="/es/features/emails">
112+
Correos electrónicos del ciclo de vida impulsados por rachas, logros y actividad.
24113
</Card>
25-
<Card title="Referencia del API" icon="code" href="/es/api-reference">
26-
Explora el API de Trophy y descubre lo que es posible.
114+
<Card title="Notificaciones push" icon="bell" href="/es/features/push-notifications">
115+
Flujos de notificaciones automatizadas usando datos de gamificación.
27116
</Card>
28117
</CardGroup>
29118

30-
## Por qué Trophy {#why-trophy}
119+
## Kit de interfaz de usuario {#ui-kit}
120+
121+
Implementa interfaces de gamificación más rápido con la biblioteca de componentes React de Trophy, construida sobre shadcn/ui y diseñada para trabajar con las estructuras de datos de Trophy.
122+
123+
<Card title="Kit de interfaz de usuario" icon="shapes" href="https://ui.trophy.so">
124+
Explora componentes de interfaz preconstruidos para rachas, logros, clasificaciones, puntos y más.
125+
</Card>
126+
127+
## Lista de verificación de producción {#production-checklist}
31128

32-
<Frame>
33-
<img height="200" width="100%" noZoom src="https://trophy.so/opengraph-image" />
34-
</Frame>
129+
Antes de implementar tu integración en producción, revisa los pasos recomendados en la lista de verificación de producción:
35130

36-
Si tu objetivo es que tus usuarios creen un hábito regular de usar tu aplicación —para aprender algo, publicar contenido o incluso hacer ejercicio— la gamificación podría ser para ti.
131+
<Card title="Lista de verificación de producción" icon="list-check" href="/es/getting-started/production-checklist">
132+
Pasos recomendados para asegurar que tu integración esté lista para producción.
133+
</Card>
37134

38-
Ha sido comprobado por Duolingo y otros que la gamificación aumenta predeciblemente la retención e incrementa el engagement en la plataforma.
135+
## Precios {#pricing}
39136

40-
Pero construir gamificación a escala puede ser complicado. Tienes una base de usuarios global, todos en diferentes zonas horarias, todos con diferentes patrones de uso que necesitan ser medidos y optimizados en tiempo real. Además, quieres ejecutar experimentos para probar diferentes enfoques y ver cómo impactan la retención, pero esto requiere cambios constantes en el código, lo que retrasa el trabajo en tu producto principal.
137+
Trophy mide el uso por **usuarios activos mensuales (MAU)**. Un MAU es un usuario que envía al menos un [evento de métrica](/es/features/events) en un mes calendario determinado. No se te cobra por usuarios abandonados que dejan de enviar eventos.
41138

42-
Trophy elimina el trabajo pesado involucrado en crear funciones como logros, rachas, sistemas de puntos y clasificaciones, al mismo tiempo que proporciona APIs confiables y escalables para lanzar experiencias de gamificación más rápido que construyéndolas internamente. Además, ofrece una plataforma web para configurar, medir y experimentar fácilmente con la experiencia del producto sin cambios constantes en el código.
139+
El nivel gratuito incluye **1,000 MAU**. Los planes de pago comienzan en $25/mes con cargos por excedente.
140+
141+
<CardGroup cols={2}>
142+
<Card title="Facturación" icon="gauge" href="/es/account/billing">
143+
Nivel gratuito, planes de pago, asignaciones y excedentes.
144+
</Card>
145+
<Card title="Calculadora de precios" icon="calculator" href="https://trophy.so/pricing">
146+
Obtén un estimado de costos mensuales según el uso esperado.
147+
</Card>
148+
</CardGroup>
43149

44-
## Obtener soporte {#get-support}
150+
## Obtén soporte {#get-support}
45151

46-
¿Quieres ponerte en contacto con el equipo de Trophy? Escríbenos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
152+
¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!

0 commit comments

Comments
 (0)