Cómo construir una función de XP

La guía describe el proceso completo para añadir una función de XP a tu aplicación web o móvil usando Trophy. Con fines ilustrativos, usaremos el ejemplo de una plataforma de estudio que utiliza XP para recompensar a los usuarios por realizar diferentes interacciones.

Para ver un ejemplo completamente funcional de esto en la práctica, consulta la demostración en vivo o el repositorio de github.

Requisitos previos

Una cuenta de Trophy
Aproximadamente 10 minutos

Configuración de Trophy

En Trophy, las Métricas son los bloques de construcción de la gamificación y modelan las diferentes interacciones que los usuarios tienen 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 por las que deseas recompensar XP. En el panel de Trophy, dirígete a la página de métricas y crea una métrica.

Una vez que hayas creado tu métrica, dirígete a la página de puntos y crea un nuevo sistema de puntos llamado ‘XP’.

Una vez creado, serás redirigido a la página de configuración del sistema de XP donde puedes crear ‘disparadores’ para cada una de las formas en que deseas recompensar a los usuarios con XP.

En Trophy rastrear las interacciones de los usuarios se hace enviando Eventos 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 el evento está asociado a una métrica configurada como parte de algún disparador de XP. Si es así, Trophy otorgará al usuario la cantidad apropiada de XP según la configuración del disparador. Esto es lo que hace que construir experiencias gamificadas con Trophy sea tan fácil: hace todo el trabajo por ti detrás de escena.

El XP también puede otorgarse a los usuarios en base a logros, rachas y otros disparadores. Consulta la documentación de puntos dedicada para más información.

Instalación del SDK de Trophy

Para interactuar con Trophy desde tu código utilizarás el SDK de Trophy disponible en los principales lenguajes de programación. Instala el SDK de Trophy:

npm install @trophyso/node

gem install trophy_api_client

pip install trophy

composer require trophyso/php

implementation 'so.trophy:trophy-java:1.0.0'

<dependency>
  <groupId>so.trophy</groupId>
  <artifactId>trophy-java</artifactId>
  <version>1.0.0</version>
</dependency>

go get github.com/trophy-so/trophy-go

// .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 de Trophy y agrégala como una variable de entorno exclusivamente del lado del servidor.

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.

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
)

La respuesta a esta llamada API es el conjunto completo de cambios en cualquier característica que hayas construido con Trophy, incluyendo cualquier XP que se haya otorgado al usuario como resultado del evento, y desde qué disparadores se otorgó.

Si utilizas Niveles de Puntos, el objeto xp puede incluir un campo level solo cuando el nivel del usuario cambió en esta solicitud; puede omitirse cuando su nivel permaneció igual. Consulta la referencia de la API de cambio de métrica para el esquema completo de respuesta.

Response

{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 900,
  ...,
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 450,
      "added": 50,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 50,
          "date": "2021-01-01T00:00:00Z",
          "total": 450,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "Flashcards Flipped",
            "metricThreshold": 100,
            "points": 50
          }
        }
      ]
    }
  },
  ...
}

Valida que esto esté funcionando revisando el panel de control de Trophy.

Mostrar XP

Tienes varias opciones para mostrar XP 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 para mostrar a los usuarios notificaciones emergentes cuando se les otorga nuevo XP. Aquí hay un ejemplo de esto en acción:

XP Pop-ups

// Sends event to Trophy
const response = await viewFlashcard();

if (!response) {
  return;
}

const xp = response.points.xp;

// Show toast if user was awarded XP
if (xp.awards.length > 0) {
  const trigger = xp.awards[0].trigger;

  toast({
    title: `You gained ${xp.added} XP`,

    // e.g. "+20 XP for 10 flashcards flipped"
    description: `+${trigger.points} XP for ${
      trigger.metricThreshold
    } ${trigger.metricName.toLowercase()}`,
  });
}

Si deseas reproducir efectos de sonido, usa la API de Audio HTML5 y siéntete libre de usar estos archivos de audio que recomendamos.

Mostrar XP del Usuario

Para obtener el XP de un usuario, utiliza la API de Puntos del usuario.

curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/points/{key} \
  --header 'X-API-KEY: <api-key>'

trophy.users.points("user-id", "points-system-key");

client.users.points(
    id="user-id",
    key="points-system-key",
)

$trophy->users->points("user-id", "points-system-key");

client.users().points("user-id","points-system-key");

response, err := client.Users.Points(
    "user-id",
    "points-system-key"
)

trophy.Users.PointsAsync("user-id", "points-system-key");

result = client.users.points(
  :id => 'user-id',
  :key => "points-system-key"
)

Esta API devuelve datos sobre el XP total del usuario, pero puede configurarse para devolver también entre 1 y 100 de las recompensas de XP más recientes del usuario mediante el parámetro de consulta awards.

Response

{
  "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "key": "xp",
  "name": "XP",
  "description": null,
  "badgeUrl": null,
  "maxPoints": null,
  "total": 100,
  "level": {
    "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
    "key": "silver",
    "name": "Silver",
    "description": "Mid-tier level",
    "badgeUrl": null,
    "points": 50
  },
  "awards": [
    {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "awarded": 10,
      "date": "2021-01-01T00:00:00Z",
      "total": 100,
      "trigger": {
        "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
        "type": "metric",
        "points": 10,
        "metricName": "Flashcards Flipped",
        "metricThreshold": 1000
      }
    }
  ]
}

Aquí hay un ejemplo de una interfaz que muestra a los usuarios una lista de sus recompensas más recientes basada en los datos devueltos por la API de Puntos del usuario.

Gráfico de XP del Usuario

La API de resumen de Puntos del usuario devuelve datos históricos listos para graficar que muestran cómo ha cambiado el XP de un usuario a lo largo del tiempo.

curl --request GET \
  --url https://api.trophy.so/v1/users/{id}/points/{key}/event-summary \
  --header 'X-API-KEY: <api-key>'

trophy.users.pointsEventSummary("user-id", "points-system-key", {
  aggregation: "daily",
  start_date: "2025-01-01",
  end_date: "2025-01-07"
});

client.users.points_event_summary(
  id="user-id",
  key="points-system-key",
  aggregation="daily",
  start_date="2025-01-01",
  end_date="2025-01-07"
)

$trophy->users->pointsEventSummary("user-id", "points-system-key");

client.users().pointsEventSummary("user-id","points-system-key");

response, err := client.Users.PointsEventSummary(
    "user-id",
    "points-system-key"
)

trophy.Users.PointsEventSummaryAsync("user-id", "points-system-key");

result = client.users.pointsEventSummary(
  :id => 'user-id',
  :key => "points-system-key"
)

Utiliza los parámetros de consulta aggregation, start_date y end_date para controlar los datos devueltos. Aquí hay un ejemplo de datos de XP agregados diariamente:

GET /users/{id}/points/{key}/event-summary — 200 response

[
  {
    "date": "2024-01-01",
    "total": 100,
    "change": 100
  },
  {
    "date": "2024-01-02",
    "total": 300,
    "change": 200
  },
  {
    "date": "2024-01-03",
    "total": 600,
    "change": 300
  }
]

Y aquí hay un ejemplo de los tipos de gráficos que puedes construir con estos datos:

Analíticas

En Trophy, tu página del sistema de xp incluye gráficos de analíticas que muestran datos sobre el total de XP ganado y un desglose exacto de qué desencadenadores otorgan la mayor cantidad de XP.

Obtener Soporte

¿Quieres contactar con el equipo de Trophy? Comunícate con nosotros por correo electrónico. ¡Estamos aquí para ayudarte!

Guías de funcionalidades

Casos de uso

Cómo construir una función de XP

Requisitos previos

Configuración de Trophy

Instalación del SDK de Trophy

Rastreo de Interacciones de Usuario

Mostrar XP

Notificaciones Emergentes

Mostrar XP del Usuario

Gráfico de XP del Usuario

Analíticas

Obtener Soporte

​Requisitos previos

​Configuración de Trophy

​Instalación del SDK de Trophy

​Rastreo de Interacciones de Usuario

​Mostrar XP

​Notificaciones Emergentes

​Mostrar XP del Usuario

​Gráfico de XP del Usuario

​Analíticas

​Obtener Soporte

Requisitos previos

Configuración de Trophy

Instalación del SDK de Trophy

Rastreo de Interacciones de Usuario

Mostrar XP

Notificaciones Emergentes

Mostrar XP del Usuario

Gráfico de XP del Usuario

Analíticas

Obtener Soporte