Cómo crear una función de energía

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 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 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 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 ‘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 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 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 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. 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://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 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.

Response

{
  "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 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 para obtener su energía total actual.

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

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:

Response

{
  "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

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.

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 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.

Response

{
  "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 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.

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

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 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. ¡Estamos aquí para ayudarte!

Guías de funcionalidades

Casos de uso

Cómo crear una función de energía

Requisitos previos

Configuración de Trophy

Instalación del SDK de Trophy

Rastreo de Interacciones de Usuario

Medición del Uso

Visualización de Energía

Analíticas

Obtener soporte