> ## 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.
# Usuarios
> Aprende a rastrear interacciones en tu base de usuarios usando Trophy.
¿Qué son los Usuarios?
Los usuarios son las personas individuales que usan tu producto. Le informas a Trophy sobre tus usuarios a través de APIs y usas el panel de control para diseñar experiencias de gamificación en torno a ellos.
Los usuarios deben ser individuos, no pueden ser empresas u organizaciones. Para crear estructuras organizacionales o agrupaciones de usuarios, considera usar un [atributo de usuario personalizado](#custom-user-attributes).
Atributos Clave
Los atributos clave son propiedades de los usuarios controladas y gestionadas por Trophy y son para cosas como `id` o `email`, algunos son obligatorios mientras que otros son opcionales.
Atributos Obligatorios
Trophy solo requiere un atributo clave, `id`. Cada usuario sobre el que informes a Trophy debe tener un `id`, esto es lo que los identifica como una persona única.
Este es el ID del usuario en **tu** base de datos.
Para simplificar las cosas, Trophy te permite usar tu propio `id` que ya tienes
en tu base de datos en lugar de necesitar gestionar otro solo para Trophy.
Atributos Opcionales
Además, puedes informarle a Trophy sobre cualquiera de los siguientes atributos clave opcionales y los pondrá a tu disposición como parte de tu experiencia de gamificación:
El nombre completo del usuario. Es accesible en plantillas de correo electrónico y otras áreas
donde quieras dirigirte al usuario por su nombre.
La dirección de correo electrónico del usuario. Esta dirección se utilizará en cualquier
[Email](/es/features/emails) que configures como parte de tu
experiencia de gamificación con Trophy.
La zona horaria del usuario. Debe especificarse como un [identificador de zona horaria IANA](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
Se utiliza para rachas, clasificaciones de leaderboard y para enviar correos electrónicos a los usuarios de acuerdo con su hora local.
En JavaScript, puedes obtener la zona horaria del usuario usando este fragmento:
```js Fetching timezone theme={null}
// e.g. 'Europe/London'
const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
```
Si has configurado algún [Email](/es/features/emails) de Trophy, solo se
enviará a un usuario cuando este campo sea true. Nota: Si no proporcionas un
`email`, intentar establecer este campo en true resultará en un error.
La lista de tokens de dispositivo para asociar con el usuario. Si has configurado alguna
[Notificación push](/es/features/push-notifications) de Trophy, solo se
enviará a un usuario cuando este campo se proporcione.
Atributos de Usuario Personalizados
Esta función está disponible en el plan [Pro](/es/account/billing#pro-plan)
Los atributos de usuario personalizados son gestionados por ti y pueden ser cualquier cosa que desees según tu caso de uso.
Por ejemplo, una aplicación de aprendizaje de idiomas podría usar un atributo de usuario personalizado para el idioma que está aprendiendo un usuario, o una plataforma de estudio podría usar uno para la materia favorita del usuario.
Los atributos de usuario personalizados te permiten informar a Trophy sobre esta información contextual y utilizarla para personalizar las funciones de gamificación.
Crear Atributos
Para crear un nuevo atributo de usuario personalizado, dirígete a la [pestaña de atributos](https://app.trophy.so/users/attributes) de la página de usuarios en el panel de Trophy y haz clic en el botón *Agregar Atributo de Usuario*.
Asigna un nombre y una clave única al atributo. La clave es lo que utilizarás para referenciar el atributo en las llamadas a la API.
Configuración de atributos
Los atributos pueden recibir valores para usuarios específicos utilizando su clave única, ya sea de forma integrada, cuando los usuarios incrementan métricas a través de la [API de incremento de métricas](/es/api-reference/endpoints/metrics/send-a-metric-change-event), o explícitamente mediante las APIs de [identificación de usuario](/es/api-reference/endpoints/users/identify-a-user), [creación de usuario](/es/api-reference/endpoints/users/create-a-user) o [actualización de usuario](/es/api-reference/endpoints/users/update-a-user).
Trophy solo establecerá valores de atributos que hayan sido creados previamente
en el panel de control. Hacemos esto para ayudarte a mantener un conjunto limpio de atributos y
prevenir sobrescrituras accidentales.
Si recibes un error similar al siguiente, es posible que hayas escrito incorrectamente la clave del atributo en la solicitud, o que necesites crear primero el atributo en el panel de control de Trophy:
```json theme={null}
{
"error": "Invalid attribute keys: pln. Please ensure all attribute keys match those set up at https://app.trophy.so/users/attributes."
}
```
En todas las APIs, el esquema para establecer valores de atributos es consistente. Este es un ejemplo de una carga útil de solicitud que establece el valor de dos atributos de usuario personalizados `subject` y `plan`:
```json {4-7} theme={null}
{
"name": "Joe Bloggs",
"email": "joe.bloggs@example.com",
"attributes": {
"subject": "physics",
"plan": "free"
}
}
```
Uso de atributos
Utiliza atributos de usuario personalizados en Trophy para personalizar funciones de gamificación, agregar y filtrar datos devueltos por las APIs, y para segmentar y comparar cohortes de usuarios en análisis.
Personalización de funciones
Los atributos de usuario personalizados se pueden utilizar para personalizar logros, personalizar la forma en que diferentes usuarios ganan puntos y más. Sigue los enlaces a las páginas relevantes a continuación para obtener más información.
Configura logros que solo puedan ser desbloqueados por usuarios específicos.
Personaliza cómo diferentes usuarios ganan puntos.
Controla qué usuarios reciben correos gamificados.
Personaliza el texto y las líneas de asunto de los correos con atributos de usuario personalizados.
Agregación y Filtrado de Datos
Puedes utilizar atributos de usuario personalizados para agregar y filtrar datos devueltos por algunas APIs, lo que permite una amplia variedad de casos de uso de gamificación. En todos los casos, los atributos se incluyen en el parámetro de consulta `userAttributes` utilizando un esquema consistente:
`?userAttributes=city:london,subscription-plan:pro`
Aquí está la lista de todas las APIs que admiten el parámetro de consulta `userAttributes`:
* [Resumen de Puntos](/es/api-reference/endpoints/points/get-points-summary)
Analítica Segmentada
Los atributos de usuario personalizados se pueden utilizar para segmentar y comparar gráficos de retención y participación entre grupos de usuarios.
Esto es útil para entender qué cohortes están aprovechando al máximo tus funciones de gamificación y cuáles tienen dificultades para participar y, por lo tanto, requieren atención.
Identificación de Usuarios
Cuando le informas a Trophy sobre un usuario en tu plataforma, llamamos a esto **identificación**. Hay dos formas de identificar usuarios con Trophy: identificación [en línea](#inline-identification) e identificación [explícita](#explicit-identification).
Recomendamos comenzar con la identificación en línea si eres nuevo en
Trophy. Si decides que necesitas más control, prueba la identificación explícita.
Identificación en Línea
La identificación en línea es la forma más sencilla de informar a Trophy sobre tus usuarios, ya que no requiere ningún código específico de identificación de usuarios. Simplemente le informas a Trophy sobre los usuarios a medida que utilizan normalmente tu plataforma.
En la práctica, esto significa que cada vez que utilizas la [API de Eventos de Métricas](/es/api-reference/endpoints/metrics/send-a-metric-change-event), proporcionas los detalles completos del usuario que desencadenó el evento.
Aquí hay un ejemplo donde se realiza una llamada a la API de eventos de métricas, y los detalles del usuario que realizó la interacción se incluyen en el cuerpo de la solicitud:
```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
)
```
En este caso, si esta es la primera interacción del usuario (es decir, es un usuario nuevo), se creará automáticamente un nuevo registro para él en Trophy.
Sin embargo, si Trophy encuentra un registro existente con el mismo `id`, entonces Trophy actualizará cualquier detalle del usuario que se pase.
En otras palabras, la identificación en línea se realiza mediante una operación `UPSERT`.
```mermaid theme={null}
flowchart LR
A@{ shape: sm-circ }
B@{ shape: diamond, label: "Is new user?" }
C@{ shape: rounded, label: "Identify new user" }
D@{ shape: rounded, label: "Update existing user" }
E@{ shape: rounded, label: "Process event" }
F@{ shape: framed-circle }
A-->B
B-- Yes --->C
B-- No --->D
C-->E
D-->E
E-->F
```
Identificar usuarios de esta manera tiene dos beneficios clave:
* Todos los usuarios nuevos que se registren en tu plataforma e incrementen una métrica se rastrean automáticamente en Trophy sin necesidad de escribir código de identificación explícito
* Cualquier cambio en las propiedades de usuarios existentes, como nombre o dirección de correo electrónico, se sincroniza automáticamente con Trophy la próxima vez que el usuario incremente una métrica
De esta manera, la identificación en línea te permite mantener toda tu base de usuarios en sincronización constante con Trophy con la menor cantidad de código requerido de tu parte.
Por esta razón, recomendamos comenzar primero con la identificación en línea y luego explorar la identificación explícita si descubres que necesitas más control.
Identificación Explícita
La identificación explícita es cuando escribes código en tu aplicación que le indica explícitamente a Trophy sobre los usuarios de forma separada a cualquier interacción de métricas. Esto es útil si deseas tener control completo sobre cómo y cuándo Trophy se entera de tus usuarios.
Los escenarios en los que podrías querer usar identificación explícita incluyen:
* Quieres informar a Trophy sobre usuarios nuevos inmediatamente al registrarse, antes de que incrementen una métrica
* Rastrear muchas métricas en Trophy y no quieres repetir código de identificación en línea
* Quieres informar a Trophy solo sobre una cohorte específica de usuarios, sobre la cual controlas las condiciones
En este caso, puedes informar a Trophy sobre nuevos usuarios utilizando la [API de Identificación de Usuarios](/es/api-reference/endpoints/users/identify-a-user).
```bash cURL theme={null}
curl --request PUT \
--url https://app.trophy.so/api/users/{id} \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--data '{
"email": "user@example.com",
"name": "User",
"tz": "Europe/London",
"subscribeToEmails": true
}'
```
Al igual que en la identificación inline, la identificación explícita también funciona mediante
una operación `UPSERT`, lo que significa que todos los atributos de usuario se mantienen sincronizados
con Trophy automáticamente.
Crear Usuarios
Para crear explícitamente un nuevo usuario en Trophy, utiliza la [API de Crear Usuario](/es/api-reference/endpoints/users/create-a-user).
Mantener Usuarios Actualizados
Para informar a Trophy sobre una actualización de un usuario en tu plataforma, puedes utilizar la [API de Actualizar Usuario](/es/api-reference/endpoints/users/update-a-user).
Todas las propiedades que pases a Trophy se actualizarán a los nuevos valores que especifiques.
Como la [identificación de usuarios](#identifying-users) mantiene los registros de usuario actualizados por
defecto, normalmente no es necesario actualizar explícitamente los usuarios en Trophy cada
vez que una de sus propiedades cambia en tu aplicación. Sin embargo, la API de
actualización de usuarios está disponible si realmente la necesitas.
Configurar Preferencias de Usuario
Trophy tiene APIs para ayudarte a crear un centro de preferencias que tus usuarios puedan usar para controlar y personalizar cómo interactúan con tus funciones de gamificación.
Esta sección explica todas las preferencias que puedes exponer a tus usuarios y su función.
Preferencias de Notificación
Puedes usar Trophy para enviar [Emails](/es/features/emails) y [Notificaciones push](/es/features/push-notifications) gamificados a tus usuarios.
La [API de actualizar preferencias](/es/api-reference/endpoints/users/update-user-preferences) de Trophy te permite construir un centro de preferencias dentro de tu aplicación con el que tus usuarios puedan interactuar para controlar qué notificaciones reciben y a través de qué canales.
La API te permite actualizar las preferencias de notificación de un usuario para diferentes tipos de notificación:
* **achievement\_completed**: Notificaciones enviadas cuando un usuario completa un logro
* **recap**: Notificaciones de resumen periódicas sobre el progreso del usuario
* **reactivation**: Notificaciones enviadas para reactivar usuarios inactivos
* **streak\_reminder**: Recordatorios para ayudar a los usuarios a mantener sus rachas
Para cada tipo de notificación, puedes especificar en qué canales debe recibir notificaciones el usuario: `email`, `push`, o ambos. Para desactivar completamente un tipo de notificación, pasa un array vacío.
Por ejemplo, el siguiente fragmento de código actualiza las preferencias de notificación de un usuario en Trophy:
```bash cURL theme={null}
curl --request PATCH \
--url https://api.trophy.so/v1/users/user-123/preferences \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--data '{
"notifications": {
"recap": ["email"],
"streak_reminder": []
}
}'
```
```typescript Node theme={null}
const response = await trophy.users.updatePreferences("user-123", {
notifications: {
recap: ["email"],
streak_reminder: []
}
});
```
```python Python theme={null}
response = client.users.update_preferences(
id="user-123",
notifications={
"recap": ["email"],
"streak_reminder": []
}
)
```
```php PHP theme={null}
$response = $trophy->users()->updatePreferences("user-123", [
"notifications" => [
"recap" => ["email"],
"streak_reminder" => []
]
]);
```
```java Java theme={null}
UpdateUserPreferencesRequest request = UpdateUserPreferencesRequest.builder()
.notifications(NotificationPreferences.builder()
.recap(Arrays.asList("email"))
.streakReminder(Collections.emptyList())
.build())
.build();
UserPreferencesResponse response = client.users().updatePreferences("user-123", request);
```
```go Go theme={null}
response, err := client.Users.UpdatePreferences("user-123", &UpdateUserPreferencesRequest{
Notifications: &NotificationPreferences{
Recap: []string{"email"},
StreakReminder: []string{},
},
})
```
```csharp C# theme={null}
var response = await trophy.Users.UpdatePreferencesAsync("user-123", new UpdateUserPreferencesRequest
{
Notifications = new NotificationPreferences
{
Recap = new[] { "email" },
StreakReminder = Array.Empty()
}
});
```
```ruby Ruby theme={null}
response = client.users.update_preferences(
id: "user-123",
notifications: {
recap: ["email"],
streak_reminder: []
}
)
```
Para crear una interfaz de centro de preferencias en tu aplicación, primero necesitarás obtener las preferencias actuales del usuario usando la [API de obtención de preferencias](/es/api-reference/endpoints/users/get-user-preferences).
Esto devolverá la configuración de notificaciones actual del usuario, que luego podrás mostrar en tu interfaz y permitir que los usuarios modifiquen.
```bash cURL theme={null}
curl --request GET \
--url https://api.trophy.so/v1/users/user-123/preferences \
--header 'X-API-KEY: '
```
```typescript Node theme={null}
const response = await trophy.users.getPreferences("user-123");
```
```python Python theme={null}
response = client.users.get_preferences(id="user-123")
```
```php PHP theme={null}
$response = $trophy->users()->getPreferences("user-123");
```
```java Java theme={null}
UserPreferencesResponse response = client.users().getPreferences("user-123");
```
```go Go theme={null}
response, err := client.Users.GetPreferences("user-123")
```
```csharp C# theme={null}
var response = await trophy.Users.GetPreferencesAsync("user-123");
```
```ruby Ruby theme={null}
response = client.users.get_preferences(id: "user-123")
```
La API devuelve una respuesta que contiene las preferencias de notificación actuales del usuario para cada tipo de notificación:
```json Response {3} theme={null}
{
"notifications": {
"achievement_completed": ["email", "push"],
"recap": ["email"],
"reactivation": ["push"],
"streak_reminder": ["email", "push"]
}
}
```
Puedes usar esta respuesta para:
* **Rellenar controles de formulario**: Preseleccionar casillas de verificación o interruptores en tu interfaz de centro de preferencias según los valores actuales
* **Mostrar el estado actual**: Mostrar qué notificaciones están habilitadas y a través de qué canales
* **Manejar preferencias faltantes**: Si un tipo de notificación no está presente en la respuesta, significa que el usuario aún no ha establecido preferencias para él, y puedes usar la configuración predeterminada de tu aplicación
Una vez que hayas obtenido y mostrado las preferencias, los usuarios pueden realizar cambios en tu interfaz, y puedes usar la [API de actualización de preferencias](/es/api-reference/endpoints/users/update-user-preferences) para guardar sus selecciones de vuelta en Trophy.
Preferencias de Racha
Trophy permite configurar las preferencias de racha de los usuarios, lo que les permite personalizar las condiciones que deben cumplir para extender su racha.
Para usar las preferencias de racha, debes tener la [personalización de rachas](/es/features/streaks#streak-personalization) habilitada.
Una vez habilitada la personalización de rachas, la [API de actualización de preferencias](/es/api-reference/endpoints/users/update-user-preferences) te permitirá sobrescribir la configuración predeterminada de rachas para un usuario específico.
Las siguientes configuraciones de racha pueden ser sobrescritas por las preferencias del usuario:
* `evaluationMode`: Determina cómo se combinan las métricas para extender la racha. Puede ser `ALL` o `OR`.
* `metrics`: Un array de métricas con umbrales personalizados requeridos para extender la racha.
```json Streak preferences theme={null}
{
"streak": {
"evaluationMode": "OR",
"metrics": [
{ "key": "words-written", "threshold": 500 }
]
}
}
```
Una vez configuradas las preferencias de racha, la [API de obtención de preferencias](/es/api-reference/endpoints/users/get-user-preferences) devolverá la configuración personalizada de rachas del usuario.
Para obtener los detalles de un usuario que ya has identificado con Trophy, utiliza la [API Get User](/es/api-reference/endpoints/users/get-a-single-user).
Esto devolverá los detalles completos del usuario junto con el atributo `control` que puedes usar para inscribir condicionalmente a los usuarios en cualquier funcionalidad de gamificación. Obtén más información sobre [Experimentación](/es/platform/experimentation).
```json Response {3} theme={null}
{
"id": "user-id",
"control": false,
"created": "2021-01-01T00:00:00Z",
"email": "user@example.com",
"name": "User",
"subscribeToEmails": true,
"tz": "Europe/London",
"updated": "2021-01-01T00:00:00Z"
}
```
Analíticas de Usuario
Analíticas Básicas
Por defecto, Trophy incluye analíticas de usuario de alto nivel en la [página de Usuarios](https://app.trophy.so/users) que incluyen:
* El número total de usuarios de los que le has informado a Trophy
* El número de usuarios que están activos diariamente
* El número de usuarios que están activos mensualmente
En esta página también puedes buscar entre todos los usuarios que Trophy ha registrado, lo cual puede ser útil para depuración.
Usuarios Principales
Además, en el [Panel de Control](https://app.trophy.so), Trophy muestra una lista de *Usuarios Principales* con el conjunto de usuarios que han logrado el mayor progreso con respecto a las métricas de tu plataforma.
¡Estos son tus usuarios más comprometidos, por lo que es útil saber quiénes son!
Preguntas Frecuentes
¡Todos los que quieras! Trophy solo cobra cada mes por los usuarios *activos*, que son aquellos que interactúan con tu producto al menos una vez en un mes determinado.
Esto es excelente porque significa que si un usuario abandona, no pagarás por ellos en los meses siguientes.
Puedes ver el número total de usuarios por los que se te cobrará cada mes dentro de Trophy en la barra lateral:
Puedes estimar tus costos de uso en nuestra [página de Precios](https://trophy.so/pricing).
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!