Skip to main content
En este tutorial, crearemos TrophyFitness, una aplicación de fitness para consumidores que rastrea carrera, ciclismo y natación. Implementaremos un bucle de gamificación completo que incluye clasificaciones semanales, rachas formadoras de hábitos y un sistema de progresión por niveles. Si quieres ir directamente al código, consulta el repositorio de ejemplo o la demostración en vivo.

Tabla de Contenidos

Stack Tecnológico

Requisitos Previos

  • Una cuenta de Trophy (regístrate aquí).
  • Node.js 18+ instalado.

Configuración e Instalación

Primero, clona el repositorio inicial o crea una nueva aplicación Next.js:
Instala las dependencias necesarias:
Configura tus variables de entorno en .env.local:

Diseñar el Modelo de Datos

Para una aplicación de fitness multideporte, necesitamos normalizar los esfuerzos. Un ciclo de 10 km no es lo mismo que una carrera de 10 km. Utilizaremos tres métricas distintas para rastrear datos sin procesar y un sistema de XP unificado para la progresión.

  1. Las Métricas

Rastrearemos la distancia como el valor principal.
  • distance_run (km) - con atributo pace (caminar/correr).
  • distance_cycled (km)
  • distance_swum (m) - con atributo style (estilo libre/braza).

  1. Los Atributos

Para habilitar clasificaciones locales, etiquetaremos a cada usuario con un atributo city.

Cómo Funciona Trophy

Antes de profundizar en el código, entendamos cómo Trophy impulsa nuestra capa de gamificación. En Trophy, las Métricas representan diferentes interacciones que los usuarios pueden realizar e impulsan funciones como Logros, Rachas y Correos Electrónicos. Cuando se registran eventos para un usuario específico, cualquier logro vinculado a la métrica especificada se desbloqueará si se cumplen los requisitos, las rachas se calcularán automáticamente, las clasificaciones se actualizarán y cualquier correo electrónico configurado se programará. Esto es lo que hace que construir experiencias gamificadas con Trophy sea tan poderoso: hace todo el trabajo detrás de escena.

Configuración de Trophy

Así es como configuraremos Trophy para nuestra aplicación de fitness:
Dirígete a la página de métricas de Trophy y crea tres métricas:
  • distance_run — Total de kilómetros corridos
  • distance_cycled — Total de kilómetros en bicicleta
  • distance_swum — Total de metros nadados
Estas claves son las que referenciaremos en nuestro código al enviar eventos.
Mientras aún estás en la página de métricas, configura los atributos de evento pace y style:
Luego, ve a la página de atributos de usuario y crea el atributo de usuario city:
Ve a la página de logros de Trophy y crea logros de hitos para cada deporte. Por ejemplo:Running:
  • First 5K (5km en total)
  • Half Marathon Hero (21.1km en total)
  • Marathon Master (42.2km en total)
Cycling:
  • Century Rider (100km en total)
  • Tour Stage (200km en total)
Swimming:
  • Pool Regular (1000m en total)
  • Open Water Ready (5000m en total)
Vincula cada logro a la métrica correspondiente.
Ve a la página de clasificaciones y configura clasificaciones semanales para impulsar la competencia. Cada clasificación debe configurarse con Unidad de repetición: Días e Intervalo de repetición: 7 para repetirse semanalmente.
Clasificaciones globales:
  • weekly-distance-run
  • weekly-distance-cycled
  • weekly-distance-swum
Clasificaciones por ciudad (desglose por atributo de usuario city):
  • weekly-distance-run-cities
  • weekly-distance-cycled-cities
  • weekly-distance-swum-cities
Ve a la página de puntos y crea un sistema de puntos llamado xp que otorgue puntos según la actividad:
  • Running: 10 XP por km
  • Cycling: 3 XP por km
  • Swimming: 10 XP por cada 100m
Este enfoque normalizado garantiza una progresión justa entre deportes.
Luego configura Niveles de puntos en el mismo sistema xp para que Trophy pueda rastrear el nivel de cada usuario. Usa las claves y umbrales a continuación para que el código de esta guía coincida con tu panel:
Dirígete a la página de rachas y configura una racha diaria vinculada a cualquiera de las métricas de distancia. Los usuarios mantendrán su racha registrando al menos una actividad por día.
Dirígete a la página de correos electrónicos y añade y activa plantillas para estos correos electrónicos automatizados de participación:
  • Logro desbloqueado — Celebra nuevas insignias
  • Racha en riesgo — Recuerda a los usuarios antes de que pierdan su racha
  • Resumen semanal — Resumen del progreso y posición en la clasificación
Cada tipo de correo tiene su propia sección—añade una plantilla en cada una y actívala para comenzar a enviar. Configura tu marca en la página de marca para correos electrónicos profesionales.

Acciones del Servidor

Crearemos un archivo src/app/actions.ts para manejar todas las interacciones con la API de Trophy. Esto mantiene nuestras claves API seguras y nos permite aprovechar las Server Actions de Next.js.
src/app/actions.ts

El Sistema de Niveles

Trophy almacena el nivel de cada usuario en el sistema de puntos xp cuando configuras Niveles de Puntos. La carga útil de puntos de usuario incluye un objeto level. La API de lista de niveles devuelve cada nivel y umbral para que puedas mostrar el progreso hacia el siguiente. Añade un pequeño ayudante junto a las constantes de tu aplicación en src/lib/constants.ts:
src/lib/constants.ts

Construyendo el Panel

El panel agrega todas las estadísticas del usuario. Obtenemos los datos del lado del servidor y derivamos barras de progreso de los umbrales devueltos por la API.
src/app/page.tsx
Nota el contenedor LogActivityDialog alrededor del botón—lo construiremos a continuación.

Registrando Entrenamientos

El botón Registrar Entrenamiento abre un cuadro de diálogo donde los usuarios seleccionan su tipo de actividad, ingresan la distancia y envían. Esto activa la acción del servidor logActivity que envía el evento a Trophy. Primero, instala los componentes requeridos de shadcn/ui:
Luego crea el componente de diálogo:
components/log-activity-dialog.tsx

Contexto del Usuario

El diálogo necesita acceso al ID del usuario actual. Crea un proveedor de contexto:
components/user-provider.tsx
Envuelve tu aplicación con el proveedor en layout.tsx:
app/layout.tsx

Utilidades Auxiliares

El contexto del usuario depende de funciones auxiliares para gestionar la identidad del usuario en localStorage:
lib/user.ts
Para las clasificaciones basadas en ciudad, inferimos la ciudad del usuario a partir de su zona horaria:
lib/city.ts

Implementando Clasificaciones

Construiremos una interfaz con pestañas que permite a los usuarios cambiar entre actividades (Correr/Ciclismo/Natación) y alcances (Global vs. Ciudad Local).
src/app/leaderboards/page.tsx

Construyendo la Página de Logros

Un espacio dedicado para mostrar insignias es esencial para la retención a largo plazo. Usaremos los datos de stats.achievements para renderizar una cuadrícula de insignias, distinguiendo visualmente entre estados ganados (coloridos) y bloqueados (escala de grises).
src/app/achievements/page.tsx

Construyendo la Página de Perfil

Finalmente, la página de perfil lo integra todo. Muestra las “Estadísticas de por Vida” del usuario, su progresión actual de XP y les permite actualizar su configuración (como su ciudad).
src/app/profile/page.tsx

El Resultado

¡Ahora tienes un ciclo de gamificación de fitness completamente funcional! Los usuarios pueden registrar entrenamientos en múltiples deportes, progresar a través de niveles de Puntos, ganar insignias y competir en las Clasificaciones.

Lo Que Has Construido

  • Seguimiento multideporte con XP normalizado entre carrera, ciclismo y natación
  • Clasificaciones semanales con competencia global y por ciudad
  • Progresión por niveles desde Principiante hasta Profesional
  • Sistema de logros con insignias de hitos
  • Rachas diarias para impulsar la retención

Próximos Pasos

  • Conecta dispositivos de fitness — Integra con Strava, Apple Health o Google Fit para registrar entrenamientos automáticamente
  • Añade funciones sociales — Permite que los usuarios sigan amigos, comparen estadísticas y compartan logros
  • Crea una experiencia móvil — Convierte a PWA o empaqueta con Capacitor para distribución en tiendas de aplicaciones
  • Añade notificaciones push — Alerta a los usuarios cuando su racha esté en riesgo o hayan sido superados en la clasificación