> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.
# Cómo Crear una Funcionalidad de Logros
> Aprende a usar Trophy para añadir una funcionalidad de logros a tu aplicación web o móvil.
Esta guía describe el proceso completo para añadir una funcionalidad de logros a tu aplicación web o móvil usando Trophy.
A modo ilustrativo, usaremos el ejemplo de una plataforma de estudio que utiliza logros para incentivar y recompensar a los usuarios por ver tarjetas de memoria.
> [!TIP]
>
> 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.md) 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 mejor represente la interacción en torno a la cual quieres construir logros.
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 logros](https://app.trophy.so/achievements) y crea los logros que desees. Puedes encontrar todos los detalles sobre los tipos de logros y los diferentes casos de uso en la [documentación de logros](/es/features/achievements.md).
Para los propósitos de esta guía, hemos configurado un par de logros basados en un número creciente de tarjetas volteadas:
* 10 tarjetas de estudio
* 50 tarjetas de estudio
* 100 tarjetas de estudio
* 250 tarjetas de estudio
* 1,000 tarjetas de estudio
También hemos configurado algunos logros relacionados con [Rachas](/es/features/streaks.md), pero no entraremos en detalle sobre estos en esta guía.
> [!TIP]
>
> Para una guía completa sobre cómo agregar una función de rachas a tu aplicación web o móvil, consulta
> nuestra [guía completa](/es/guides/how-to-build-a-streaks-feature.md).
También puedes crear [logros de aniversario](/es/features/achievements.md#anniversary-achievements) que se desbloquean cuando los usuarios alcanzan hitos anuales desde su fecha de registro.
En Trophy rastreas las interacciones de los usuarios enviando [Eventos](/es/features/events.md) desde tu código a las API de Trophy contra una métrica específica.
Cuando se registran eventos para un usuario específico, cualquier logro vinculado a la métrica especificada se **completará automáticamente** si se cumplen los requisitos.
Esto es lo que hace que construir experiencias gamificadas con Trophy sea tan fácil: hace todo el trabajo por ti entre bastidores.
## Instalación del SDK de Trophy
Para interactuar con Trophy desde tu código, utilizarás el SDK de Trophy disponible en los principales [lenguajes de programación](/es/api-reference/client-libraries.md).
Instala el SDK de Trophy:
```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='*******'
```
> [!WARNING]
>
> Asegúrate de **no** exponer tu clave de API en código del lado del cliente.
## Rastreo de 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/events/submit-a-metric-event.md).
```bash cURL theme={null}
curl -X POST https://api.trophy.so/v1/metrics/flashcards-flipped/event \
-H "X-API-KEY: " \
-H "Idempotency-Key: flashcard-view-42" \
-H "Content-Type: application/json" \
-d '{
"user": {
"id": "18",
"email": "user@example.com",
"tz": "Europe/London"
},
"value": 750
}'
```
```typescript Node theme={null}
import type { EventResponse } from "@trophyso/node/api";
const response: EventResponse = await trophy.metrics.event(
"flashcards-flipped",
{
user: {
id: "18",
email: "user@example.com",
tz: "Europe/London",
},
value: 750,
idempotencyKey: "flashcard-view-42",
}
);
```
```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 en cualquier característica que hayas construido con Trophy, incluyendo cualquier logro que se haya desbloqueado como resultado del evento.
```json Response [expandable] theme={null}
{
"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"
}
],
...
}
```
Valida que esto funciona revisando el [panel](https://app.trophy.so) de Trophy.
## Visualización de Logros
Tienes varias opciones para mostrar logros en tu aplicación. Aquí veremos las opciones más comunes.
### Notificaciones Emergentes
Podemos usar la respuesta de la [API de cambio de métrica](/es/api-reference/endpoints/events/submit-a-metric-event.md) para mostrar notificaciones emergentes (o 'toasts') cuando los usuarios completen logros.
Aquí tienes un ejemplo de esto en acción:
```ts Achievement Completed Pop-up theme={null}
// Sends event to Trophy
const response = await viewFlashcard();
if (!response) {
return;
}
// Show toasts if the user has unlocked any new achievements
response.achievements.forEach((achievement) => {
toast({
title: achievement.name,
description: achievement.description,
image: {
src: achievement.badgeUrl,
alt: achievement.name,
},
});
});
```
> [!TIP]
>
> Si deseas 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 Logros del Usuario
Para obtener todos los logros que un usuario ha completado, utiliza la [API de logros de usuario](/es/api-reference/endpoints/users/get-a-users-completed-achievements.md).
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/users/{id}/achievements \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.users.achievements("user-id");
```
```python Python theme={null}
client.users.achievements("user-id")
```
```php PHP theme={null}
$trophy->users->achievements("user-id");
```
```java Java theme={null}
UserAchievementsResponse response = client.users().achievements("user-id");
```
```go Go theme={null}
response, err := client.Users.Achievements("user-id")
```
```csharp C# theme={null}
await trophy.Users.AchievementsAsync("user-id");
```
```ruby Ruby theme={null}
result = client.users.achievements(
:id => 'user-id'
)
```
> [!TIP]
>
> También puedes obtener logros incompletos al mismo tiempo pasando `includeIncomplete` como `'true'`.
### Mostrar Todos los Logros
Si en cambio deseas mostrar todos los logros que has configurado en Trophy como parte de una interfaz de usuario globalmente accesible que no está vinculada a un usuario en particular, puedes utilizar la [API de todos los logros](/es/api-reference/endpoints/achievements/all-achievements.md).
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/achievements \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.achievements();
```
```python Python theme={null}
client.achievements()
```
```php PHP theme={null}
$trophy->achievements();
```
```java Java theme={null}
UserAchievementsResponse response = client.achievements();
```
```go Go theme={null}
response, err := client.Achievements()
```
```csharp C# theme={null}
await trophy.AchievementsAsync();
```
```ruby Ruby theme={null}
result = client.achievements()
```
### Estadísticas de Completado de Logros
Tanto la API de logros de usuario como la API de todos los logros incluyen estadísticas de completado como `completions` (el número de usuarios que han completado un logro) y `rarity` (el porcentaje de usuarios que han completado un logro).
## Análisis
La [página de logros](https://app.trophy.so/achievements) en Trophy muestra cuántos usuarios han completado cada logro que has configurado.
Además, la página de análisis de cualquier métrica en Trophy incluye un gráfico que muestra el progreso de los usuarios a través de tus logros.
## Obtener Soporte
¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.