> ## Documentation Index
> Fetch the complete documentation index at: https://trophy-ci-i18n-auto-translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo Crear una Funcionalidad de Rachas

> Aprende a usar Trophy para añadir una funcionalidad de rachas a tu aplicación web o móvil.

Esta guía describe el proceso completo para añadir una funcionalidad de rachas a tu aplicación web o móvil usando Trophy.

A modo ilustrativo, utilizaremos el ejemplo de una plataforma de estudio que emplea una racha diaria para incentivar y recompensar a los usuarios por ver tarjetas de estudio.

> [!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) 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 desde la cual quieres generar rachas.

En el panel de Trophy, dirígete a la [página de métricas](https://app.trophy.so/metrics) y crea una métrica.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-ci-i18n-auto-translations/kq20NZCpkjuLyTvG/assets/guides/achievements-feature/create_new_metric.mp4?fit=max&auto=format&n=kq20NZCpkjuLyTvG&q=85&s=9c66a4444b21eae410158df64d14f3c6" />

Una vez que hayas creado tu métrica, dirígete a la [página de rachas](https://app.trophy.so/streaks/configure) y selecciona la frecuencia de racha que deseas (diaria, semanal o mensual).

Luego añade tu métrica a las condiciones de racha y establece el umbral que los usuarios deben cumplir (por ejemplo, al menos 1 para extender su racha en cada período).

También puedes añadir múltiples métricas y elegir si los usuarios deben cumplir todas o solo una—consulta la [documentación de condiciones de racha](/es/features/streaks#streak-conditions) para más detalles.

En Trophy puedes hacer seguimiento de las interacciones de los usuarios enviando [Eventos](/es/features/events) desde tu código a las API de Trophy asociados a una métrica específica.

Cuando se registran eventos para un usuario específico, Trophy verificará automáticamente si han cumplido las condiciones de su racha para el período actual y actualizará la racha del usuario en consecuencia.

Esto es lo que hace que crear 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 la mayoría de los principales [lenguajes de programación](/es/api-reference/client-libraries).

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}
<dependency>
  <groupId>so.trophy</groupId>
  <artifactId>trophy-java</artifactId>
  <version>1.0.0</version>
</dependency>
```

```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 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 API en código del lado del cliente.

## Seguimiento de Interacciones de Usuarios

Para hacer seguimiento de un evento (interacción de usuario) asociado a tu métrica, utiliza la [API de cambio de métrica](/es/api-reference/endpoints/events/submit-a-metric-event).

```bash cURL theme={null}
curl -X POST https://api.trophy.so/v1/metrics/flashcards-flipped/event \
     -H "X-API-KEY: <apiKey>" \
     -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
)
```

> [!TIP]
>
> Al incluir la zona horaria del usuario en el atributo `tz`, Trophy
> hará seguimiento automático de las rachas según el reloj local del usuario y gestionará
> casos límite complicados donde los usuarios cambian de zona horaria.

La respuesta a esta llamada API es el conjunto completo de cambios a cualquier funcionalidad que hayas creado con Trophy, incluyendo los datos más recientes sobre la racha del usuario.

```json Response [expandable] theme={null}
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  ...,
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  },
  ...
}
```

Valida que esto funciona verificando el [panel de control](https://app.trophy.so) de Trophy.

## Visualización de Rachas

Tienes varias opciones para mostrar rachas 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) para mostrar notificaciones emergentes (o 'toasts') cuando el usuario extiende su racha.

Aquí hay un ejemplo de esto en acción:

```ts Streak Extended Pop-up theme={null}
// Sends event to Trophy
const response = await viewFlashcard();

if (!response) {
  return;
}

// Show toast if user has extended their streak
if (response.currentStreak?.extended) {
  toast({
    title: "You're on a roll!",
    description: `Keep going to keep your ${response.currentStreak.length} day streak!`,
  });
}
```

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy-ci-i18n-auto-translations/kq20NZCpkjuLyTvG/assets/guides/streaks-feature/streak-toasts.mp4?fit=max&auto=format&n=kq20NZCpkjuLyTvG&q=85&s=5b68e39f680cbbbb219c871fd5800fb6" />

> [!TIP]
>
> Si quieres reproducir efectos de sonido, usa 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 Rachas de Usuario

Para obtener datos sobre la racha de un usuario, usa la [API de racha de usuario](/es/api-reference/endpoints/users/get-a-users-streak).

```bash cURL theme={null}
curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/streak \
  --header 'X-API-KEY: <api-key>'
```

```typescript Node theme={null}
trophy.users.streak("user-id", {
  historyPeriods: 14
});
```

```python Python theme={null}
client.users.streak(
    id="user-id",
    history_periods=14,
)
```

```php PHP theme={null}
$request = new UsersStreakRequest([
    'history_periods' => 14
]);

$trophy->users->streak("user-id", $request);
```

```java Java theme={null}
UsersStreakRequest request = UsersStreakRequest.builder()
      .historyPeriods(14)
      .build();

UsersStreakResponse response = client.users().streak("user-id", request);
```

```go Go theme={null}
response, err := client.Users.Streak(
    "user-id",
    &api.UsersStreakRequest{
        HistoryPeriods: 14,
    },
)
```

```csharp C# theme={null}
var request = new UsersStreakRequest {
   HistoryPeriods = 14
};

await trophy.Users.StreaksAsync("user-id", request);
```

```ruby Ruby theme={null}
result = client.users.streak(
  :id => 'user-id',
  :history_periods => 14
)
```

Esta API no solo devuelve datos sobre la racha actual del usuario como `length` y `expires`, sino que también puede devolver datos históricos de rachas que se pueden usar para mostrar cualquier tipo de interfaz de racha que desees a través del parámetro `historyPeriods`.

```json Response [expandable] theme={null}
{
  "length": 1,
  "frequency": "weekly",
  "started": "2025-04-02",
  "periodStart": "2025-03-31",
  "periodEnd": "2025-04-05",
  "expires": "2025-04-12",
  "pauses": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "start": "2026-08-20",
      "end": "2026-08-27"
    }
  ],
  "streakHistory": [
    {
      "periodStart": "2025-03-30",
      "periodEnd": "2025-04-05",
      "length": 1,
      "usedPause": false
    },
    {
      "periodStart": "2025-04-06",
      "periodEnd": "2025-04-12",
      "length": 2,
      "usedPause": false
    },
    {
      "periodStart": "2025-04-13",
      "periodEnd": "2025-04-19",
      "length": 3,
      "usedPause": false
    },
    {
      "periodStart": "2025-04-20",
      "periodEnd": "2025-04-26",
      "length": 0,
      "usedPause": false
    },
    {
      "periodStart": "2025-04-27",
      "periodEnd": "2025-05-03",
      "length": 1,
      "usedPause": false
    },
    {
      "periodStart": "2025-05-04",
      "periodEnd": "2025-05-10",
      "length": 2,
      "usedPause": false
    },
    {
      "periodStart": "2025-05-11",
      "periodEnd": "2025-05-17",
      "length": 3,
      "usedPause": false
    }
  ]
}
```

Aquí hay un ejemplo de un calendario de rachas estilo git construido usando los datos de la respuesta anterior:

![](https://mintcdn.com/trophy-ci-i18n-auto-translations/kq20NZCpkjuLyTvG/assets/guides/streaks-feature/streak-calendar.png?fit=max\&auto=format\&n=kq20NZCpkjuLyTvG\&q=85\&s=7a869d84d939ced031c5414987dc2540)

> [!TIP]
>
> Consulta este [repositorio de ejemplo](https://github.com/trophyso/example-study-platform/blob/demo/src/app/user-center/study-center/default-view.tsx) para ver un componente React que gestiona esta interfaz usando datos de Trophy.

## Analíticas

La [página de rachas](https://app.trophy.so/streaks) en Trophy muestra datos sobre rachas activas, la longitud promedio de las rachas y las rachas más largas.

![](https://mintcdn.com/trophy-ci-i18n-auto-translations/kq20NZCpkjuLyTvG/assets/guides/streaks-feature/analytics.png?fit=max\&auto=format\&n=kq20NZCpkjuLyTvG\&q=85\&s=da83f9a3fdf54c00114ddd256bbada94)

## Congelación de Rachas

Trophy también admite congelación de rachas, lo que puede ayudar a evitar que los usuarios pierdan su racha si accidentalmente se pierden un periodo.

Obtén más información sobre la congelación de rachas en la [documentación dedicada de congelación de rachas](/es/features/streaks#streak-freezes).

## Pausas de Racha

Trophy también admite pausas de racha, que protegen la racha de un usuario durante un rango de fechas conocido en lugar de terminarla.

Obtén más información sobre las pausas de racha en la [documentación dedicada de pausas de racha](/es/features/streaks#streak-pauses).

## Obtener Soporte

¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudar!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.