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.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.
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 theprofile-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.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.
Creating Boosts
User-specific boosts can only be created programmatically through the Admin API.
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.2se redondea a1y1.7se redondea a2.
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 conkey, 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 eltotal 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 mapapoints 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
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 incluirlevel: 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
- 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, sulevel 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

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
GET /points/{key} — 200 response


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
