Users

What are Users?

Users are the individual people that use your product. You tell Trophy about your users through APIs and use the dashboard to design gamification experiences around them. Users must be individuals, they cannot be companies or organisations. To create organizational structures or user groupings, consider using a custom user attribute.

Key Attributes

Key attributes are properties of users controlled and managed by Trophy and are for things like id or email, some are required while others are optional.

Required Attributes

Trophy only requires one key attribute, id. Every user you tell Trophy about must have an id, this is what identifies them as a unique person.

string

required

This is the ID of the user in your database.

To make things simple, Trophy lets you use your own id that you already have in your database instead of needing to manage another one just for Trophy.

Optional Attributes

Additionally, you can tell Trophy about any of the following optional key attributes and it will make them available to you as part of your gamification experience:

string

The user’s full name. This is accessible in email templates and other areas where you may want to address the user by name.

string

The user’s email address. This address will be used in any Emails that you set up as part of your gamification experience with Trophy.

string

The user’s time zone. Must be specified as an IANA timezone identifier. Used for streaks, leaderboard rankings and sending emails to users in accordance with their local clock.In JavaScript, you can fetch the users time zone using this snippet:

Fetching timezone

// e.g. 'Europe/London'
const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

If you’ve configured any Trophy Emails, then they’ll only be sent to a user when this field is true. Note: If you don’t provide an email, attempting to set this field to true will result in an error.

The date the user signed up on your platform, as YYYY-MM-DD. ISO 8601 date-times are accepted and stored as their UTC calendar day. Must not be after today in the user’s timezone. This field is separate from created, which is the date Trophy first learned about the user.

array<string>

The list of device tokens to associate with the user. If you’ve configured any Trophy Push Notifications, then they’ll only be sent to a user when this field is provided.

Custom User Attributes

Los atributos de usuario personalizados son gestionados por ti y pueden ser lo 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 de la página de usuarios en el panel de Trophy y haz clic en el botón Agregar Atributo de Usuario. Asigna al atributo un nombre y una clave única. La clave es lo que usarás para hacer referencia al atributo en las llamadas a la API.

Configurar atributos

Los atributos pueden asignarse valores para usuarios específicos utilizando su clave única, ya sea en línea, cuando los usuarios incrementan métricas a través de la API de incremento de métricas, o explícitamente a través de las APIs de identificación de usuario, crear usuario o actualizar usuario.

Trophy solo establecerá valores de atributos que primero hayan sido creados en el panel. 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 mal la clave del atributo en la solicitud, o que necesites crear primero el atributo en el panel de Trophy:

{
  "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. Aquí hay un ejemplo de una carga útil de solicitud que establece el valor de dos atributos de usuario personalizados subject y plan:

{
  "name": "Joe Bloggs",
  "email": "joe.bloggs@example.com",
  "attributes": {
    "subject": "physics",
    "plan": "free"
  }
}

Uso de atributos

Utilice 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 usar para personalizar logros, personalizar la forma en que diferentes usuarios ganan puntos y más. Siga los enlaces a las páginas relevantes a continuación para obtener más información.

Personalización de logros

Configure logros que solo pueden ser desbloqueados por usuarios específicos.

Personalización de puntos

Personalice cómo diferentes usuarios ganan puntos.

Segmentación de correos electrónicos

Controle qué usuarios reciben correos electrónicos gamificados.

Personalización de correos electrónicos

Personalice el contenido y las líneas de asunto de los correos electrónicos con atributos de usuario personalizados.

Agregación y filtrado de datos

Puede usar atributos de usuario personalizados para agregar y filtrar datos devueltos por algunas APIs para admitir una amplia gama de casos de uso de gamificación. En todos los casos, los atributos se incluyen en el parámetro de consulta userAttributes usando un esquema consistente: ?userAttributes=city:london,subscription-plan:pro Aquí hay una lista de todas las APIs que admiten el parámetro de consulta userAttributes:

Resumen de puntos

Análisis segmentados

Los atributos de usuario personalizados se pueden usar para segmentar y comparar gráficos de retención y participación entre grupos de usuarios. Esto es útil para comprender qué cohortes están aprovechando al máximo sus 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 en que puedes identificar usuarios con Trophy: identificación en línea e identificación explícita.

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, pasas los detalles completos del usuario que activó el evento. Aquí hay un ejemplo donde se realiza una llamada a la API a la API de eventos de métricas, y los detalles del usuario que realizó la interacción se pasan en el cuerpo de la solicitud:

curl -X POST https://app.trophy.so/api/metrics/flashcards-flipped/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 750
}'

trophy.metrics.event("flashcards-flipped", {
  user: {
    id: "18",
    email: "user@example.com",
    tz: "Europe/London",
  },
  value: 750,
});

client.metrics.event(
    key="flashcards-flipped",
    user=EventRequestUser(
        id="18",
        email="user@example.com",
        tz="Europe/London",
    ),
    value=750.0,
)

$user = new EventRequestUser([
    'id' => '18',
    'email' => 'user@example.com'
]);

$request = new MetricsEventRequest([
    'user' => $user,
    'value' => 750
]);

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

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);

response, err := client.Metrics.Event(
    "flashcards-flipped",
    &api.MetricsEventRequest{
        User: &api.EventRequestUser{
            Id: "18",
            Email: "user@example.com",
        },
        Value: 750,
    },
)

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);

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), entonces 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.

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 código de identificación explícito escrito por ti
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 constantemente sincronizada con Trophy con la menor cantidad de código requerido de tu parte. Por eso 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 indica explícitamente a Trophy acerca de los usuarios de forma separada de cualquier interacción con métricas. Esto es útil si deseas tener control completo sobre cómo y cuándo Trophy conoce a tus usuarios. Los escenarios en los que podrías querer usar la identificación explícita podrían ser:

Quieres informar a Trophy sobre nuevos usuarios inmediatamente al registrarse, antes de que incrementen una métrica
Registras muchas métricas en Trophy y no quieres repetir el código de identificación en línea.
Quieres informar a Trophy solo sobre una cohorte específica de usuarios, de la cual controlas las condiciones

En este caso, puedes informar a Trophy sobre nuevos usuarios usando la API de Identificación de Usuarios.

curl --request PUT \
  --url https://app.trophy.so/api/users/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "email": "user@example.com",
  "name": "User",
  "tz": "Europe/London",
  "signUpDate": "2020-08-20",
  "subscribeToEmails": true
}'

Al igual que en la identificación en línea, 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, usa la API de Crear Usuario.

Mantener los Usuarios Actualizados

Para informar a Trophy sobre una actualización de un usuario en tu plataforma, puedes usar la API de Actualizar Usuario. Todas las propiedades que pases a Trophy se actualizarán a los nuevos valores que especifiques.

Como la identificación de usuarios mantiene actualizados los registros de usuarios de forma predeterminada, generalmente no es necesario actualizar explícitamente a 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.

Configuración de Preferencias de Usuario

Trophy tiene API que te ayudan a crear un centro de preferencias que tus usuarios pueden utilizar 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 Notificaciones

Puedes usar Trophy para enviar Emails y Notificaciones push gamificados a tus usuarios. La API de actualización de preferencias de Trophy te permite crear un centro de preferencias dentro de tu aplicación con el que tus usuarios pueden 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 notificaciones:

achievement_completed: Notificaciones enviadas cuando un usuario completa un logro
recap: Notificaciones resumen periódicas sobre el progreso del usuario
reactivation: Notificaciones enviadas para volver a involucrar a 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:

curl --request PATCH \
  --url https://api.trophy.so/v1/users/user-123/preferences \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "notifications": {
    "recap": ["email"],
    "streak_reminder": []
  }
}'

const response = await trophy.users.updatePreferences("user-123", {
  notifications: {
    recap: ["email"],
    streak_reminder: []
  }
});

response = client.users.update_preferences(
  id="user-123",
  notifications={
    "recap": ["email"],
    "streak_reminder": []
  }
)

$response = $trophy->users()->updatePreferences("user-123", [
  "notifications" => [
    "recap" => ["email"],
    "streak_reminder" => []
  ]
]);

UpdateUserPreferencesRequest request = UpdateUserPreferencesRequest.builder()
  .notifications(NotificationPreferences.builder()
    .recap(Arrays.asList("email"))
    .streakReminder(Collections.emptyList())
    .build())
  .build();
UserPreferencesResponse response = client.users().updatePreferences("user-123", request);

response, err := client.Users.UpdatePreferences("user-123", &UpdateUserPreferencesRequest{
  Notifications: &NotificationPreferences{
    Recap: []string{"email"},
    StreakReminder: []string{},
  },
})

var response = await trophy.Users.UpdatePreferencesAsync("user-123", new UpdateUserPreferencesRequest
{
  Notifications = new NotificationPreferences
  {
    Recap = new[] { "email" },
    StreakReminder = Array.Empty<string>()
  }
});

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 deberás obtener las preferencias actuales del usuario usando la API de obtención de preferencias. Esto devolverá la configuración de notificaciones actual del usuario, que luego puedes mostrar en tu interfaz y permitir que los usuarios modifiquen.

curl --request GET \
  --url https://api.trophy.so/v1/users/user-123/preferences \
  --header 'X-API-KEY: <api-key>'

const response = await trophy.users.getPreferences("user-123");

response = client.users.get_preferences(id="user-123")

$response = $trophy->users()->getPreferences("user-123");

UserPreferencesResponse response = client.users().getPreferences("user-123");

response, err := client.Users.GetPreferences("user-123")

var response = await trophy.Users.GetPreferencesAsync("user-123");

response = client.users.get_preferences(id: "user-123")

El API devuelve una respuesta que contiene las preferencias de notificación actuales del usuario para cada tipo de notificación:

Response

{
  "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 el API de actualización de preferencias para guardar sus selecciones de vuelta en Trophy.

Preferencias de Racha

Trophy admite preferencias de usuario para rachas, permitiendo a los usuarios personalizar las condiciones que deben cumplir para extender su racha, incluyendo qué días de la semana cuentan para ella.

Para usar las preferencias de racha, debes tener habilitada la personalización de rachas.

Una vez habilitada la personalización de rachas, el API de actualización de preferencias te permitirá anular la configuración predeterminada de rachas para un usuario específico. Las siguientes configuraciones de racha pueden ser anuladas por las preferencias del usuario:

enabled: Si se calculan las rachas para este usuario. Cuando es false, la racha del usuario es siempre 0 y no se envían webhooks ni notificaciones de racha.
metrics: Un array de métricas con umbrales personalizados requeridos para extender la racha.
evaluationMode: Determina cómo se combinan las métricas para extender la racha. Puede ser ALL o OR.
daysOff: Un array de números de días de la semana (0 = domingo hasta 6 = sábado) que anulan los días libres de la organización. El usuario no perderá su racha si está inactivo en estos días.

Streak preferences

{
  "streak": {
    "enabled": true,
    "evaluationMode": "OR",
    "daysOff": [1, 3, 5],
    "metrics": [
      { "key": "words-written", "threshold": 500 }
    ]
  }
}

Una vez configuradas las preferencias de racha, la API de obtener preferencias devolverá la configuración personalizada de racha del usuario.

Obtención de información del usuario

Para obtener los detalles de un usuario que ya hayas identificado con Trophy, utiliza la API Get 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.

Response

{
  "id": "user-id",
  "control": false,
  "created": "2021-01-01T00:00:00Z",
  "email": "user@example.com",
  "name": "User",
  "signUpDate": "2020-08-20",
  "subscribeToEmails": true,
  "tz": "Europe/London",
  "updated": "2021-01-01T00:00:00Z"
}

Analíticas de usuarios

Analíticas básicas

Por defecto, Trophy incluye analíticas de usuarios de alto nivel en la página de Usuarios, incluyendo:

El número total de usuarios sobre 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 destacados

Además, en el Panel de control, Trophy muestra una lista de Usuarios destacados con el conjunto de usuarios que han logrado el mayor progreso en las Métricas de tu plataforma. ¡Estos son tus usuarios más comprometidos, por lo que es útil saber quiénes son!

Preguntas frecuentes

¿Cuántos usuarios puedo informar a Trophy?

¡Todos los que quieras! Trophy solo cobra cada mes por los usuarios activos, que son los usuarios 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 él 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 los costos de uso en nuestra página de Precios.

Obtener Soporte

¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por correo electrónico. ¡Estamos aquí para ayudarte!

Getting Started

Features

Platform

Account

What are Users?

Key Attributes

Required Attributes

Optional Attributes

Custom User Attributes

Crear atributos

Configurar atributos

Uso de atributos

Personalización de funciones

Personalización de logros

Personalización de puntos

Segmentación de correos electrónicos

Personalización de correos electrónicos

Agregación y filtrado de datos

Análisis segmentados

Identificación de usuarios

Identificación en línea

Identificación Explícita

Crear Usuarios

Mantener los Usuarios Actualizados

Configuración de Preferencias de Usuario

Preferencias de Notificaciones

Preferencias de Racha

Obtención de información del usuario

Analíticas de usuarios

Analíticas básicas

Usuarios destacados

Preguntas frecuentes

Obtener Soporte

​What are Users?

​Key Attributes

​Required Attributes

​Optional Attributes

​Custom User Attributes

​Crear atributos

​Configurar atributos

​Uso de atributos

​Personalización de funciones

Personalización de logros

Personalización de puntos

Segmentación de correos electrónicos

Personalización de correos electrónicos

​Agregación y filtrado de datos

​Análisis segmentados

​Identificación de usuarios

​Identificación en línea

​Identificación Explícita

​Crear Usuarios

​Mantener los Usuarios Actualizados

​Configuración de Preferencias de Usuario

​Preferencias de Notificaciones

​Preferencias de Racha

​Obtención de información del usuario

​Analíticas de usuarios

​Analíticas básicas

​Usuarios destacados

​Preguntas frecuentes

​Obtener Soporte

What are Users?

Key Attributes

Required Attributes

Optional Attributes

Custom User Attributes

Crear atributos

Configurar atributos

Uso de atributos

Personalización de funciones

Agregación y filtrado de datos

Análisis segmentados

Identificación de usuarios

Identificación en línea

Identificación Explícita

Crear Usuarios

Mantener los Usuarios Actualizados

Configuración de Preferencias de Usuario

Preferencias de Notificaciones

Preferencias de Racha

Obtención de información del usuario

Analíticas de usuarios

Analíticas básicas

Usuarios destacados

Preguntas frecuentes

Obtener Soporte