Saltar al contenido principal
Esta guía describe el proceso completo para añadir una funcionalidad de logros a tu aplicación web o móvil usando Trophy. A modo ilustrativo, usaremos el ejemplo de una plataforma de estudio que utiliza logros para incentivar y recompensar a los usuarios por ver tarjetas de memoria.
Para ver un ejemplo completamente funcional de esto en la práctica, consulta la demostración en vivo o el repositorio de github.

​
Requisitos previos

  • Una cuenta de Trophy
  • Aproximadamente 10 minutos

​
Configuración de Trophy

En Trophy, las Métricas son los componentes fundamentales de la gamificación y modelan las diferentes interacciones que los usuarios realizan con tu producto. En esta guía, la interacción que nos interesa es flashcards-viewed, pero puedes crear una métrica que mejor represente la interacción en torno a la cual quieres construir logros. En el panel de Trophy, dirígete a la página de métricas y crea una métrica.
Una vez que hayas creado tu métrica, dirígete a la página de logros y crea los logros que desees. Puedes encontrar todos los detalles sobre los tipos de logros y los diferentes casos de uso en la documentación de logros. Para los propósitos de esta guía, hemos configurado un par de logros basados en un número creciente de tarjetas volteadas:
  • 10 tarjetas de estudio
  • 50 tarjetas de estudio
  • 100 tarjetas de estudio
  • 250 tarjetas de estudio
  • 1,000 tarjetas de estudio
También hemos configurado algunos logros relacionados con Rachas, pero no entraremos en detalle sobre estos en esta guía.
Para una guía completa sobre cómo agregar una función de rachas a tu aplicación web o móvil, consulta nuestra guía completa.
En Trophy rastrear las interacciones de usuarios enviando Events desde tu código a las API de Trophy contra una métrica específica. Cuando se registran eventos para un usuario específico, cualquier logro vinculado a la métrica especificada se completará automáticamente si se cumplen los requisitos. Esto es lo que hace que crear experiencias gamificadas con Trophy sea tan fácil: realiza todo el trabajo por ti detrás de escena.

​
Instalar Trophy SDK

Para interactuar con Trophy desde tu código, utilizarás el Trophy SDK disponible en la mayoría de los lenguajes de programación principales. Instala el Trophy SDK: 
npm install @trophyso/node
A continuación, obtén tu clave API desde la página de integración de Trophy y agrégala como una variable de entorno solo del lado del servidor. 
TROPHY_API_KEY='*******'
Asegúrate de no exponer tu clave API en código del lado del cliente.

​
Rastrear Interacciones de Usuarios

Para rastrear un evento (interacción de usuario) contra tu métrica, utiliza la API de cambio de métrica. 
curl -X POST https://app.trophy.so/api/metrics/flashcards-flipped/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 750
}'
La respuesta a esta llamada API es el conjunto completo de cambios a cualquier funcionalidad que hayas creado con Trophy, incluidos los logros que se desbloquearon como resultado del evento.
Response
{
  "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"
    }
  ],
  ...
}
Valida que esto funciona verificando el panel de control de Trophy.

​
Mostrar Logros

Tienes varias opciones para mostrar logros en tu aplicación. Aquí veremos las opciones más comunes.

​
Notificaciones Emergentes

Podemos usar la respuesta del API de cambio de métrica para mostrar notificaciones emergentes (o ‘toasts’) cuando los usuarios completan logros. Aquí hay un ejemplo de esto en acción:
Achievement Completed Pop-up
// Sends event to Trophy
const response = await viewFlashcard();

if (!response) {
  return;
}

// Show toasts if the user has unlocked any new achievements
response.achievements.forEach((achievement) => {
  toast({
    title: achievement.name,
    description: achievement.description,
    image: {
      src: achievement.badgeUrl,
      alt: achievement.name,
    },
  });
});
Si quieres reproducir efectos de sonido, usa el API de Audio HTML5 y siéntete libre de usar estos archivos de audio que recomendamos.

​
Mostrar Logros de Usuario

Para obtener todos los logros que un usuario ha completado, usa el API de logros de usuario. 
curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/achievements \
  --header 'X-API-KEY: <api-key>'
También puedes obtener logros incompletos al mismo tiempo pasando includeIncomplete como 'true'.

​
Mostrar Todos los Logros

Si en cambio quieres mostrar todos los logros que has configurado en Trophy como parte de una interfaz de usuario globalmente accesible que no esté vinculada a un usuario en particular, puedes usar el API de todos los logros. 
curl --request GET \
  --url https://api.trophy.so/v1/achievements \
  --header 'X-API-KEY: <api-key>'

​
Estadísticas de Finalización de Logros

Tanto el API de logros de usuario como el API de todos los logros incluyen estadísticas de finalización como completions (el número de usuarios que han completado un logro) y rarity (el porcentaje de usuarios que han completado un logro).

​
Analíticas

La página de logros en Trophy muestra cuántos usuarios han completado cada logro que has configurado.
Además, la página de analíticas de cualquier métrica en Trophy incluye un gráfico que muestra el progreso de los usuarios a través de tus Logros.

​
Obtener Soporte

¿Quieres ponerte en contacto con el equipo de Trophy? Comunícate con nosotros por correo electrónico. ¡Estamos aquí para ayudarte!