Saltar al contenido principal
Esta guía describe el proceso completo para agregar una funcionalidad de clasificaciones a tu aplicación web o móvil usando Trophy. Con fines ilustrativos, utilizaremos el ejemplo de una plataforma de estudio que usa una clasificación diaria para crear competencia amistosa en torno a la visualización de 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 represente mejor la interacción en torno a la cual deseas crear clasificaciones. 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 clasificaciones y crea las clasificaciones que desees. Puedes encontrar todos los detalles sobre los tipos de clasificaciones y los diferentes casos de uso en la documentación de clasificaciones.
Para los propósitos de esta guía, hemos configurado una clasificación diaria que rastrea el XP total que un usuario gana al ver tarjetas de estudio.
Para una guía completa sobre cómo agregar una función de XP a tu aplicación web o móvil, consulta nuestra guía completa.
En Trophy rastreas las interacciones de los usuarios enviando Eventos desde tu código a las API de Trophy contra una métrica específica. Cuando se registran eventos para un usuario específico, Trophy actualiza automáticamente su clasificación en cada clasificación de la que forma parte. Esto es lo que hace que construir experiencias gamificadas con Trophy sea tan fácil, hace todo el trabajo por ti en segundo plano.

​
Instalando Trophy SDK

Para interactuar con Trophy desde tu código, utilizarás el Trophy SDK disponible en la mayoría de los principales lenguajes de programación. Instala el Trophy SDK: 
npm install @trophyso/node
A continuación, obtén tu clave de 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 de API en código del lado del cliente.

​
Rastreando 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 de API es el conjunto completo de cambios a cualquier función que hayas construido con Trophy, incluyendo cualquier cambio en su clasificación en cualquier clasificación de la que formen parte.
Response
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  ...,
  "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
    }
  }
}
Valida que esto esté funcionando revisando el panel de control de Trophy.

​
Mostrando Clasificaciones

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

​
Notificaciones Emergentes

Podemos utilizar la respuesta de la API de cambio de métrica para mostrar notificaciones emergentes (o ‘toasts’) cuando los usuarios suben en las clasificaciones. Aquí hay un ejemplo de esto en acción:
Leaderboard Rank Up Pop-up
// Sends event to Trophy
const response = await viewFlashcard();

if (!response) {
  return;
}

const leaderboard = response.leaderboards["daily_champions"];

if (!leaderboard) {
  return;
}

// Show toasts if the user moved up the leaderboard
if (leaderboard.rank > leaderboard.previousRank) {
  toast({
    title: "You're on the move!,
    description: `You moved up ${leaderboard.previousRank - leaderboard.rank} places!,
  });
}
Si quieres reproducir efectos de sonido, utiliza la API de Audio HTML5 y siéntete libre de usar estos archivos de audio que recomendamos.

​
Mostrar las Clasificaciones

Para obtener una clasificación y sus rankings más actualizados, utiliza la API de clasificación. 
curl --request GET \
  --url https://api.trophy.so/v1/leaderboards/{key} \
  --header 'X-API-KEY: <api-key>'
También puedes utilizar el parámetro run con la fecha de la ‘ejecución’ pasada específica de una clasificación para la cual deseas obtener datos.
Aquí hay un ejemplo de los datos devueltos por la API de clasificación:
Response
{
  "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
  "name": "Weekly Flashcard Challenge",
  "key": "weekly-challenge",
  "rankBy": "metric",
  "metricKey": "flashcards-flipped",
  "metricName": "Flashcards Flipped",
  "pointsSystemKey": null,
  "pointsSystemName": null,
  "description": "Compete weekly to see who views the most flashcards",
  "status": "active",
  "start": "2025-01-01",
  "end": null,
  "maxParticipants": 100,
  "runUnit": "day",
  "runInterval": 7,
  "rankings": [
    {
      "userId": "user-123",
      "userName": "Alice Johnson",
      "rank": 1,
      "value": 5000
    },
    {
      "userId": "user-456",
      "userName": "Bob Smith",
      "rank": 2,
      "value": 4500
    },
    {
      "userId": "user-789",
      "userName": "Charlie Brown",
      "rank": 3,
      "value": 4200
    }
  ]
}

​
Mostrar el Historial de Rango del Usuario

Utiliza la API de clasificación de usuario para obtener datos sobre cómo ha cambiado el rango de un usuario específico a lo largo del tiempo en una clasificación particular. 
curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/leaderboards/{key} \
  --header 'X-API-KEY: <api-key>'
Aquí hay un ejemplo de los datos devueltos por la API de rankings de clasificación de usuario, que incluye el rango actual del usuario en el atributo rank y un array de rangos anteriores en el atributo history:
Response
{
  "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
  "name": "Weekly Word Count Challenge",
  "key": "weekly-words",
  "rankBy": "metric",
  "metricKey": "flashcards-flipped",
  "metricName": "Flashcards Flipped",
  "pointsSystemKey": null,
  "pointsSystemName": null,
  "description": "Compete weekly to see who writes the most words",
  "start": "2025-01-01",
  "end": null,
  "maxParticipants": 100,
  "runUnit": "day",
  "runInterval": 7,
  "rank": 2,
  "value": 4500,
  "history": [
    {
      "timestamp": "2025-01-15T10:30:00Z",
      "previousRank": null,
      "rank": 5,
      "previousValue": null,
      "value": 1000
    },
    {
      "timestamp": "2025-01-15T14:15:00Z",
      "previousRank": 5,
      "rank": 3,
      "previousValue": 1000,
      "value": 3000
    },
    {
      "timestamp": "2025-01-15T18:45:00Z",
      "previousRank": 3,
      "rank": 2,
      "previousValue": 3000,
      "value": 4500
    }
  ]
}

​
Analíticas

La página de clasificaciones en Trophy muestra cuántos usuarios están participando activamente en una clasificación, así como una medida de competitividad basada en cuántos cambios de rango están ocurriendo. La página de analíticas también muestra una distribución de las puntuaciones de los usuarios para ayudar a identificar grupos de usuarios dentro de las clasificaciones.
Además, la página de clasificaciones de la clasificación muestra las posiciones actuales y pasadas de una clasificación:

​
Obtener soporte

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