Rachas

Aprende a usar rachas en una experiencia de producto gamificada con Trophy.

​

¿Qué son las Rachas?

Una racha es un período de días, semanas o meses consecutivos en el que un usuario ha realizado una acción clave en tu plataforma. Se ha demostrado que las rachas aumentan significativamente la retención, especialmente cuando la acción del usuario que se rastrea se alinea con el valor central de tu producto.

​

Frecuencia de Racha

Las rachas en Trophy pueden ser diarias, semanales o mensuales. Esto significa que un usuario debe cumplir sus condiciones de racha al menos una vez cada día, semana o mes calendario para mantener su racha.

Si has configurado zonas horarias para tus usuarios, Trophy rastreará automáticamente la racha de cada usuario en su zona horaria local (incluyendo cuando los usuarios cambian de zona horaria) y mantendrá las rachas intactas.

Trophy calcula automáticamente los datos de racha para cada frecuencia de racha, lo que significa que puedes cambiar en cualquier momento.

​

Condiciones de Racha

En Trophy puedes establecer los umbrales que un usuario debe cumplir para extender su racha basándote en tus Métricas configuradas.

Puedes elegir qué métricas deben ser parte de tu racha y, para las que elijas, puedes establecer un umbral personalizado que los usuarios deben cumplir.

Al combinar métricas, puedes elegir entre dos modos de evaluación:

• ALL significa que un usuario debe cumplir cada umbral de métrica para extender su racha
• OR significa que un usuario solo tiene que cumplir uno de tus umbrales de métrica para extender su racha

De esta manera puedes diseñar tu lógica de racha para que coincida con el caso de uso de tu aplicación.

​

Días Libres

Para rachas diarias, puedes marcar días específicos de la semana como días libres en la página de rachas del panel de Trophy. Esos días no cuentan para la racha: los usuarios aún pueden extender su racha si están activos, pero perder un día libre no la romperá.

Debes dejar al menos un día que cuente para la racha. Las rachas semanales y mensuales ignoran los días libres.

A diferencia de las congelaciones de racha, los días libres no se consumen. Se aplican cada semana hasta que los cambies.

Si has habilitado la personalización de racha, los usuarios pueden anular los días libres predeterminados mediante las preferencias de usuario.

​

Congelaciones de Racha

Las congelaciones de racha ayudan a los usuarios a mantener sus rachas por más tiempo al permitirles perder un número determinado de períodos sin que se restablezca a cero. Esto ayuda a mantener las rachas motivadoras incluso si los usuarios no mantienen un hábito de uso perfecto.

Las congelaciones de racha son opcionales y se pueden configurar en la página de rachas del panel de Trophy.

Cuando están habilitadas, decides cuántas congelaciones puede tener un usuario y cuántas se le otorgan con el tiempo. Cuando un usuario pierde un período, se consume una congelación. Las congelaciones se consumen hasta que los usuarios no tienen congelaciones restantes, momento en el cual la racha del usuario se restablece a cero.

Las congelaciones de racha son diferentes de las pausas de racha en que las congelaciones permiten a los usuarios perder un número determinado de períodos sin romper su racha, independientemente del motivo, mientras que las pausas de racha protegen específicamente una racha durante un rango de fechas conocido y predefinido, como unas vacaciones o descanso programado. Las congelaciones se consumen automáticamente cuando el usuario pierde una actividad requerida, mientras que las pausas se crean manualmente con anticipación para cubrir ausencias planificadas.

​

Concesión de congelamientos

Puede configurar cualquier número de congelamientos arbitrarios para otorgar a los nuevos usuarios cuando los identifique por primera vez con Trophy. Para configurar esto, habilite las concesiones de congelamiento y establezca el recuento inicial de congelamientos en la página de rachas del panel de Trophy.

Trophy también puede otorgar automáticamente congelamientos de racha a los usuarios con el tiempo. Puede elegir un número arbitrario de días durante los cuales otorgar un número arbitrario de congelamientos a cada usuario.

Para configurar esto, establezca el número de días durante los cuales otorgar congelamientos y el número de congelamientos a otorgar en la página de rachas del panel de Trophy. Aquí también puede establecer el número máximo de congelamientos que cada usuario puede tener, hasta un límite de 100.

Si ha configurado zonas horarias para sus usuarios, Trophy consumirá automáticamente los congelamientos a medianoche en la zona horaria del usuario cuando sea necesario para extender su racha, y si se deben otorgar nuevos congelamientos a un usuario, se otorgarán hasta diez minutos después.

​

Pausas de racha

Las pausas de racha protegen la racha de un usuario durante un rango de fechas conocido, como unas vacaciones u otro descanso planificado. Mientras una pausa cubre un período, Trophy mantiene la duración de la racha del usuario en lugar de finalizar la racha si no cumple con sus condiciones de racha.

Las pausas de racha son diferentes de los congelamientos de racha en que las pausas protegen específicamente la racha de un usuario durante un rango de fechas conocido y predefinido, como unas vacaciones programadas o un descanso, mientras que los congelamientos permiten a los usuarios perder un número establecido de días (o períodos) sin romper su racha, independientemente del motivo. Las pausas se crean manualmente con anticipación para cubrir ausencias planificadas, mientras que los congelamientos se consumen automáticamente cuando el usuario pierde una actividad requerida.

​

Crear pausas

Crea pausas con la API de administración para crear pausas de rachas. Puedes crear pausas para hasta 100 usuarios en una única solicitud.

Cada pausa requiere:

• userId: el usuario para el que crear una pausa
• start: la primera fecha que cubre la pausa
• end: la última fecha que cubre la pausa

Las fechas de inicio en el pasado son rechazadas. Si has configurado zonas horarias para tus usuarios, Trophy evalúa start contra el día de hoy en la zona horaria local de cada usuario.

​

Eliminar pausas

Para evitar que una pausa se aplique, elimínala con la API de administración para eliminar pausas de rachas.

​

Leer pausas

La API de rachas de usuario devuelve las pausas próximas y actualmente activas en el campo pauses. Las pausas pasadas y eliminadas se omiten.

Cada período en streakHistory incluye usedPause, que es true cuando la racha del usuario estuvo en pausa durante ese período.

​

Seguimiento de rachas

Trophy calcula automáticamente las rachas para todos los usuarios según los eventos de métricas que reportes a Trophy.

No se requiere trabajo adicional para hacer seguimiento de las rachas, y puedes comenzar a usarlas de inmediato. Solo asegúrate de que las rachas estén habilitadas en el panel de Trophy.

También puedes leer y actualizar la configuración de rachas de la organización — frecuencia, modo de evaluación, métricas, días libres, personalización y congelamientos — con la API de administración de configuración de rachas.

Para un recorrido completo sobre cómo configurar una funcionalidad de rachas usando Trophy, consulta nuestra guía oficial.

​

Personalización de rachas

Trophy puede permitir que los usuarios personalicen cómo funciona su racha dentro de los límites que establezcas para ellos. Para hacer esto, activa la personalización de rachas en la página de rachas del panel de Trophy.

Una vez habilitado, los usuarios podrán personalizar las condiciones de racha que deben cumplir para extender su racha, incluyendo el modo de evaluación de racha, el umbral para cada métrica y días libres, a través de las preferencias de usuario.

Para obtener más información sobre cómo establecer las preferencias de usuario para un usuario específico, consulta la documentación dedicada sobre preferencias de usuario.

​

Gestión de Rachas

Esta sección describe algunas de las operaciones que puedes realizar para gestionar las rachas de los usuarios en tu aplicación.

​

Restaurar la Racha de un Usuario

Para restaurar la racha de un usuario, dirígete a la página de detalles del usuario y utiliza la acción ‘Restaurar Racha’. Restaurar la racha de un usuario la establece a la longitud que tenía cuando la perdió por última vez.

También puedes usar la API de administración para restaurar rachas para restaurar rachas de forma programática.

​

Mostrar Rachas

Trophy expone los datos de rachas de dos formas, que pueden utilizarse para construir elementos de interfaz dentro de tus aplicaciones y mostrar las rachas a los usuarios.

Consulta nuestra guía completa sobre cómo agregar una funcionalidad de rachas a tu aplicación para obtener más detalles.

​

Respuesta de Evento de Métrica

Cuando incrementas una métrica para un usuario, la respuesta de la API de métricas incluirá la racha actual del usuario.

Response

{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  "achievements": [
    {
      "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "trigger": "metric",
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "metricName": "Flashcards Flipped",
      "metricValue": 500,
      "name": "500 Flashcards Flipped",
      "description": "Flip 500 flashcards in the app.",
      "badgeUrl": null,
      "userAttributes": [],
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12",
    "extended": true
  },
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 10,
      "level": {
        "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
        "key": "bronze",
        "name": "Bronze",
        "description": "Starting level",
        "badgeUrl": null,
        "points": 0
      },
      "added": 10,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 10,
          "date": "2021-01-01T00:00:00Z",
          "total": 10,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "Flashcards Flipped",
            "metricThreshold": 100,
            "points": 10,
            "status": "active",
            "userAttributes": [],
            "created": "2021-01-01T00:00:00Z",
            "updated": "2021-01-01T00:00:00Z"
          }
        }
      ]
    }
  },
  "leaderboards": {
    "daily_champions": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
      "key": "daily_champions",
      "name": "Daily Champions",
      "description": null,
      "status": "active",
      "rankBy": "metric",
      "runUnit": "day",
      "runInterval": 1,
      "maxParticipants": 100,
      "breakdownAttributes": [],
      "metricName": "Flashcards Flipped",
      "metricKey": "flashcards-flipped",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "startTime": null,
      "endTime": null,
      "previousRank": 50,
      "rank": 12
    }
  },
  "idempotencyKey": "flashcard-view-42",
  "idempotentReplayed": false
}

Esto puede utilizarse para activar de forma transaccional elementos de UI/UX incluyendo:

• Mostrar ventanas emergentes en la aplicación
• Reproducir efectos de sonido

​

API de Rachas de Usuario

La API de rachas de usuario devuelve la racha actual de un solo usuario, junto con su historial reciente de rachas y cualquier pausa de racha próxima o activa. Usa el parámetro de consulta historyPeriods para controlar cuántos períodos devolver.

Response

{
  "length": 1,
  "frequency": "weekly",
  "started": "2025-04-02",
  "periodStart": "2025-03-31",
  "periodEnd": "2025-04-05",
  "expires": "2025-04-12",
  "rank": 5,
  "pauses": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "start": "2026-08-20",
      "end": "2026-08-27"
    }
  ],
  "streakHistory": [
    {
      "periodStart": "2025-03-02",
      "periodEnd": "2025-03-08",
      "length": 9,
      "usedPause": false
    },
    {
      "periodStart": "2025-03-09",
      "periodEnd": "2025-03-15",
      "length": 0,
      "usedPause": false
    },
    {
      "periodStart": "2025-03-16",
      "periodEnd": "2025-03-22",
      "length": 0,
      "usedPause": false
    },
    {
      "periodStart": "2025-03-23",
      "periodEnd": "2025-03-29",
      "length": 1,
      "usedPause": false
    },
    {
      "periodStart": "2025-03-30",
      "periodEnd": "2025-04-05",
      "length": 2,
      "usedPause": false
    },
    {
      "periodStart": "2025-04-06",
      "periodEnd": "2025-04-12",
      "length": 3,
      "usedPause": false
    },
    {
      "periodStart": "2025-04-13",
      "periodEnd": "2025-04-19",
      "length": 4,
      "usedPause": false
    }
  ]
}

Utiliza estos datos para mostrar el historial de rachas de un usuario dentro de tu aplicación.

​

Listar las Rachas de Múltiples Usuarios

Si deseas mostrar rachas para múltiples usuarios a la vez, por ejemplo para admitir una racha de amigos o una función de grupo de usuarios, entonces utiliza la API de listar rachas de usuario.

[
  {
    "userId": "user-123",
    "streakLength": 15,
    "extended": "2025-01-01T05:03:00Z"
  },
  {
    "userId": "user-456",
    "streakLength": 12,
    "extended": "2025-01-01T08:43:00Z"
  },
  {
    "userId": "user-789",
    "streakLength": 0,
    "extended": null
  }
]

​

Obtener Soporte

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