Skip to main content

What is a Points System?

Points systems are used to create counters that track users’ interactions with Metrics, Achievements and Streaks. You can then build features like ‘XP’ and ‘Energy’ around these counters within your product.

Use Cases

Rewards

Points systems can be used to create features like ‘XP’ or ‘Gems’ that reward users for a number of interactions at different rates. In this way points can be used to weight the value of certain interactions differently to others to reward users for taking the actions you consider most closely correlated to retention.

Metering

Points systems can also be used to create features like ‘Energy’ that meter usage of your product in a way that gives you control over promoting and restricting user activity. This allows you to control the rate at which users can use your product with a flexible mechanic that sits outside your codebase.

Creating Points Systems

Trophy let’s you set up multiple points systems for different use cases within your application.
To create a points system, head to the points page and follow the steps below.
1

Hit New Points System

Give the new points system a name, and a unique key. The key is what you’ll use to reference the points system in APIs and in email templates if relevant.
2

Add a description (Optional)

You can also give the points system a description which is returned from APIs to be displayed in your application.
3

Configure max points (Optional)

If you want to limit the number of points that each user can have in your new system, set a value in the ‘max points’ field.
Any points triggers that you configure against this points system will respect the maximum set.
4

Assign a badge (Optional)

You can assign a badge or logo by uploading an image or by entering a custom image URL. APIs return a src-friendly URL for display in your application.

Points Triggers

In Trophy, points are awarded to or deducted from users through triggers. These define the different mechanics that make up your points system. You can add as many triggers as you like to each points system you set up, allowing you to create different logic for how points are awarded or deducted for different points systems.

Types of Triggers

There are multiple types of triggers in Trophy that can be used to award or deduct points in different ways.

Metric Triggers

Points can be awarded or deducted continually as users increment Metrics. You can choose to award or deduct any arbitrary number of points at any arbitrary metric threshold, for example “award 10 points for every 3 tasks completed”.

Streak Triggers

Points can be awarded or deducted for reaching any arbitrary length of a Streak, for example “award 50 points for every 7 days streak”.

Achievement Triggers

Points can be awarded or deducted when users unlock specific Achievements, for example “award 100 points when users completed the profile-completed achievement”.

Time-based Triggers

Points can be awarded or deducted at repeating time intervals, every hour or every day. For example “award 10 points every 3 hours”.

User Identification Triggers

Points can be awarded when users are first identified in Trophy, useful for granting an initial amount of points when they sign up to your product.

Creating Triggers

To create a new points trigger, head to the points system that you want to create a trigger for and follow the steps below.
All new points triggers are created as ‘Inactive’ to allow testing and balancing before deployment to production.
1

Choose a trigger type

Choose how you want points to be awarded or deducted as described by the available trigger types.
2

Set up trigger

Once you’ve chosen the points trigger type, you need to set up the trigger settings.
  • If you chose the Metric trigger, you’ll need to choose the metric and the threshold amount at which to award or deduct points.
  • If you chose the Streak trigger, you’ll need to set the streak length that should award or deduct points.
  • If you chose the Achievement trigger, you’ll need to choose the achievement that should award or deduct points when completed.
  • If you chose the Time trigger, you’ll need to choose the time unit you want to award or deduct points on (hours or days) and the number of those time units that you want to award or deduct points after.
  • If you chose the First User Identification trigger, you won’t need to add any additional configuration.
3

Set points to award/deduct

Once your trigger is configured, set the number of points to award or deduct when fired.
4

Add attribute filters (Optional)

You can assign attribute filters to a points trigger to further restrict when they apply.
  • To limit a Metric trigger to only apply to events with specific custom event attributes, add one or more filters in the Event Attributes section.
  • To limit any type of trigger to only apply to a user with one or more specific custom user attributes, add attributes and the desired values in the User Attributes section.
When you set multiple event attribute filters, all of them must match for the metric trigger to fire.
5

Hit save

Save the new points trigger.
6

Activate

Once you’re happy that your new trigger will behave as expected, change its status to active to make it live.

Balancing Points

Running an effective points system requires finding the optimal pace at which users earn points. Too fast, and users will get points fatigue, rendering them useless. Too slow, and users may get bored and churn. Trophy’s preview tool can model different scenarios to help you determine how frequently users should earn points in each of your points systems.

Points Boosts

Points boosts are multipliers that you can use to increase the number of points awarded to users during a specific time period. This section explains how boosts work and how they can be used to increase your application’s retention and engagement.

Boost Targeting

There are a few different ways you can use boosts in Trophy.
  • Global boosts multiply points earned by all users during the boost window, or can be scoped to a specific user cohort by using custom user attributes.
  • User-specific boosts only multiply points earned by a single user within the boost window.
Typically, global boosts are used to increase platform-wide engagement during key calendar events like Black Friday/Cyber Monday in e-commerce, New Year in fitness and exam season in ed-tech platforms. Conversely, user-specific boosts are commonly used to provide additional incentives for users to take actions that are correlated with higher retention.

Creating Boosts

User-specific boosts can only be created programmatically through the Admin API.
To create a global points boost in the Trophy dashboard, follow the steps below.
1

Ir a la página de Impulsos

Ve a la página de puntos y haz clic en el sistema de puntos para el que deseas crear un impulso. Luego navega a la pestaña Impulsos y haz clic en el botón Nuevo Impulso.
2

Elige un nombre

Elige un nombre para tu impulso que describa claramente para qué es. Por ejemplo, “Impulso 2X - Todos los Usuarios - Navidad 2026”.
3

Establece el multiplicador

Establece el valor numérico por el que el impulso multiplicará los puntos obtenidos. Si eliges un multiplicador decimal, tendrás la opción de elegir el comportamiento de redondeo que debe usar el impulso.
4

Configura la ventana del impulso

Elige una fecha de inicio y (opcionalmente) una fecha de finalización para tu impulso. Si eliges una fecha de inicio futura, Trophy programará el impulso para que se active en la fecha elegida. De manera similar, si estableces una fecha de finalización, Trophy se encargará de detener tu impulso automáticamente.
5

Agrega filtros de atributos (opcional)

Si deseas que tu impulso solo afecte a un grupo específico de usuarios, establece condiciones de atributos de usuario que coincidan con las de tu grupo objetivo. Trophy se encargará de aplicar el impulso únicamente a los puntos obtenidos por usuarios con valores de atributos de usuario coincidentes.
6

Activar impulso

Haz clic en Guardar Impulso para guardar tu nuevo impulso en tu cuenta. El impulso estará en estado inactivo de forma predeterminada. Para activarlo, haz clic en el menú desplegable a la derecha del nombre del impulso en la página de Impulsos y haz clic en Activar.

Multiplicadores de impulso

Cada impulso tiene un único valor multiplicador que aumenta los Puntos totales obtenidos por los usuarios afectados por ese impulso. Los multiplicadores de impulso deben ser números positivos, pero pueden ser decimales para admitir escenarios donde se requieran impulsos porcentuales como ‘50% más Puntos’.

Acumulación de impulsos

Los impulsos de Puntos en Trophy se acumulan mediante multiplicación. Esto permite que los usuarios se beneficien de múltiples impulsos simultáneamente. Para demostrar la acumulación, considera un impulso de 2X, 1.5X y 3X activos dentro del mismo período de tiempo. El multiplicador de impulso resultante para un usuario que califica para los tres impulsos sería el siguiente:
Boost Stacking Example

Redondeo de impulsos

Trophy admite valores de eventos métricos de punto flotante, pero se encarga de redondear los Puntos a enteros automáticamente. Sin embargo, al usar multiplicadores de impulso decimales, puede haber algunos escenarios donde este redondeo predeterminado no sea suficiente para producir siempre valores de Puntos enteros. Por lo tanto, Trophy ofrece tres modos de redondeo para proporcionar control adicional sobre el comportamiento de redondeo específicamente cuando los impulsos están involucrados en los cálculos de Puntos.
  • Redondear hacia abajo: De forma predeterminada, Trophy redondeará los Puntos hacia abajo al entero más cercano cuando la multiplicación de impulsos resulte en un decimal.
  • Redondear hacia arriba: Trophy redondea los Puntos decimales hacia arriba al entero más cercano después de la multiplicación de impulsos.
  • Redondear al más cercano: Trophy redondeará los Puntos al entero más cercano, hacia arriba o hacia abajo, según el valor final después de la multiplicación de impulsos. Por ejemplo, 1.2 se redondea a 1 y 1.7 se redondea a 2.
En escenarios donde los Puntos se usan para imitar mecánicas de crédito de plataforma, se recomienda usar el comportamiento de redondeo hacia abajo predeterminado para proteger contra deslizamiento.
Simplemente elige tu modo de redondeo preferido al crear impulsos a través del panel de Trophy.

Niveles de Puntos

Los niveles de puntos son hitos discretos que defines en un sistema de puntos en Trophy. Cada nivel tiene un umbral. Cuando el total de puntos de un usuario en el sistema supera este umbral, Trophy les asigna ese nivel automáticamente. No necesitas mantener la lógica de niveles en tu propia base de código. Utiliza niveles para rangos de clasificación, interfaz de progresión, niveles de recompensa o análisis. Trophy mantiene sincronizado el nivel actual de cada usuario cada vez que ganan o pierden puntos en ese sistema.

Configuración de niveles

Para configurar niveles para un sistema de puntos, ábrelo desde la página de puntos en el panel de Trophy y utiliza la pestaña de niveles para añadir o gestionar niveles.
1

Abre tu sistema de puntos

Desde la página de puntos, selecciona el sistema de puntos al que deseas añadir niveles.
2

Abre la pestaña de niveles

Desde la página de tu sistema de puntos, abre la pestaña de niveles.
3

Añade niveles

Crea cada nivel con una clave estable, un nombre visible, descripción opcional, imagen de insignia y el umbral de puntos necesario para alcanzar ese nivel.Los umbrales deben reflejar cómo quieres que se sienta la progresión a medida que los usuarios acumulan puntos de tus activadores.
4

Guardar

Guarda tus niveles. Trophy evaluará los totales contra estos umbrales en cada cambio de puntos.

Visualización de Niveles

La mayoría de los equipos combinan tres enfoques: una imagen estática de cada nivel (para pantallas de progresión), el nivel actual del usuario (para encabezados y perfil) y retroalimentación inmediata cuando una acción los impulsa a un nuevo nivel.

Mostrar Todos los Niveles

Llama a la API de obtener niveles una vez por clave de sistema de puntos (por ejemplo, al cargar la aplicación o desde tu servidor al renderizar una página de progresión). La respuesta es un array de niveles con key, name, description, badgeUrl opcional, y el umbral points para cada nivel. Al vincular tu interfaz de usuario a la respuesta de la API de Trophy, te asegurarás de que se actualice automáticamente cuando realices cambios en los niveles en el panel de Trophy.
Response

Mostrar Nivel del Usuario

La API de puntos del usuario devuelve el total del usuario, su objeto level actual y awards recientes. El campo level contiene el nivel actual del usuario, o null si no existen niveles o aún no ha alcanzado el umbral de puntos para ningún nivel. Combina total con la lista ordenada de niveles del paso anterior para dibujar una barra de progreso entre el umbral actual y el siguiente.
Response

Notificaciones de Cambio de Nivel

Cuando envías un evento de cambio de métrica, la respuesta incluirá un mapa points indexado por las claves de tu sistema de puntos para cada sistema que cambió como resultado del evento. Los datos contienen una clave level solo cuando el nivel del usuario cambió debido a este evento. Si su nivel se mantuvo igual, esa clave se omite, por lo que puedes tratar de manera segura un level presente como una señal de cambio de nivel sin necesidad de contabilidad adicional.
Response
Un patrón típico es verificar el objeto para tu sistema después de un evento exitoso, luego activar un toast, modal o sonido:
El mismo comportamiento de level se aplica cuando los puntos cambian debido a la finalización de un logro. Para notificaciones dirigidas por el servidor (correo electrónico, push, CRM) que no deben depender de que el cliente vea la respuesta HTTP, suscríbete al webhook points.level_changed en su lugar. Este webhook se activa cuando el nivel de un usuario cambia como resultado de ganar o perder puntos, e incluye previousLevel y newLevel.

Análisis a nivel de cuenta

La API de resumen de niveles devuelve cuántos usuarios se encuentran actualmente en cada nivel, lo cual es útil para paneles de administración, vistas de embudo o equilibrado de progresión.
Response

Mostrar Puntos

Hay varias formas de usar Trophy para obtener y mostrar puntos en tu aplicación.
Para ver ejemplos prácticos, consulta nuestras guías sobre cómo agregar una función de XP o una función de energía a tu aplicación web o móvil.

Activar interfaz de usuario transaccional

En primer lugar, cualquier punto otorgado o deducido a los usuarios como resultado de un evento de cambio de métrica se devuelve en la respuesta al usar la API de evento de cambio de métrica. La respuesta incluye el nuevo total de puntos del usuario, cuántos puntos se otorgaron o dedujeron como resultado del evento y los detalles de los activadores de puntos específicos que se ejecutaron. Cuando Niveles de Puntos está habilitado, cada objeto de puntos en esa respuesta también puede incluir level: Trophy incluye el nuevo nivel del usuario solo cuando cambió como resultado de ese evento. El mismo comportamiento opcional de level se aplica cuando los puntos cambian por la finalización de un logro. Ejemplo de respuesta POST /metrics/{key}/event (los campos coinciden con la especificación de la API de Trophy; tus claves bajo points e leaderboards dependen de tu cuenta):
Response
Esto hace que sea muy sencillo leer la respuesta y activar cualquiera de las siguientes interfaces de usuario transaccionales en tu aplicación:
  • Mostrar notificaciones y ventanas emergentes en la aplicación
  • Reproducir efectos de sonido

Mostrar los Puntos del Usuario

Trophy también tiene APIs que te permiten obtener los datos de puntos del usuario cuando lo desees. Primero, la API de puntos de usuario devuelve los puntos totales del usuario para un sistema de puntos en particular, su level actual (o null si los niveles no están en uso o no han alcanzado un nivel aún), y hasta 100 de los eventos más recientes que otorgaron puntos o dedujeron puntos de ellos. Puedes usar esta API para mostrar los puntos totales del usuario en cualquier lugar de tu plataforma, así como una sección de ‘Últimas recompensas’ o similar. GET /users/{id}/points/{key} — ejemplo de cuerpo de respuesta (especificación de la API de Trophy):
Response
Luego, la API de resumen de puntos de usuario puede usarse para obtener datos históricos de puntos para un usuario en particular. Los datos pueden agregarse diariamente, semanalmente o mensualmente entre una fecha de inicio y una fecha de finalización. Usa esta API para mostrar gráficos de progreso de puntos a los usuarios durante cualquier período de tiempo. Ejemplo de respuesta GET /users/{id}/points/{key}/event-summary 200 (especificación de la API de Trophy; la estructura coincide con tus parámetros de consulta aggregation, startDate y endDate):
GET /users/{id}/points/{key}/event-summary — 200 response

Mostrar Datos Agregados

Además, hay una serie de APIs que pueden usarse para obtener y mostrar datos de puntos a nivel de cuenta. Primero, la API de resumen de puntos devuelve datos agregados del sistema de puntos en toda tu base de usuarios. Utiliza estos datos para mostrar un histograma de puntos de un sistema de puntos en particular y mostrar a los usuarios cómo se comparan con otros en la plataforma. Cuando uses Niveles de Puntos, la API de resumen de niveles complementa esto con un recuento de usuarios por nivel. GET /points/{key}/summary — ejemplo de respuesta 200 (especificación de la API de Trophy):
GET /points/{key}/summary — 200 response
Finalmente, la API del sistema de puntos devuelve los metadatos del sistema y los activadores. Ejemplo de respuesta 200 (especificación de la API de Trophy):
GET /points/{key} — 200 response
La API de resumen de puntos también se puede filtrar para devolver únicamente datos de usuarios con atributos de usuario personalizados específicos.
Utiliza la respuesta de la API del sistema de puntos para mostrar a los usuarios cómo pueden ganar puntos en tu plataforma. Cualquier nuevo activador que añadas se devolverá automáticamente desde esta API, reduciendo los cambios de código en tu plataforma y trasladando las operaciones a Trophy.

Analíticas de Puntos

Trophy tiene analíticas integradas para rastrear las concesiones de puntos de cada sistema de puntos que configures entre tus usuarios en tiempo real, incluyendo:
  • Total de puntos ganados por todos los usuarios a lo largo del tiempo
  • Mayor cantidad de puntos ganados por un solo usuario
  • Promedio de puntos ganados en los primeros 14 días (útil para entender los patrones de retención de nuevos usuarios y el impacto de los puntos)
  • Un desglose de los activadores de puntos más comúnmente otorgados

Obtener Soporte

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