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.

Los activadores de puntos añaden XP automáticamente al saldo de un usuario. Si quieres que los usuarios reclamen el XP antes de que se aplique, usa en su lugar una recompensa de puntos.

En Trophy, haces seguimiento de las interacciones de los usuarios enviando eventos desde tu código a la API de Trophy para una métrica específica. Cuando se registran eventos para un usuario concreto, Trophy comprueba automáticamente si el evento corresponde a una métrica configurada como parte de algún activador de XP. Si es así, Trophy otorga al usuario la cantidad de XP correspondiente según la configuración del activador. Esto es lo que hace tan fácil crear experiencias gamificadas con Trophy: hace todo el trabajo por ti en segundo plano.

También se puede otorgar XP a los usuarios en función de logros, rachas y otros activadores. Consulta la documentación de puntos para obtener más información.

Instalar el SDK de Trophy

Para interactuar con Trophy desde tu código, usarás el SDK de Trophy, disponible en la mayoría de 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 de API en la página de integración de Trophy y añádela como una variable de entorno solo del lado del servidor.

TROPHY_API_KEY='*******'

Asegúrate de no exponer tu clave de API en el código del lado del cliente.

Seguimiento de las interacciones de los usuarios

Para registrar un evento (una interacción del usuario) en tu métrica, usa la API de cambio de métrica.

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

import type { EventResponse } from "@trophyso/node/api";

const response: EventResponse = await trophy.metrics.event(
  "flashcards-flipped",
  {
    user: {
      id: "18",
      email: "user@example.com",
      tz: "Europe/London",
    },
    value: 750,
    idempotencyKey: "flashcard-view-42",
  }
);

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 a la API es el conjunto completo de cambios en las funciones que hayas creado con Trophy, incluido el XP otorgado al usuario como resultado del evento y los activadores que lo otorgaron.

Si usas Niveles de Puntos, el objeto xp puede incluir un campo level solo cuando el nivel del usuario haya cambiado en esta solicitud; puede omitirse si su nivel no ha cambiado. Consulta la referencia de la API de cambio de métrica para ver el esquema de respuesta completo.

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
          }
        }
      ]
    }
  },
  ...
}

Comprueba que todo funciona correctamente revisando el panel de Trophy.

Mostrar XP

Tienes varias opciones para mostrar XP en tu aplicación. Aquí veremos las más habituales.

Notificaciones emergentes

Podemos usar la respuesta de la API de cambio de métrica para mostrar notificaciones emergentes a los usuarios cuando se les otorga XP. Este es un ejemplo 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 quieres reproducir efectos de sonido, usa la API de audio de HTML5 y no dudes en copiar estos archivos de audio que recomendamos.

Mostrar la XP del usuario

Para obtener la XP de un usuario, usa la API de puntos de 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 la XP total del usuario, pero también puede configurarse para devolver 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
      }
    }
  ]
}

Este es un ejemplo de una interfaz que muestra a los usuarios una lista de sus recompensas más recientes, a partir de los datos devueltos por la API de puntos de usuario.

Gráfico de XP del usuario

La API de resumen de puntos de usuario devuelve datos históricos listos para graficar que muestran cómo ha cambiado la XP de un usuario con el 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"
)

Usa los parámetros de consulta aggregation, start_date y end_date para controlar los datos devueltos. Este es un ejemplo de datos de XP agregados por día:

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 este es un ejemplo de los tipos de gráficos que puedes crear con estos datos:

Analíticas

En Trophy, la página del sistema de XP incluye gráficos de analíticas que muestran datos sobre el total de XP obtenidos y un desglose de qué desencadenantes otorgan más XP.

Obtener soporte

¿Quieres ponerte en contacto con el equipo de Trophy? Escríbenos 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

Instalar el SDK de Trophy

Seguimiento de las interacciones de los usuarios

Mostrar XP

Notificaciones emergentes

Mostrar la XP del usuario

Gráfico de XP del usuario

Analíticas

Obtener soporte

​Requisitos previos

​Configuración de Trophy

​Instalar el SDK de Trophy

​Seguimiento de las interacciones de los usuarios

​Mostrar XP

​Notificaciones emergentes

​Mostrar la XP del usuario

​Gráfico de XP del usuario

​Analíticas

​Obtener soporte

Requisitos previos

Configuración de Trophy

Instalar el SDK de Trophy

Seguimiento de las interacciones de los usuarios

Mostrar XP

Notificaciones emergentes

Mostrar la XP del usuario

Gráfico de XP del usuario

Analíticas

Obtener soporte