> ## 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.
# Cómo Crear una Funcionalidad de Clasificaciones
> Aprende a usar Trophy para agregar una funcionalidad de clasificaciones a tu aplicación web o móvil.
Esta guía describe el proceso completo para agregar una funcionalidad de clasificaciones a tu aplicación web o móvil usando Trophy.
Con fines ilustrativos, utilizaremos el ejemplo de una plataforma de estudio que usa una clasificación diaria para crear competencia amistosa en torno a la visualización de tarjetas de memoria.
Para ver un ejemplo completamente funcional de esto en la práctica, consulta la [demostración en vivo](https://examples.trophy.so) o el [repositorio de github](https://github.com/trophyso/example-study-platform/tree/demo).
Requisitos previos
* Una cuenta de [Trophy](https://app.trophy.so/sign-up)
* Aproximadamente 10 minutos
Configuración de Trophy
En Trophy, las [Métricas](/es/features/metrics) son los componentes fundamentales de la gamificación y modelan las diferentes interacciones que los usuarios realizan con tu producto.
En esta guía, la interacción que nos interesa es `flashcards-viewed`, pero puedes crear una métrica que represente mejor la interacción en torno a la cual deseas crear clasificaciones.
En el panel de Trophy, dirígete a la [página de métricas](https://app.trophy.so/metrics) y crea una métrica.
Una vez que hayas creado tu métrica, dirígete a la [página de clasificaciones](https://app.trophy.so/leaderboards) y crea las clasificaciones que desees. Puedes encontrar todos los detalles sobre los tipos de clasificaciones y los diferentes casos de uso en la [documentación de clasificaciones](/es/features/leaderboards).
Para los propósitos de esta guía, hemos configurado una clasificación diaria que rastrea el XP total que un usuario gana al ver tarjetas de estudio.
Para una guía completa sobre cómo agregar una función de XP a tu aplicación web o móvil, consulta
nuestra [guía completa](/es/guides/how-to-build-an-xp-feature).
En Trophy rastreas las interacciones de los usuarios enviando [Eventos](/es/features/events) desde tu código a las API de Trophy contra una métrica específica.
Cuando se registran eventos para un usuario específico, Trophy actualiza automáticamente su clasificación en cada clasificación de la que forma parte.
Esto es lo que hace que construir experiencias gamificadas con Trophy sea tan fácil, hace todo el trabajo por ti en segundo plano.
Instalando Trophy SDK
Para interactuar con Trophy desde tu código, utilizarás el Trophy SDK disponible en la mayoría de los principales [lenguajes de programación](/es/api-reference/client-libraries).
Instala el Trophy SDK:
```bash Node theme={null}
npm install @trophyso/node
```
```bash Ruby theme={null}
gem install trophy_api_client
```
```bash Python theme={null}
pip install trophy
```
```bash PHP theme={null}
composer require trophyso/php
```
```bash Java (Gradle) theme={null}
implementation 'so.trophy:trophy-java:1.0.0'
```
```bash Java (Maven) theme={null}
so.trophy
trophy-java
1.0.0
```
```bash Go theme={null}
go get github.com/trophy-so/trophy-go
```
```bash .NET (C#) theme={null}
// .NET Core CLI
dotnet add package Trophy
// Nuget Package Manager
nuget install Trophy
// Visual Studio
Install-Package Trophy
```
A continuación, obtén tu clave de API desde la [página de integración](https://app.trophy.so/integration) de Trophy y agrégala como una variable de entorno **solo del lado del servidor**.
```bash theme={null}
TROPHY_API_KEY='*******'
```
Asegúrate de **no** exponer tu clave de API en código del lado del cliente.
Rastreando Interacciones de Usuarios
Para rastrear un evento (interacción de usuario) contra tu métrica, utiliza la [API de cambio de métrica](/es/api-reference/endpoints/metrics/send-a-metric-change-event).
```bash cURL theme={null}
curl -X POST https://app.trophy.so/api/metrics/flashcards-flipped/event \
-H "X-API-KEY: " \
-H "Content-Type: application/json" \
-d '{
"user": {
"id": "18",
"email": "user@example.com",
"tz": "Europe/London"
},
"value": 750
}'
```
```typescript Node theme={null}
trophy.metrics.event("flashcards-flipped", {
user: {
id: "18",
email: "user@example.com",
tz: "Europe/London",
},
value: 750,
});
```
```python Python theme={null}
client.metrics.event(
key="flashcards-flipped",
user=EventRequestUser(
id="18",
email="user@example.com",
tz="Europe/London",
),
value=750.0,
)
```
```php PHP theme={null}
$user = new EventRequestUser([
'id' => '18',
'email' => 'user@example.com'
]);
$request = new MetricsEventRequest([
'user' => $user,
'value' => 750
]);
$trophy->metrics->event("flashcards-flipped", $request);
```
```java Java theme={null}
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);
```
```go Go theme={null}
response, err := client.Metrics.Event(
"flashcards-flipped",
&api.MetricsEventRequest{
User: &api.EventRequestUser{
Id: "18",
Email: "user@example.com",
},
Value: 750,
},
)
```
```csharp C# theme={null}
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);
```
```ruby Ruby theme={null}
result = client.metrics.event(
:key => 'flashcards-flipped',
:user => {
:id => '18',
:email => 'user@example.com'
},
:value => 750
)
```
La respuesta a esta llamada de API es el conjunto completo de cambios a cualquier función que hayas construido con Trophy, incluyendo cualquier cambio en su clasificación en cualquier clasificación de la que formen parte.
```json Response [expandable] theme={null}
{
"metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
"eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"total": 750,
...,
"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
}
}
}
```
Valida que esto esté funcionando revisando el [panel de control](https://app.trophy.so) de Trophy.
Mostrando Clasificaciones
Tienes varias opciones para mostrar clasificaciones en tu aplicación. Aquí veremos las opciones más comunes.
Notificaciones Emergentes
Podemos utilizar la respuesta de la [API de cambio de métrica](/es/api-reference/endpoints/metrics/send-a-metric-change-event) para mostrar notificaciones emergentes (o 'toasts') cuando los usuarios suben en las clasificaciones.
Aquí hay un ejemplo de esto en acción:
```ts Leaderboard Rank Up Pop-up theme={null}
// Sends event to Trophy
const response = await viewFlashcard();
if (!response) {
return;
}
const leaderboard = response.leaderboards["daily_champions"];
if (!leaderboard) {
return;
}
// Show toasts if the user moved up the leaderboard
if (leaderboard.rank > leaderboard.previousRank) {
toast({
title: "You're on the move!,
description: `You moved up ${leaderboard.previousRank - leaderboard.rank} places!,
});
}
```
Si quieres reproducir efectos de sonido, utiliza la [API de Audio
HTML5](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) y siéntete
libre de usar estos [archivos de
audio](https://github.com/trophyso/example-study-platform/tree/demo/public/sounds)
que recomendamos.
Mostrar las Clasificaciones
Para obtener una clasificación y sus rankings más actualizados, utiliza la [API de clasificación](/es/api-reference/endpoints/leaderboards/get-leaderboard).
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/leaderboards/{key} \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.leaderboards.get("daily_champions", {
offset: 0,
limit: 10,
run: "2025-01-15"
});
```
```python Python theme={null}
client.leaderboards.get(
key="daily_champions",
offset=0,
limit=10,
run="2025-01-15"
)
```
```php PHP theme={null}
$trophy->leaderboards->get("daily_champions");
```
```java Java theme={null}
client.leaderboards().get("daily_champions");
```
```go Go theme={null}
response, err := client.Leaderboards.Get("daily_champions")
```
```csharp C# theme={null}
trophy.Leaderboards.GetAsync("daily_champions");
```
```ruby Ruby theme={null}
result = client.Leaderboards.Get(
:key => "daily_champions"
)
```
También puedes utilizar el parámetro `run` con la fecha de la 'ejecución' pasada específica
de una clasificación para la cual deseas obtener datos.
Aquí hay un ejemplo de los datos devueltos por la API de clasificación:
```json Response [expandable] theme={null}
{
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
"name": "Weekly Flashcard Challenge",
"key": "weekly-challenge",
"rankBy": "metric",
"metricKey": "flashcards-flipped",
"metricName": "Flashcards Flipped",
"pointsSystemKey": null,
"pointsSystemName": null,
"description": "Compete weekly to see who views the most flashcards",
"status": "active",
"start": "2025-01-01",
"end": null,
"maxParticipants": 100,
"runUnit": "day",
"runInterval": 7,
"rankings": [
{
"userId": "user-123",
"userName": "Alice Johnson",
"rank": 1,
"value": 5000
},
{
"userId": "user-456",
"userName": "Bob Smith",
"rank": 2,
"value": 4500
},
{
"userId": "user-789",
"userName": "Charlie Brown",
"rank": 3,
"value": 4200
}
]
}
```
Mostrar el Historial de Rango del Usuario
Utiliza la [API de clasificación de usuario](/es/api-reference/endpoints/users/get-a-users-leaderboard) para obtener datos sobre cómo ha cambiado el rango de un usuario específico a lo largo del tiempo en una clasificación particular.
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/users/{id}/leaderboards/{key} \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.users.leaderboards("user-id", "daily_champions", {
run: "2025-01-15"
});
```
```python Python theme={null}
client.users.leaderboards("user-id", "daily_champions", run="2025-01-15")
```
```php PHP theme={null}
$trophy->users->leaderboards("user-id", "daily_champions")
```
```java Java theme={null}
client.users().leaderboards("user-id", "daily_champions")
```
```go Go theme={null}
response, err := client.Users.Leaderboards("user-id", "daily_champions")
```
```csharp C# theme={null}
trophy.Users.Leaderboards("user-id", "daily_champions");
```
```ruby Ruby theme={null}
result = client.Leaderboards.Get(
:id => "user-id",
:key => "daily_champions"
)
```
Aquí hay un ejemplo de los datos devueltos por la API de rankings de clasificación de usuario, que incluye el rango actual del usuario en el atributo `rank` y un array de rangos anteriores en el atributo `history`:
```json Response [expandable] theme={null}
{
"id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
"name": "Weekly Word Count Challenge",
"key": "weekly-words",
"rankBy": "metric",
"metricKey": "flashcards-flipped",
"metricName": "Flashcards Flipped",
"pointsSystemKey": null,
"pointsSystemName": null,
"description": "Compete weekly to see who writes the most words",
"start": "2025-01-01",
"end": null,
"maxParticipants": 100,
"runUnit": "day",
"runInterval": 7,
"rank": 2,
"value": 4500,
"history": [
{
"timestamp": "2025-01-15T10:30:00Z",
"previousRank": null,
"rank": 5,
"previousValue": null,
"value": 1000
},
{
"timestamp": "2025-01-15T14:15:00Z",
"previousRank": 5,
"rank": 3,
"previousValue": 1000,
"value": 3000
},
{
"timestamp": "2025-01-15T18:45:00Z",
"previousRank": 3,
"rank": 2,
"previousValue": 3000,
"value": 4500
}
]
}
```
Analíticas
La [página de clasificaciones](https://app.trophy.so/achievements) en Trophy muestra cuántos usuarios están participando activamente en una clasificación, así como una medida de competitividad basada en cuántos cambios de rango están ocurriendo.
La página de analíticas también muestra una distribución de las puntuaciones de los usuarios para ayudar a identificar grupos de usuarios dentro de las clasificaciones.
Además, la página de clasificaciones de la clasificación muestra las posiciones actuales y pasadas de una clasificación:
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!