> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Clasificaciones
> Aprende a usar Clasificaciones en una experiencia de producto gamificada con Trophy.
¿Qué son las Clasificaciones?
Las Clasificaciones son competiciones sociales entre usuarios de tu aplicación. Usa clasificaciones para aumentar el engagement y fomentar la interacción social.
Tipos de Clasificaciones
En esta sección describimos los diferentes tipos de clasificaciones compatibles en Trophy y cuándo usar cada una.
Clasificaciones Perpetuas
Las clasificaciones perpetuas nunca se reinician. Una vez iniciadas, rastrean y clasifican continuamente el progreso de los usuarios a lo largo del tiempo para siempre, o hasta la [fecha de finalización](#end-dates) configurada.
Usa clasificaciones perpetuas cuando quieras crear rankings históricos de toda la actividad de los usuarios.
Clasificaciones Repetitivas
Las clasificaciones repetitivas se pueden configurar para reiniciarse después de cualquier número arbitrario de días, meses o años.
En Trophy, cada instancia de una clasificación repetitiva se denomina **'run'**. Por ejemplo, una clasificación mensual tendría 12 runs en un año, pero una clasificación diaria tendría `n` runs en un mes donde `n` es el número de días en un mes determinado.
Trophy rastrea los rankings en cada run de una clasificación repetitiva individualmente y proporciona [APIs](/es/api-reference/endpoints/leaderboards/get-leaderboard) para obtener datos de ranking de runs históricos.
Recomendamos usar clasificaciones repetitivas en lugar de perpetuas cuando sea posible, ya que las clasificaciones repetitivas dan a los nuevos usuarios las mismas oportunidades de competir con los usuarios existentes, ayudando a evitar que las clasificaciones se vuelvan obsoletas.
Manejo de Zonas Horarias
Si has registrado las [zonas horarias](/es/features/users#param-tz) de los usuarios con Trophy, estas se utilizarán para garantizar que cada usuario tenga las mismas oportunidades de ganar sin importar en qué parte del mundo se encuentre.
En la práctica, esto significa que las clasificaciones se finalizan y los ganadores se eligen aproximadamente 12 horas después de que naturalmente terminan en UTC, lo que permite a los usuarios de todas las zonas horarias hacer su último esfuerzo.
Consejos para Clasificaciones Semanales
Para crear una clasificación semanal, configura una [clasificación recurrente](#repeating-leaderboards) con un programa de 7 días y establece la fecha de inicio en el próximo primer día de la semana.
Mientras esperas a que llegue la fecha de inicio, la clasificación estará en estado `scheduled` y se activará automáticamente en la fecha de inicio.
Lógica de Clasificación
Las clasificaciones en Trophy son configurables para clasificar a los participantes de varias formas diferentes y así soportar casos de uso comunes.
Métodos de Clasificación
El método de clasificación de una clasificación determina en qué dimensión se ordenarán los participantes.
Clasificaciones por Métricas
Las clasificaciones de métricas están vinculadas a una [Métrica](/es/features/metrics) existente de Trophy y clasifican a los usuarios según su valor métrico total.
Usa clasificaciones de métricas si solo deseas clasificar a los usuarios según una única interacción.
Clasificaciones por Puntos
Las clasificaciones de puntos están vinculadas a un [Sistema de Puntos](/es/features/points) existente de Trophy y clasifican automáticamente a los usuarios según sus puntos totales.
Usa una clasificación de puntos si deseas clasificar a los usuarios según una combinación de métricas, logros u otras funciones de Trophy.
Clasificación de Rachas
Las clasificaciones de rachas ordenan a los usuarios según la longitud de su racha actual.
Las clasificaciones de rachas solo pueden ser [perpetuas](#perpetual-leaderboards).
Desglose de Clasificaciones
Si tienes una base de usuarios grande, es una buena práctica dividir a los participantes de la clasificación en grupos más pequeños y socialmente conectados. Esto suele generar mayor engagement que cuando se usan clasificaciones globales.
Las clasificaciones en Trophy pueden configurarse para agrupar usuarios en grupos más pequeños según uno o más [atributos personalizados de usuario](/es/features/users#custom-user-attributes).
Al usar desgloses de clasificación, los [límites de participantes](#participant-limits)
se aplican a nivel de grupo, no en general.
Para configurar un desglose de clasificación, ve a la página de configuración de la clasificación y crea o selecciona uno o más atributos de usuario en el campo 'Atributos de Desglose'.
Trophy comenzará automáticamente a agrupar usuarios en clasificaciones más pequeñas según los valores de los atributos elegidos para cada usuario.
Para obtener las clasificaciones de un grupo específico de usuarios con un valor de atributo determinado, usa la [API de clasificaciones](/es/api-reference/endpoints/leaderboards/get-leaderboard), especificando un filtro de atributo en el parámetro `userAttributes` de la siguiente manera:
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/leaderboards/{key}?userAttributes=city:london \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.leaderboards.get("daily_champions", {
offset: 0,
limit: 10,
run: "2025-01-15",
userAttributes: "city:london"
});
```
```python Python theme={null}
client.leaderboards.get(
key="daily_champions",
offset=0,
limit=10,
run="2025-01-15",
user_attributes="city:london"
)
```
```php PHP theme={null}
$request = new LeaderboardsGetRequest([
'offset' => 0,
'limit' => 10,
'run' => "2025-01-15",
'user_attributes' => "city:london"
]);
$trophy->leaderboards->get("daily_champions", $request);
```
```java Java theme={null}
LeaderboardsGetRequest request = LeaderboardsGetRequest.builder()
.offset(0)
.limit(10)
.run("2025-01-15")
.userAttributes("city:london")
.build();
LeaderboardsGetResponse response = client.leaderboards().get("daily_champions", request);
```
```go Go theme={null}
response, err := client.Leaderboards.Get(
"daily_champions",
&api.LeaderboardsGetRequest{
Offset: 0,
Limit: 10,
Run: "2025-01-15",
UserAttributes: "city:london",
},
)
```
```csharp C# theme={null}
var request = new LeaderboardsGetRequest {
Offset = 0,
Limit = 10,
Run = "2025-01-15",
UserAttributes = "city:london"
};
await trophy.Leaderboards.GetAsync("daily_champions", request);
```
```ruby Ruby theme={null}
result = client.Leaderboards.Get(
:key => "daily_champions",
:offset => 0,
:limit => 10,
:run => "2025-01-15",
:user_attributes => "city:london"
)
```
Para obtener las clasificaciones de un grupo específico de usuarios con una combinación particular de atributos de usuario, pasa múltiples filtros `key:value` delimitados por comas en `userAttributes` de la siguiente manera:
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/leaderboards/{key}?userAttributes=region:southeast,city:london \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.leaderboards.get("daily_champions", {
offset: 0,
limit: 10,
run: "2025-01-15",
userAttributes: "region:southeast,city:london"
});
```
```python Python theme={null}
client.leaderboards.get(
key="daily_champions",
offset=0,
limit=10,
run="2025-01-15",
user_attributes="region:southeast,city:london"
)
```
```php PHP theme={null}
$request = new LeaderboardsGetRequest([
'offset' => 0,
'limit' => 10,
'run' => "2025-01-15",
'user_attributes' => "region:southeast,city:london"
]);
$trophy->leaderboards->get("daily_champions", $request);
```
```java Java theme={null}
LeaderboardsGetRequest request = LeaderboardsGetRequest.builder()
.offset(0)
.limit(10)
.run("2025-01-15")
.userAttributes("region:southeast,city:london")
.build();
LeaderboardsGetResponse response = client.leaderboards().get("daily_champions", request);
```
```go Go theme={null}
response, err := client.Leaderboards.Get(
"daily_champions",
&api.LeaderboardsGetRequest{
Offset: 0,
Limit: 10,
Run: "2025-01-15",
UserAttributes: "region:southeast,city:london",
},
)
```
```csharp C# theme={null}
var request = new LeaderboardsGetRequest {
Offset = 0,
Limit = 10,
Run = "2025-01-15",
UserAttributes = "region:southeast,city:london"
};
await trophy.Leaderboards.GetAsync("daily_champions", request);
```
```ruby Ruby theme={null}
result = client.Leaderboards.Get(
:key => "daily_champions",
:offset => 0,
:limit => 10,
:run => "2025-01-15",
:user_attributes => "region:southeast,city:london"
)
```
Cuando se proporcionan múltiples filtros `userAttributes`, todos los filtros deben coincidir
para que un usuario se incluya en las clasificaciones devueltas.
Fechas de Inicio y Fin
Usa fechas de inicio y fin para controlar la ventana durante la cual las clasificaciones están clasificando activamente a los usuarios.
Fechas de inicio
Las clasificaciones en Trophy se pueden configurar para que comiencen en una fecha futura de tu elección. Esto suele ser útil para permitir tiempo para cambios o ajustes de último momento antes de que las clasificaciones empiecen a rankear usuarios.
Las clasificaciones con una fecha de inicio en el futuro están programadas y se activan automáticamente en la fecha de inicio que elijas.
Fechas de finalización
Las clasificaciones en Trophy pueden tener fechas de finalización. Si estableces una fecha de finalización en una clasificación, después de esa fecha entrará en estado `finished` y los rankings se finalizarán y se elegirán los ganadores.
Debido a las diferencias en [zonas horarias](#handling-time-zones), las clasificaciones pueden finalizarse hasta 12 horas después de la fecha de finalización en UTC para permitir que todos los usuarios alcancen la fecha de finalización según su reloj local.
Límites de participantes
Las clasificaciones en Trophy tienen un número máximo de participantes de **1.000**. Sin embargo, una clasificación se puede configurar para tener cualquier número arbitrario de participantes para soportar casos de uso como *Top 100* o similares.
Si una clasificación ya tiene un número de participantes que coincide con su máximo configurado, los nuevos usuarios tendrán que superar la puntuación del rango más bajo para unirse a la clasificación.
Elegimos limitar el tamaño de las clasificaciones para ayudar a guiar a los clientes sobre las mejores prácticas.
Tradicionalmente, las clasificaciones con muchos participantes no logran involucrar a los usuarios más allá del 1% superior, y tienen un impacto **negativo** en los usuarios de la mitad inferior, particularmente en los usuarios nuevos. Para evitar esto, mantén tus clasificaciones pequeñas dividiéndolas en clasificaciones más pequeñas usando [atributos de desglose](#ranking-breakdowns).
Para obtener más información sobre los efectos negativos en las clasificaciones globales, lee esta [publicación del blog](https://www.trophy.so/blog/leaderboard-only-motivating-top-one-percent).
La única excepción a esto es cuando se utilizan [atributos de desglose](#ranking-breakdowns) para agrupar a los participantes en cohortes más pequeñas. Al usar atributos de desglose, el límite de participantes se aplica a cada grupo, no de forma general.
Crear Clasificaciones
Para crear una clasificación, dirígete a la [página de clasificaciones](https://app.trophy.so/leaderboards) en el panel de Trophy y haz clic en el botón *Nueva Clasificación*.
Elige un nombre para la clasificación.
Ingresa una clave de referencia única para la clasificación. Esto es lo que usarás para hacer referencia a la clasificación en el código de tu aplicación.
Elige uno de los [métodos](#ranking-methods) por el cual la clasificación clasificará a los usuarios:
* **Métrica**: Clasifica a los usuarios por el valor total de una métrica elegida
* **Puntos**: Clasifica a los usuarios por los puntos totales en un sistema de puntos elegido
* **Racha**: Clasifica a los usuarios por la longitud de la racha actual
Elige el número máximo de participantes que la clasificación debe admitir. El
límite superior actual admitido por Trophy es 1,000. Lee [esta
sección](#participant-limits) para obtener más información sobre cómo elegimos este límite.
Haz clic en guardar y dirígete a la página de configuración para establecer [fechas de inicio y finalización](#start-end-dates), [cronogramas de clasificaciones recurrentes](#repeating-leaderboards) y más.
Administrar Clasificaciones
Las Clasificaciones en Trophy tienen varios estados para ayudarte a controlar cuándo y cómo los usuarios pueden unirse a ellas.
Estados de Clasificación
Las Clasificaciones pueden tener uno de los siguientes estados:
* `Inactive`
* `Scheduled`
* `Active`
* `Finished`
Todas las clasificaciones nuevas se crean como `Inactive`. Mientras están inactivas, se puede cambiar cualquier propiedad o configuración de la clasificación, no serán visibles para los usuarios y los usuarios no podrán unirse a ellas.
Una vez que estés listo para que los usuarios empiecen a participar, puedes hacerla `Active`. Esto significa que Trophy comenzará a rastrear la actividad de los usuarios e ingresarlos en las clasificaciones.
Las clasificaciones que se han configurado con una [fecha de inicio](#start-dates) en el futuro no pueden activarse, solo pueden estar `Scheduled`. Una vez que la fecha de inicio haya pasado, Trophy las hará `Active` automáticamente y comenzará a aceptar participantes.
Si una clasificación tiene una [fecha de finalización](#end-dates), una vez que haya pasado, Trophy la moverá automáticamente al estado `Finished` y dejará de monitorear la actividad del usuario. Una vez que una clasificación haya finalizado, no será visible para los usuarios, pero aún puedes consultar las APIs para obtener las posiciones de ejecuciones históricas.
Mostrar Clasificaciones
Consulta nuestra [guía completa](/es/guides/how-to-build-a-leaderboards-feature) sobre
cómo agregar clasificaciones a tu aplicación para más detalles.
Análisis de Clasificaciones
Trophy tiene análisis integrados para ayudarte a entender cómo los usuarios interactúan con tus clasificaciones.
Total de Participantes Únicos
Este gráfico muestra cuántos usuarios únicos han participado en cualquier ejecución de una clasificación a lo largo del tiempo. Esto es útil para entender cuántos de tus usuarios realmente participan en clasificaciones y cómo los [límites de participantes](#participant-limits) están afectando esto.
Usuarios activos
Este gráfico muestra el número de usuarios que han cambiado de rango al menos una vez en una clasificación determinada. Esto es útil para tener una idea de cuán competitivo es el usuario promedio en una clasificación en particular.
Cambios de Rango
Este gráfico muestra el número total de cambios de rango en una clasificación particular a lo largo del tiempo. Esto es útil para entender cuán competitivos son los usuarios en general.
Distribución de Puntuaciones
Este gráfico es un histograma de las puntuaciones de los usuarios en una clasificación particular. Esto es útil para tener una idea de qué tan agrupados o dispersos están los usuarios, y qué secciones de las clasificaciones son las más competitivas.
Preguntas Frecuentes
Limitamos las clasificaciones a 1,000 participantes.
Lee más sobre esto en la [sección dedicada](#participant-limits) de esta página.
{" "}
Trophy admite la ejecución de clasificaciones repetidas en cualquier número arbitrario de
días. Así que una clasificación semanal sería simplemente una clasificación que se repite cada 7
días. Lee [esta sección](#tips-for-weekly-leaderboards) para más consejos sobre
la creación de clasificaciones semanales.
Obtener soporte
¿Quieres ponerte en contacto con el equipo de Trophy? Comunícate con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!