Eventos

¿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. Si estás enviando eventos en lote desde tu backend (por ejemplo, vaciados de cola, migraciones o importaciones por lotes), utiliza el endpoint de la Admin API Enviar un lote de eventos de métrica para enviar hasta 1,000 eventos de métrica en una sola solicitud. Aquí hay un ejemplo donde una plataforma de estudio ficticia está usando una métrica para rastrear el número de tarjetas didácticas volteadas por cada estudiante. Cada vez que un estudiante interactúa, la plataforma envía un evento a Trophy indicándole cuántas tarjetas 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
}'

trophy.metrics.event("flashcards-flipped", {
  user: {
    id: "18",
    email: "user@example.com",
    tz: "Europe/London",
  },
  value: 750,
});

client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=750.0,
)

$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com'
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 750
]);

$trophy->metrics->event("flashcards-flipped", $request);

MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .build()
      )
      .value(750)
      .build();

EventResponse response = client.metrics().event("flashcards-flipped", request);

response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
        },
        Value: 750,
    },
)

var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com"
};

var request = new MetricsEventRequest {
   User = user,
   Value = 750
};

await trophy.Metrics.EventAsync("flashcards-flipped", request);

result = client.metrics.event(
  :key => 'flashcards-flipped',
  :user => {
    :id => '18',
    :email => 'user@example.com'
  },
  :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 resultado directo del evento que ocurrió:

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 más recientes de clasificación del usuario para cada clasificación que cambió como resultado del evento

Con un poco de código personalizado, estos datos de respuesta pueden utilizarse para impulsar cualquier experiencia dentro de la aplicación que desees, incluyendo:

Activar notificaciones dentro de la aplicación
Efectos de sonido
Animaciones

Observa a Charlie integrar el seguimiento de métricas en una aplicación NextJS simple usando el SDK de Node.js de Trophy:

Eventos Idempotentes

Trophy permite garantizar la unicidad de los eventos para que los usuarios no puedan incrementar una métrica repitiendo la misma acción una y otra vez. Por ejemplo, una aplicación de aprendizaje de idiomas podría especificar que los usuarios solo pueden incrementar la métrica lessons-completed en 1 por cada lección única completada, de modo que si completan la misma lección dos veces, solo cuenta la primera.

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
}'

trophy.metrics.event("lessons-completed",
  {
    user: {
      id: "18",
      email: "user@example.com",
      tz: "Europe/London",
    },
    value: 1,
    idempotencyKey: "lesson-123",
  }
);

client.metrics.event(
    key="lessons-completed",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=1,
    idempotencyKey="lesson-123"
)

$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com'
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 1,
    'idempotencyKey' => 'lesson-123'
]);

$trophy->metrics->event("lessons-completed", $request);

MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .build()
      )
      .value(1)
      .idempotencyKey("lesson-123")
      .build();

EventResponse response = client.metrics().event("lessons-completed", request);

response, err := client.Metrics.Event(
    "lessons-completed",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
        },
        Value: 1,
        IdempotencyKey: "lesson-123"
    },
)

var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com"
};

var request = new MetricsEventRequest {
   User = user,
   Value = 1,
   IdempotencyKey = "lesson-123"
};

await trophy.Metrics.EventAsync("lessons-completed", request);

result = client.metrics.event(
  :key => 'lessons-completed',
  :user => {
    :id => '18',
    :email => 'user@example.com'
  },
  :value => 1,
  :idempotencyKey => 'lesson-123'
)

Esto ayuda a mantener tu código libre de lógica que verifique si los usuarios han completado acciones previamente, 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.

Eventos paralelos

Trophy no admite eventos paralelos a la misma métrica para el mismo usuario. En su lugar, usa el parámetro value para incrementar la métrica por el monto total de todos los eventos individuales que necesitas rastrear.

curl -X POST https://app.trophy.so/api/metrics/lessons-completed/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 5
}'

trophy.metrics.event("lessons-completed", {
  user: {
    id: "18",
    email: "user@example.com",
    tz: "Europe/London",
  },
  value: 5,
});

client.metrics.event(
    key="lessons-completed",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=5,
)

$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com'
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 5,
]);

$trophy->metrics->event("lessons-completed", $request);

MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .build()
      )
      .value(5)
      .build();

EventResponse response = client.metrics().event("lessons-completed", request);

response, err := client.Metrics.Event(
    "lessons-completed",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
        },
        Value: 5,
    },
)

var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com"
};

var request = new MetricsEventRequest {
   User = user,
   Value = 5,
};

await trophy.Metrics.EventAsync("lessons-completed", request);

result = client.metrics.event(
  :key => 'lessons-completed',
  :user => {
    :id => '18',
    :email => 'user@example.com'
  },
  :value => 5
)

Obtener soporte

¿Quieres contactar al equipo de Trophy? Comunícate con nosotros por correo electrónico. ¡Estamos aquí para ayudarte!

Primeros pasos

Funciones

Plataforma

Cuenta

¿Qué son los eventos?

Atributos clave

Valor del evento

Atributos personalizados de eventos

Crear Atributos

Establecer Atributos

Usar Atributos

Desencadenadores Avanzados de Características

Disparadores de Logros

Disparadores de Puntos

Personalización de correos electrónicos

Seguimiento de eventos de Métricas

Eventos Idempotentes

Eventos paralelos

Obtener soporte

​¿Qué son los eventos?

​Atributos clave

​Valor del evento

​Atributos personalizados de eventos

​Crear Atributos

​Establecer Atributos

​Usar Atributos

​Desencadenadores Avanzados de Características

Disparadores de Logros

Disparadores de Puntos

​Personalización de correos electrónicos

​Seguimiento de eventos de Métricas

​Eventos Idempotentes

​Eventos paralelos

​Obtener soporte

¿Qué son los eventos?

Atributos clave

Valor del evento

Atributos personalizados de eventos

Crear Atributos

Establecer Atributos

Usar Atributos

Desencadenadores Avanzados de Características

Personalización de correos electrónicos

Seguimiento de eventos de Métricas

Eventos Idempotentes

Eventos paralelos

Obtener soporte