Saltar al contenido principal

​
¿Qué son los eventos?

Los eventos representan interacciones individuales de usuarios contra Métricas en Trophy. Un evento corresponde a una única interacción realizada por un único usuario. Cuando integras métricas en tu plataforma, estás configurando tu plataforma para transmitir continuamente eventos a tus métricas de Trophy para cada interacción de usuario. Estas interacciones luego impulsan todas las funcionalidades de gamificación que configures alrededor de estas métricas.

​
Atributos clave

​
Valor del evento

El value de un evento es la cantidad numérica que se añadirá al recuento total de la métrica del usuario como resultado de la interacción del usuario a la que se refiere.
El valor de un evento puede ser positivo o negativo, y puede ser un número entero o un decimal.

​
Atributos personalizados de eventos

Esta funcionalidad está disponible en el plan Pro
Puedes especificar varios atributos personalizados de eventos para ayudarte a rastrear información adicional relevante para tu caso de uso contra los eventos que envías a Trophy. Por ejemplo, una aplicación de aprendizaje de idiomas podría tener una métrica de ‘Preguntas completadas’ y usar un atributo personalizado de evento para almacenar si la respuesta a cada pregunta fue correcta. De manera similar, una aplicación de fitness podría usar una métrica de ‘Ejercicios completados’ y usar un atributo personalizado de evento para almacenar el peso que se utilizó en cada ejercicio y otro atributo personalizado de evento para almacenar cuánto duró el ejercicio. Usar atributos de eventos personalizados de esta manera te permite enriquecer eventos en Trophy con contexto adicional relevante para tu caso de uso y utilizarlo para impulsar características de gamificación aún más atractivas.

​
Crear Atributos

Para crear un nuevo atributo de evento personalizado, dirígete a la página de métricas en el panel de Trophy y haz clic en el botón Agregar Atributo de Evento. Asigna un nombre y una clave única al atributo; usarás la clave cuando hagas referencia al atributo en las llamadas a la API.

​
Establecer Atributos

Para establecer el valor de un atributo personalizado en un evento, pasa su valor en el objeto attributes en tu código de seguimiento de métricas.
Trophy solo establecerá valores de atributos que primero hayan sido creados en el panel. Hacemos esto para ayudarte a mantener un conjunto limpio de atributos y prevenir sobrescrituras accidentales.Si recibes un error similar al siguiente, es posible que hayas escrito mal la clave del atributo en la solicitud, o necesites crear el atributo primero en el panel de Trophy:
{
  "error": "Invalid attribute keys: device. Please ensure all attribute keys match those set up at https://app.trophy.so/metrics."
}
Aquí hay un ejemplo de un payload de evento donde se establecen los valores de dos atributos, device y duration: 
{
  "user": {
    "id": "18",
    "tz": "Europe/London"
  },
  "value": 25,
  "attributes": {
    "device": "ios",
    "duration": "120"
  }
}

​
Usar Atributos

Los atributos de eventos personalizados pueden utilizarse para impulsar desencadenadores más avanzados para logros y puntos, y pueden usarse en plantillas de correo electrónico para personalizar el texto y controlar los datos mostrados en gráficos.

​
Desencadenadores Avanzados de Características

Los atributos de eventos personalizados pueden utilizarse para configurar desencadenadores de logros o puntos que solo rastreen eventos con valores de atributos específicos. Sigue los enlaces a las páginas relevantes a continuación para obtener más información.

Disparadores de Logros

Configura logros que solo se pueden desbloquear mediante eventos con ciertos valores de atributos.

Disparadores de Puntos

Configura disparadores de puntos para otorgar puntos solo desde eventos con valores de atributos específicos.

​
Personalización de correos electrónicos

Si utilizas cualquier correo electrónico de Trophy, los atributos de eventos se pueden usar para personalizar los datos mostrados en ciertos bloques de correo electrónico. En primer lugar, cuando utilices variables basadas en métricas en el texto del correo electrónico, puedes usar atributos de eventos para controlar con mayor precisión a qué datos hace referencia la variable. Por ejemplo, aquí hay un caso donde usamos una variable de correo electrónico para informar a los usuarios sobre su número total de entrenamientos realizados en diferentes equipos de gimnasio, utilizando una métrica ‘Workouts’ y un atributo ‘Equipment’:
En segundo lugar, aquí hay un ejemplo donde agregamos un gráfico a un correo electrónico que muestra a los usuarios cuántos entrenamientos han realizado en bicicleta a lo largo del tiempo:
Hay un gran número de posibilidades aquí, ¡así que sé creativo!

​
Seguimiento de eventos de Métricas

Cada métrica tiene un key único que puedes usar para referenciar y rastrear eventos en tu código. Puedes encontrar el key en la página de configuración de la métrica. Para comenzar a rastrear las interacciones de usuarios como eventos en tus Métricas de Trophy, usa la API de Métricas o una de nuestras Bibliotecas cliente con tipos seguros, compatibles con la mayoría de los principales lenguajes de programación. Aquí hay un ejemplo donde una plataforma de estudio ficticia utiliza una métrica para rastrear el número de tarjetas de estudio volteadas por cada estudiante. Cada vez que un estudiante interactúa, la plataforma envía un evento a Trophy indicándole cuántas tarjetas de estudio vieron: 
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
}'
Cualquier Logro, Racha, Puntos o Clasificación que se haya configurado para esta métrica se procesará automáticamente, y la respuesta contendrá cualquier actualización del progreso del usuario que sea un resultado directo del evento ocurrido:
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"
    }
  ],
  "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
    }
  }
}
En este ejemplo, la respuesta incluye lo siguiente:
  • Los logros recién desbloqueados del usuario como resultado del evento
  • La racha más reciente del usuario como resultado del evento
  • Los puntos más recientes del usuario para cada sistema de puntos que cambió como resultado del evento
  • Los datos de clasificación más recientes del usuario para cada clasificación que cambió como resultado del evento
Con un poco de código personalizado, estos datos de respuesta se pueden utilizar para impulsar cualquier experiencia dentro de la aplicación que desees, incluyendo:
  • Activar notificaciones dentro de la aplicación
  • Efectos de sonido
  • Animaciones
Observa cómo Charlie integra el seguimiento de métricas en una aplicación simple de NextJS usando el SDK de Trophy para Node.js:

​
Eventos Idempotentes

Trophy permite garantizar la unicidad en los eventos para que los usuarios no puedan aumentar una métrica realizando la misma acción exacta una y otra vez. Por ejemplo, una aplicación de aprendizaje de idiomas podría especificar que los usuarios solo pueden aumentar la métrica lessons-completed en 1 por cada lección única completada, por lo que si completan la misma lección dos veces, solo la primera cuenta. 
curl -X POST https://app.trophy.so/api/metrics/lessons-completed/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Idempotency-Key: <lesson-123>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 1
}'
Esto ayuda a mantener tu código libre de lógica que verifique si los usuarios han completado acciones anteriormente, y en su lugar puedes confiar en que Trophy mantendrá las restricciones que necesitas. Para usar eventos idempotentes, utiliza el encabezado Idempotency-Key en la API de eventos de métricas. Más información sobre idempotencia.

​
Obtener Soporte

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