> ## 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 función de energía
> Aprende a usar Trophy para añadir una función de energía a tu aplicación web o móvil.
La guía describe el proceso completo para añadir una función de energía a tu aplicación web o móvil usando Trophy.
Con fines ilustrativos, utilizaremos el ejemplo de una plataforma de estudio que usa energía para regular la velocidad a la que los usuarios pueden ver 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 cualquier número de métricas que mejor representen las interacciones desde las cuales deseas otorgar y consumir energía.
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 puntos](https://app.trophy.so/points) y crea un nuevo sistema de puntos llamado 'Energy'.
Una vez creado, serás dirigido a la página de configuración del sistema de energía donde podrás crear [activadores de puntos](/es/features/points#types-of-triggers) para cada una de las formas en que deseas otorgar o consumir energía.
Utiliza activadores de tipo 'time' para otorgar nueva energía a los usuarios cada hora o día, y usa [otros tipos](/es/features/points#types-of-triggers) de activadores con valores negativos para consumir energía según las diferentes interacciones de usuario que desees.
En Trophy rastreas las interacciones de usuario enviando [Eventos](/es/features/events) desde tu código a las APIs de Trophy contra una métrica específica.
Cuando se registran eventos para un usuario específico, Trophy verificará automáticamente si alguno de los activadores configurados para tu sistema de energía debe ejecutarse, y los procesará en consecuencia.
Trophy también se encarga de otorgar automáticamente nueva energía a los usuarios con el tiempo de acuerdo con cualquier activador de tipo 'time' que hayas configurado.
Esto es lo que hace que construir experiencias gamificadas con Trophy sea tan fácil: realiza todo el trabajo por ti en segundo plano.
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}
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 API desde la [página de integración](https://app.trophy.so/integration) de Trophy y agrégala como una variable de entorno **exclusivamente del lado del servidor**.
```bash theme={null}
TROPHY_API_KEY='*******'
```
Asegúrate de **no** exponer tu clave API en código del lado del cliente.
Rastreo de Interacciones de Usuario
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 API es el conjunto completo de cambios en cualquier funcionalidad que hayas construido con Trophy, incluyendo cualquier cambio en la energía como resultado del evento y desde qué activadores se consumió la energía.
```json Response [expandable] theme={null}
{
"metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
"eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"total": 750,
...,
"points": {
"energy": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"name": "Energy",
"description": null,
"badgeUrl": null,
"total": 9,
"added": -1,
"awards": [
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"awarded": -1,
"date": "2021-01-01T00:00:00Z",
"total": 9,
"trigger": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"type": "metric",
"metricName": "Flashcards Flipped",
"metricThreshold": 1,
"points": -1
}
}
]
}
},
...
}
```
Valida que esto funcione verificando el [panel de control](https://app.trophy.so) de Trophy.
Medición del Uso
Para evitar que los usuarios realicen acciones en tu producto basándose en energía, utiliza la [API de puntos de usuario](/es/api-reference/endpoints/users/get-a-users-points) para obtener su energía total actual.
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/users/{id}/points/{key} \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.users.points("user-id", "points-system-key");
```
```python Python theme={null}
client.users.points(
id="user-id",
key="points-system-key",
)
```
```php PHP theme={null}
$trophy->users->points("user-id", "points-system-key");
```
```java Java theme={null}
client.users().points("user-id","points-system-key");
```
```go Go theme={null}
response, err := client.Users.Points(
"user-id",
"points-system-key"
)
```
```csharp C# theme={null}
trophy.Users.PointsAsync("user-id", "points-system-key");
```
```ruby Ruby theme={null}
result = client.users.points(
:id => 'user-id',
:key => "points-system-key"
)
```
Esto devuelve datos sobre la energía total que tiene el usuario, permitiéndote usar la propiedad `total` para controlar qué acciones puede realizar un usuario:
```json Response [expandable] theme={null}
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"name": "Energy",
"description": null,
"badgeUrl": null,
"total": 10,
"awards": [
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"awarded": 1,
"date": "2021-01-01T00:00:00Z",
"total": 10,
"trigger": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"type": "time",
"points": 1,
"timeUnit": "day",
"timeInterval": 1
}
},
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"awarded": -1,
"date": "2021-01-01T00:00:00Z",
"total": 9,
"trigger": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"type": "metric",
"points": -1,
"metricName": "Flashcards Flipped",
"metricThreshold": 1
}
}
]
}
```
Aquí hay un ejemplo donde un usuario solo puede ver una tarjeta de estudio si `total > 0`
```ts theme={null}
const energy = await trophy.users.points("user-id", "energy");
if (!energy) {
return;
}
if (energy.total > 0) {
showNextFlashcard();
}
```
Luego puedes modificar la configuración de tu trigger en Trophy y controlar la frecuencia con la que los usuarios pueden interactuar con tu producto directamente desde el panel de control de Trophy sin necesidad de realizar cambios en el código.
Visualización de Energía
Para obtener la energía de un usuario, utiliza la [API de puntos de usuario](/es/api-reference/endpoints/users/get-a-users-points).
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/users/{id}/points/{key} \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.users.points("user-id", "points-system-key");
```
```python Python theme={null}
client.users.points(
id="user-id",
key="points-system-key",
)
```
```php PHP theme={null}
$trophy->users->points("user-id", "points-system-key");
```
```java Java theme={null}
client.users().points("user-id","points-system-key");
```
```go Go theme={null}
response, err := client.Users.Points(
"user-id",
"points-system-key"
)
```
```csharp C# theme={null}
trophy.Users.PointsAsync("user-id", "points-system-key");
```
```ruby Ruby theme={null}
result = client.users.points(
:id => 'user-id',
:key => "points-system-key"
)
```
Esta API devuelve datos sobre la energía total del usuario, pero puede configurarse para devolver también entre 1 y 100 de los cambios de energía más recientes del usuario usando el parámetro de consulta `awards`.
```json Response [expandable] theme={null}
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"name": "Energy",
"description": null,
"badgeUrl": null,
"total": 10,
"awards": [
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"awarded": 1,
"date": "2021-01-01T00:00:00Z",
"total": 10,
"trigger": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"type": "time",
"points": 1,
"timeUnit": "day",
"timeInterval": 1
}
},
{
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"awarded": -1,
"date": "2021-01-01T00:00:00Z",
"total": 9,
"trigger": {
"id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
"type": "metric",
"points": -1,
"metricName": "Flashcards Flipped",
"metricThreshold": 1
}
}
]
}
```
La [API de resumen de puntos de usuario](/es/api-reference/endpoints/users/get-a-users-points-summary) también puede utilizarse para crear interfaces basadas en gráficos, como mostrar a los usuarios su consumo de energía a lo largo del tiempo.
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/users/{id}/points/{key}/event-summary \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
trophy.users.pointsEventSummary("user-id", "points-system-key", {
aggregation: "daily",
start_date: "2025-01-01",
end_date: "2025-01-07"
});
```
```python Python theme={null}
client.users.points_event_summary(
id="user-id",
key="points-system-key",
aggregation="daily",
start_date="2025-01-01",
end_date="2025-01-07"
)
```
```php PHP theme={null}
$trophy->users->pointsEventSummary("user-id", "points-system-key");
```
```java Java theme={null}
client.users().pointsEventSummary("user-id","points-system-key");
```
```go Go theme={null}
response, err := client.Users.PointsEventSummary(
"user-id",
"points-system-key"
)
```
```csharp C# theme={null}
trophy.Users.PointsEventSummaryAsync("user-id", "points-system-key");
```
```ruby Ruby theme={null}
result = client.users.pointsEventSummary(
:id => 'user-id',
:key => "points-system-key"
)
```
Aquí hay un ejemplo de una interfaz que muestra a los usuarios su energía actual, un gráfico que muestra su uso a lo largo del tiempo y una lista de sus cambios de energía más recientes.
Analíticas
En Trophy, tu [página del sistema de energía](https://app.trophy.so/points) incluye gráficos de analíticas que muestran datos sobre la energía total otorgada/consumida y un desglose detallado de qué triggers causan los cambios más frecuentes en la energía.
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!