> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Bienvenido a Trophy

> Trophy es la capa de gamificación para aplicaciones de consumo. Crea puntos, logros, rachas y clasificaciones en minutos con las APIs y los SDKs prediseñados de Trophy.

Trophy es la capa de gamificación para aplicaciones de consumo. Crea puntos, logros, rachas y clasificaciones en minutos con las APIs y los SDKs prediseñados de Trophy.

## Primeros pasos

Instala un SDK de Trophy para rastrear la actividad de los usuarios y habilitar puntos, logros, rachas y clasificaciones en tu aplicación.

```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
```

> [card] [Inicio rápido](/es/getting-started/quickstart.md)
>
> Configura una cuenta de Trophy y crea tu primera funcionalidad en cinco minutos.

> [card] [Usa la API REST](/es/api-reference/introduction.md)
>
> Aprende a usar la API REST para integrar Trophy en tu aplicación.

> [card] [Consulta un ejemplo completo](https://github.com/trophyso/example-study-platform/tree/demo)
>
> Aplicación de ejemplo completa con un stack de gamificación completo que usa Trophy.

## Uso de agentes de IA

Conecta los servidores MCP de Trophy para que los agentes puedan leer la documentación actualizada y configurar tu cuenta durante la integración.

> [!TIP]
>
> Se recomienda usar los servidores MCP de Trophy para una configuración y una experiencia de desarrollo más rápidas.

> [card] [Docs MCP](/es/mcp/docs-mcp-server/introduction.md)
>
> Búsqueda en tiempo real de documentación para agentes de IA.

> [card] [Account MCP](/es/mcp/account-mcp-server/introduction.md)
>
> Configura tu cuenta de Trophy mediante agentes de IA.

> [card] [Mejores prácticas](/es/mcp/best-practice.md)
>
> Configuración recomendada para usar ambos servidores MCP juntos.

## Envía tu primer evento

Todas las funciones de gamificación están impulsadas por [eventos de métricas](/es/features/events.md). Aquí te mostramos cómo enviar tu primer evento usando un SDK de Trophy:

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

```typescript Node theme={null}
import { TrophyApiClient } from "@trophyso/node";
import type { EventResponse } from "@trophyso/node/api";

const trophy = new TrophyApiClient({
  apiKey: process.env.TROPHY_API_KEY as string,
});

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
const response: EventResponse = await trophy.metrics.event(
  "flashcards-flipped",
  {
    user: {
      id: "18",
      email: "user@example.com",
      tz: "Europe/London",
    },
    value: 1,
    // Protects against duplicate events from the same flashcard
    idempotencyKey: "flashcard-view-42",
  }
);
```

```python Python theme={null}
from trophy import Trophy
from trophy.types import EventRequestUser

client = Trophy(
    api_key=os.environ.get("TROPHY_API_KEY"),
)

# user.id is required. email and tz are optional but recommended
# (tz is required for correct streak calendar days).
response = client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=1.0,
    idempotencyKey="flashcard-view-42", # Protects against duplicate events from the same flashcard
)
```

```php PHP theme={null}
use Trophy\TrophyClient;
use Trophy\Types\EventRequestUser;
use Trophy\Types\MetricsEventRequest;

$trophy = new TrophyClient([
    'apiKey' => getenv('TROPHY_API_KEY')
]);

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com',
    'tz' => 'Europe/London',
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 1,
    // Protects against duplicate events from the same flashcard
    'idempotencyKey' => 'flashcard-view-42',
]);

$response = $trophy->metrics->event("flashcards-flipped", $request);
```

```java Java theme={null}
TrophyApiClient client = TrophyApiClient.builder()
    .apiKey(System.getenv("TROPHY_API_KEY"))
    .build();

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
MetricsEventRequest request = MetricsEventRequest.builder()
      .user(
        EventRequestUser.builder()
          .id("18")
          .email("user@example.com")
          .tz("Europe/London")
          .build()
      )
      .value(1)
      // Protects against duplicate events from the same flashcard
      .idempotencyKey("flashcard-view-42")
      .build();

EventResponse response = client.metrics().event("flashcards-flipped", request);
```

```go Go theme={null}
client, err := trophy.NewClient(
    option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
)
if err != nil {
    log.Fatal(err)
}

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
            Tz: "Europe/London",
        },
        Value: 1,
        // Protects against duplicate events from the same flashcard
        IdempotencyKey: "flashcard-view-42",
    },
)
```

```csharp C# theme={null}
var trophy = new TrophyClient(
    Environment.GetEnvironmentVariable("TROPHY_API_KEY")
);

// user.id is required. email and tz are optional but recommended
// (tz is required for correct streak calendar days).
var user = new EventRequestUser {
   Id = "18",
   Email = "user@example.com",
   Tz = "Europe/London"
};

var request = new MetricsEventRequest {
   User = user,
   Value = 1,
   // Protects against duplicate events from the same flashcard
   IdempotencyKey = "flashcard-view-42"
};

var response = await trophy.Metrics.EventAsync("flashcards-flipped", request);
```

```ruby Ruby theme={null}
client = TrophyApiClient::Client.new(
  :api_key => ENV["TROPHY_API_KEY"]
)

# user.id is required. email and tz are optional but recommended
# (tz is required for correct streak calendar days).
result = client.metrics.event(
  :key => 'flashcards-flipped',
  :user => {
    :id => '18',
    :email => 'user@example.com',
    :tz => 'Europe/London'
  },
  :value => 1,
  :idempotencyKey => 'flashcard-view-42' # Protects against duplicate events from the same flashcard
)
```

La respuesta incluye los cambios en el estado de gamificación como resultado del evento, incluyendo:

* El nuevo valor total de la métrica del usuario
* Cualquier logro desbloqueado recientemente
* Nuevos totales de Puntos y recompensas
* Un objeto de Racha actualizado
* Cualquier nueva posición en las Clasificaciones

Usa esta respuesta para reaccionar a los cambios en el estado de gamificación del usuario e impulsar elementos de UI.

```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": "Flip 500 flashcards in the app.",
      "badgeUrl": null,
      "userAttributes": [],
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12",
    "extended": true
  },
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 10,
      "level": {
        "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
        "key": "bronze",
        "name": "Bronze",
        "description": "Starting level",
        "badgeUrl": null,
        "points": 0
      },
      "added": 10,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 10,
          "date": "2021-01-01T00:00:00Z",
          "total": 10,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "Flashcards Flipped",
            "metricThreshold": 100,
            "points": 10,
            "status": "active",
            "userAttributes": [],
            "created": "2021-01-01T00:00:00Z",
            "updated": "2021-01-01T00:00:00Z"
          }
        }
      ]
    }
  },
  "leaderboards": {
    "daily_champions": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
      "key": "daily_champions",
      "name": "Daily Champions",
      "description": null,
      "status": "active",
      "rankBy": "metric",
      "runUnit": "day",
      "runInterval": 1,
      "maxParticipants": 100,
      "breakdownAttributes": [],
      "metricName": "Flashcards Flipped",
      "metricKey": "flashcards-flipped",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "startTime": null,
      "endTime": null,
      "previousRank": 50,
      "rank": 12
    }
  },
  "idempotencyKey": "flashcard-view-42",
  "idempotentReplayed": false
}
```

## Construye según el caso de uso

Para obtener más información sobre cómo construir funciones de gamificación comunes usando Trophy, consulta las siguientes guías:

> [card] [Logros](/es/guides/how-to-build-a-milestones-feature.md)
>
> Desbloquea logros a partir del progreso o acciones únicas.

> [card] [Rachas](/es/guides/how-to-build-a-streaks-feature.md)
>
> Impulsa ciclos de hábitos diarios o semanales con detección de zona horaria integrada.

> [card] [Puntos](/es/guides/how-to-build-an-xp-feature.md)
>
> Otorga puntos desde acciones dentro de la aplicación y configura niveles e impulsos.

> [card] [Clasificaciones](/es/guides/how-to-build-a-leaderboards-feature.md)
>
> Crea clasificaciones recurrentes o únicas.

> [card] [Correos electrónicos](/es/features/emails.md)
>
> Correos electrónicos del ciclo de vida impulsados por rachas, logros y actividad.

> [card] [Notificaciones push](/es/features/push-notifications.md)
>
> Flujos de notificaciones automatizadas usando datos de gamificación.

## Kit de interfaz de usuario

Implementa interfaces de gamificación más rápido con la biblioteca de componentes React de Trophy, construida sobre shadcn/ui y diseñada para trabajar con las estructuras de datos de Trophy.

> [card] [Kit de interfaz de usuario](https://ui.trophy.so)
>
> Explora componentes de interfaz preconstruidos para rachas, logros, clasificaciones, puntos y más.

## Lista de verificación de producción

Antes de implementar tu integración en producción, revisa los pasos recomendados en la lista de verificación de producción:

> [card] [Lista de verificación de producción](/es/getting-started/production-checklist.md)
>
> Pasos recomendados para asegurar que tu integración esté lista para producción.

## Precios

Trophy mide el uso por **usuarios activos mensuales (MAU)**. Un MAU es un usuario que envía al menos un [evento de métrica](/es/features/events.md) en un mes calendario determinado. No se te cobra por usuarios abandonados que dejan de enviar eventos.

El nivel gratuito incluye **1,000 MAU**. Los planes de pago comienzan en \$25/mes con cargos por excedente.

> [card] [Facturación](/es/account/billing.md)
>
> Nivel gratuito, planes de pago, asignaciones y excedentes.

> [card] [Calculadora de precios](https://trophy.so/pricing)
>
> Obtén un estimado de costos mensuales según el uso esperado.

## Obtén 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.