> ## 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.
# Logros
> Aprende a usar Logros en una experiencia de producto gamificada con Trophy.
¿Qué son los Logros?
Los logros son recompensas que los usuarios pueden desbloquear al usar tu plataforma. Se pueden usar para recompensar a los usuarios por hacer un progreso continuo en los recorridos principales del usuario, o para motivarlos a explorar funciones más nuevas.
Los logros funcionan mejor cuando están diseñados para incentivar a los usuarios a realizar acciones que probablemente aumenten la retención.
Usa las [analíticas de métrica](/es/features/metrics#metric-analytics) de Trophy para comparar
la retención de cada interacción de usuario, luego configura logros en torno a
estas interacciones para maximizar el impacto en la retención.
Aquí revisaremos los tipos de logros que puedes construir con Trophy, las diferentes formas de usarlos y cómo integrarlos en tu plataforma.
Mira a Charlie ejecutar un recorrido usando logros en una aplicación NextJS:
Tipos de Logros
Trophy ofrece cuatro tipos de logros: [Métrica](#metric-achievements), [API](#api-achievements), [Racha](#streak-achievements) y [Logros compuestos](#composite-achievements), detallados a continuación.
Logros de Métrica
Los logros de métrica están vinculados a [Métricas](/es/features/metrics) y son ideales cuando quieres incentivar a los usuarios a realizar la misma acción una y otra vez.
Tomemos el ejemplo de una plataforma de estudio que usa Trophy para animar a los usuarios a ver más tarjetas de estudio con logros de métrica de la siguiente manera:
* 1,000 tarjetas de estudio
* 2,500 tarjetas de estudio
* 5,000 tarjetas de estudio
* 10,000 tarjetas de estudio
* 25,000 tarjetas de estudio
* 50,000 tarjetas de estudio
En este caso crearías una métrica llamada *Tarjetas Volteadas* y crearías logros vinculados a la métrica para cada hito.
Dado que estos logros están directamente vinculados a la métrica *Tarjetas Volteadas*, Trophy rastreará automáticamente cuándo los usuarios desbloquean estos logros a medida que [incrementan la métrica](/es/features/events#tracking-metric-events).
Cuando se desbloquean logros, Trophy incluye información sobre los logros desbloqueados en la respuesta del [API de Eventos](/es/api-reference/endpoints/metrics/send-a-metric-change-event) y activa automáticamente [Correos de Logros](/es/features/emails#achievement-emails) si está configurado.
```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": "Write 500 words in the app.",
"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"
},
"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
}
}
]
}
},
"leaderboards": {
"daily_champions": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
"key": "daily_champions",
"name": "Daily Champions",
"description": null,
"rankBy": "metric",
"runUnit": null,
"runInterval": 0,
"maxParticipants": 100,
"metricName": "Flashcards Flipped",
"metricKey": "flashcards-flipped",
"threshold": 10,
"start": "2025-01-01",
"end": null,
"previousRank": 50,
"rank": 12
}
}
}
```
Logros de API
Los logros de API solo se pueden completar una vez y son útiles para recompensar a los usuarios por realizar acciones específicas.
Ejemplos comunes incluyen:
* Un usuario completando su perfil después de registrarse
* Un usuario vinculando su cuenta de redes sociales a una plataforma
* Un usuario compartiendo su experiencia con el producto en redes sociales
Los logros de API sirven como una forma sencilla de recompensar a los usuarios por completar cualquier acción que consideres importante para la retención.
Al igual que los logros de métricas, los logros de API también pueden activar [Correos de Logros](/es/features/emails#achievement-emails) automatizados si está configurado.
Logros de Racha
Los logros de racha están directamente vinculados a la [Racha](/es/features/streaks) de un usuario y se desbloquean automáticamente cuando los usuarios alcanzan una longitud de racha específica.
Puedes crear tantos logros de racha como desees para longitudes de racha crecientes, por ejemplo 7 días, 30 días y 365 días para motivar a los usuarios a usar tu aplicación cada vez más.
Al igual que los logros de métricas y API, puedes agregar un nombre personalizado y asignar una insignia a los logros de racha.
Logros Compuestos
Los logros compuestos se desbloquean automáticamente cuando un usuario ha completado todos los logros prerequisitos que selecciones. Son ideales para crear recompensas por niveles o de maestría que reconocen a los usuarios que han alcanzado un conjunto específico de hitos.
Por ejemplo, podrías crear un logro compuesto "Maestro del estudio" que se desbloquea cuando un usuario ha completado:
* 1,000 tarjetas de estudio
* Racha de 7 días
* Completar la incorporación
Los logros compuestos son útiles para crear rutas de progresión y fomentar que los usuarios interactúen en diferentes áreas de tu aplicación. Al igual que otros tipos de logros, pueden activar [correos electrónicos de logros](/es/features/emails#achievement-emails) cuando se desbloquean.
Crear Logros
Para crear nuevos logros, dirígete a la [página de logros](https://app.trophy.so/achievements) en el panel de Trophy y haz clic en el botón **Nuevo logro**:
Ingresa un nombre para el logro. Este se devolverá desde las API y estará disponible para su uso en correos electrónicos y otras áreas de Trophy según corresponda.
Ingresa una breve descripción del logro. Esta se devolverá desde las API
y estará disponible para su uso en correos electrónicos y otras áreas de Trophy
según corresponda.
Puedes agregar una insignia subiendo una imagen o ingresando una URL de imagen personalizada.
La URL se devuelve en las respuestas de la API y se usa en correos electrónicos y otras áreas de
Trophy según corresponda.
Elige cómo quieres que se desbloquee este Logro.
* Elegir **Métrica** significa que el logro se desbloqueará automáticamente cuando el total de la métrica del usuario alcance el valor de activación del logro.
* Elegir **Racha** significará que el logro se desbloqueará automáticamente cuando la duración de la racha del usuario alcance el valor del disparador del logro.
* Elegir **Llamada API** significará que el logro solo se desbloqueará cuando tu código lo marque explícitamente como completado mediante una solicitud a la [API de completar logro](/es/api-reference/endpoints/achievements/mark-an-achievement-as-completed).
* Elegir **Compuesto** significará que el logro se desbloqueará automáticamente cuando el usuario haya completado todos los logros prerequisito que selecciones.
Una vez que hayas elegido el tipo de disparador para el logro, debes configurar los ajustes del disparador.
* Si elegiste el disparador **Métrica**, necesitarás elegir la métrica y el valor total del usuario que debe desbloquear el logro cuando se alcance.
* Si elegiste el disparador **Racha**, necesitarás establecer la duración de la racha que debe desbloquear el logro.
* Si elegiste el disparador **Llamada API**, necesitarás elegir una referencia única `key` que usarás para completar el logro a través de la [API](/es/api-reference/endpoints/achievements/mark-an-achievement-as-completed).
* Si elegiste el disparador **Compuesto**, necesitarás seleccionar los logros prerequisito que deben estar completados para que este logro se desbloquee. El logro compuesto se desbloqueará automáticamente cuando un usuario complete el último prerequisito.
Puedes asignar filtros de atributos a un logro para restringir aún más quién puede desbloquearlo y cuándo.
* Para limitar un logro de **Métrica** a que solo se aplique a eventos con [atributos de evento personalizados](/es/features/events#custom-event-attributes) específicos, agrega uno o más filtros en la sección **Atributos de Evento**.
* Para limitar cualquier tipo de logro a que solo se aplique a un usuario con uno o más [atributos de usuario personalizados](/es/features/users#custom-user-attributes) específicos, agrega atributos y los valores deseados en la sección **Atributos de Usuario**.
Cuando estableces múltiples filtros de atributos de evento, todos deben coincidir para que se aplique el logro de métrica. En las respuestas de API, `eventAttributes` es el campo canónico e `eventAttribute` está obsoleto por compatibilidad heredada.
Guarda el nuevo logro.
Gestión de Logros
Trophy tiene herramientas integradas que te ayudan a probar y controlar qué logros se pueden desbloquear, por quién y cuándo, sin afectar producción.
Estados de Logro
Aquí tienes una descripción general de los diferentes estados de logro y lo que significan.
**Inactivo**
Todos los logros se crean como inactivos. Los logros inactivos no se pueden completar y no se devuelven en ninguna API de logros. Los usuarios no los verán hasta que los actives.
**Activo**
Cuando activas un logro, lo pones 'en producción'. Los usuarios pueden completarlo y se devolverá en todas las API de logros.
**Bloqueado**
Cuando bloqueas un logro, los usuarios que aún no lo hayan desbloqueado ya no podrán desbloquearlo, pero los usuarios que ya lo hayan desbloqueado no se verán afectados.
Los logros bloqueados solo se devuelven en las API para usuarios que ya los han conseguido.
Flujo de Trabajo de Logros
Los logros se pueden mover a través de diferentes estados según el siguiente flujo de trabajo:
```mermaid theme={null}
flowchart LR
A@{ shape: rounded, label: "Inactive" }
B@{ shape: rounded, label: "Active" }
C@{ shape: rounded, label: "Active" }
D@{ shape: rounded, label: "Locked" }
E@{ shape: rounded, label: "Archived" }
F@{ shape: rounded, label: "Locked" }
G@{ shape: rounded, label: "Active" }
H@{ shape: rounded, label: "Archived" }
A-->B
C-->D
D-->E
C-->E
F-->G
F-->H
style A fill:#FDFDEA,stroke:#F7F0D5
style B fill:#F2FAF7,stroke:#E2F6E6
style C fill:#F2FAF7,stroke:#E2F6E6
style D fill:#eee,stroke:#ddd
style E fill:#ddd,stroke:#ccc
style F fill:#eee,stroke:#ddd
style G fill:#F2FAF7,stroke:#E2F6E6
style H fill:#ddd,stroke:#ccc
```
Completar Logros
Si estás usando logros de métrica, no es necesario *completar* logros explícitamente. Una vez que hayas configurado el [seguimiento de métricas](/es/features/events#tracking-metric-events) en tu código, todos los logros vinculados a la métrica se rastrearán automáticamente.
De manera similar, si estás usando logros de racha, todos los logros relacionados con la racha del usuario se desbloquearán automáticamente cuando un usuario alcance la longitud de racha respectiva.
Los logros compuestos también se completan automáticamente. Se desbloquean tan pronto como un usuario ha completado todos sus logros prerequisito. No se necesitan llamadas API adicionales.
Sin embargo, si está utilizando logros de API, deberá marcarlos como completados para cada usuario según corresponda. Para ello, puede usar la [API de Completar Logro](/es/api-reference/endpoints/achievements/mark-an-achievement-as-completed) utilizando el `key` del logro que desea completar.
Esto devolverá una respuesta que contiene los detalles del logro completado que se puede usar en cualquier flujo de trabajo posterior a la finalización, como mostrar una notificación dentro de la aplicación.
```json Response theme={null}
{
"completionId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"achievement": {
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
"trigger": "api",
"name": "Finish onboarding",
"description": "Complete the onboarding process.",
"badgeUrl": "https://example.com/badge.png",
"key": "finish-onboarding",
"achievedAt": "2021-01-01T00:00:00Z"
}
}
```
Retroactividad de Logros
Por defecto, cada vez que mueve un logro al estado 'Activo' [status](#managing-achievements), Trophy verificará si algún usuario existente cumple con los requisitos del logro y lo completará para ellos en segundo plano.
Esto significa que cuando lance nuevos logros a producción, o edite un logro activo existente, la retroactividad ocurrirá automáticamente.
Cuando los logros se completan de esta manera, los usuarios no reciben
notificaciones de que esto ha sucedido. Esto es para evitar que los cambios a sus
logros en Trophy resulten en que los usuarios reciban muchas notificaciones.
Puede verificar cuántos usuarios han completado logros en cualquier momento en la [página de logros](https://app.trophy.so/achievements) en el panel de Trophy. La columna *Usuarios* en los logros puede actualizarse durante la retroactividad.
Uso de Insignias
Puede asignar una insignia a cualquier logro cargando una imagen—Trophy la sirve y devuelve el URL—o proporcionando su propia URL de imagen. Las respuestas de API relevantes incluyen ese valor en `badgeUrl` para usarse como el `src` en etiquetas ``.
```json Response {8} theme={null}
{
"completionId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"achievement": {
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
"trigger": "api",
"name": "Finish onboarding",
"description": "Complete the onboarding process.",
"badgeUrl": "https://example.com/badge.png",
"key": "finish-onboarding",
"achievedAt": "2021-01-01T00:00:00Z"
}
}
```
Mostrar Logros
Trophy tiene varias APIs que permiten mostrar logros dentro de tus aplicaciones. Aquí veremos las diferentes formas de usarlas y los tipos de interfaces de usuario que puedes construir.
Consulta nuestra [guía completa](/es/guides/how-to-build-an-achievements-feature) sobre
cómo añadir una funcionalidad de logros a tu aplicación para más detalles.
Todos los Logros
Para mostrar una vista general de alto nivel de todos los logros que los usuarios pueden completar, usa el [endpoint de todos los logros](/es/api-reference/endpoints/achievements/all-achievements). Usa estos datos para construir una interfaz que ofrezca a los usuarios una idea de las rutas de progresión dentro de tu aplicación.
El endpoint de todos los logros devuelve una lista de todos los logros dentro de tu cuenta de Trophy. Cada logro devuelto también incluye `completions` (el número de usuarios que han completado el logro) y `rarity` (el porcentaje de usuarios que han completado el logro) de la siguiente manera:
```json Response [expandable] theme={null}
[
{
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
"trigger": "api",
"name": "Finish onboarding",
"description": "Complete the onboarding process.",
"badgeUrl": "https://example.com/badge.png",
"key": "finish-onboarding",
"completions": 8,
"rarity": 80
},
{
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123683",
"trigger": "metric",
"name": "500 Flashcards Flipped",
"description": "View 500 flashcards in the app.",
"badgeUrl": "https://example.com/badge.png",
"metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123683",
"metricName": "Flashcards Flipped",
"metricValue": 500,
"completions": 6,
"rarity": 60
},
{
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123684",
"trigger": "streak",
"name": "10 days of exercise",
"description": "Exercise at least once a day for 10 days in a row.",
"badgeUrl": "https://example.com/badge.png",
"streakLength": 10,
"completions": 2,
"rarity": 20
},
{
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123685",
"trigger": "achievement",
"name": "Study Master",
"description": "Complete all introductory milestones.",
"badgeUrl": "https://example.com/badge.png",
"achievementIds": [
"5100fe51-6bce-6j44-b0hs-bddc4e123682", "5100fe51-6bce-6j44-b0hs-bddc4e123683", "5100fe51-6bce-6j44-b0hs-bddc4e123684"
],
"completions": 1,
"rarity": 5
}
]
```
Logros del Usuario
Si en cambio estás construyendo elementos de interfaz específicos del usuario, usa el [endpoint de logros del usuario](/es/api-reference/endpoints/users/get-a-users-completed-achievements) para devolver los logros que un usuario específico ha completado.
También puedes incluir logros que un usuario aún no ha completado incluyendo
el parámetro de consulta `includeIncomplete=true`.
Analíticas de Logros
Si tienes logros configurados para cualquiera de tus [Métricas](/es/features/metrics), entonces la página de analíticas de métricas muestra un gráfico que te indica el progreso actual de todos los usuarios de la siguiente manera:
Preguntas Frecuentes
Usa logros de métricas para recompensar a los usuarios por realizar la misma acción una y otra vez, y para incentivarlos a hacerlo más.
Usa logros de racha para recompensar a los usuarios por mantener su racha.
Usa logros de API cuando quieras recompensar a los usuarios por realizar acciones específicas que solo necesitan hacer una vez.
Usa logros compuestos cuando quieras crear recompensas por niveles o de maestría que se desbloqueen cuando los usuarios completen un conjunto específico de logros previos.
Los Logros, como toda gamificación, ofrecen la mejor retención cuando están estrechamente alineados con la razón principal por la que el usuario usa tu plataforma.
Usa los [análisis de métricas](/es/features/metrics#metric-analytics) de Trophy para comparar la retención de cada interacción del usuario, luego configura logros en torno a estas interacciones para maximizar el impacto en la retención.
Obtener Soporte
¿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!
