Cómo funcionan los Challenges

• Asignación: el customer recibe el challenge (o se inscribe desde la app). El challenge define uno o más hitos sobre la misma métrica de progreso.
• Seguimiento del progreso: la plataforma actualiza el progreso con la frecuencia del atributo de customer subyacente. El endpoint customers/{value}/challenges devuelve el estado calculado para pintar la barra de progreso.
• Premio: al alcanzar un hito, se entregan los premios configurados en ese nivel del challenge. Puede ser un descuento, puntos, un reward/regalo o acceso a otra mecánica de juego.

How It Works

1. Asignación — el challenge se pone a disposición de los customers elegibles (automáticamente o por enrollment).
2. Tracking — cada compra o evento personalizado actualiza el atributo que monitoriza el challenge.
3. API de progreso — tu app llama a GET /customers/{customer_id}/challenges para renderizar barras de progreso con los valores calculados.
4. Detección de victoria — la plataforma compara el valor del atributo con el umbral de cada nivel. En un challenge progresivo el progreso es acumulativo: alcanzar el nivel 3 implica haber cruzado los niveles 1 y 2. Si un recálculo salta varios umbrales, se ganan todos los niveles cruzados en esa ejecución.
5. Entrega del premio — por cada nivel recién ganado se entregan los premios seleccionados en el challenge para ese nivel: descuento, puntos, reward/regalo (solo catálogo + targeted; se añade al catálogo personalizado del customer para canjear después — nunca auto-redimido al ganar) o acceso a otra mecánica de juego.

nota

Los Challenges siguen una métrica de progreso. Usa Hito único para un umbral y sus premios, o Progresivo para 2–5 umbrales crecientes sobre la misma métrica con premios por nivel. Los challenges multi-acción (acciones distintas en un challenge) aún no están disponibles.

Enrollment Mechanics

Cuando un challenge requiere enrollment, aplican estas reglas:

• Solo pueden ganar los customers que se hayan inscrito explícitamente — alcanzar el objetivo sin enrollarse no otorga el premio.
• Los customers pueden enrollarse antes de la fecha de inicio del challenge, pero nunca después de la fecha de fin.
• Los customers de países no definidos en el challenge no pueden participar, aunque conozcan el challenge.

El progreso no lo corta la fecha de enrollment. El challenge lee el Atributo calculado seleccionado tal cual. Si los carritos o eventos anteriores al enrollment (o anteriores a la fecha de inicio del challenge) cuentan hacia el progreso depende únicamente de cómo esté definida esa métrica de progresión — su periodo, filtros y lógica de cálculo. Por defecto, el enrollment no inicia ni corta la métrica; si necesitas excluir actividad previa al enrollment (o al inicio), configúralo en el Atributo calculado.

tip

Un customer que se enrolla pronto puede mostrar progreso ya al empezar el challenge, si la ventana del atributo incluye actividad anterior. Eso es esperable cuando la métrica está así definida — no es un bug de la plataforma.

Targeted Delivery and Recurrence Dates

Los Challenges se pueden promocionar o asignar con Targeted Delivery, incluidos envíos recurrentes. En ese setup interactúan cuatro capas de fechas:

Layer	Controls
Fechas de visualización	Si el Challenge puede aparecer en el catálogo de la app del customer.
Fechas de disponibilidad	Si el Challenge está activo y se puede ganar.
Política de expiración	Cuándo un Challenge ganado se reinicia y se puede intentar de nuevo.
Recurrencia de Targeted Delivery	Cuándo la Audience recibe la comunicación o asignación del Challenge.

El Challenge debe permanecer activo durante todo el periodo cubierto por la recurrencia. Un envío semanal recurrente no hace semanal el Challenge por sí solo: la disponibilidad del Challenge, el periodo del atributo calculado y la política de expiración deben soportar el comportamiento semanal deseado.

Por ejemplo, si un Challenge se envía cada lunes durante cuatro semanas, configúralo visible y disponible a lo largo de esas cuatro semanas. Si los Customers deben poder ganar una vez por semana, alinea el periodo del atributo calculado y la política de expiración con ese reset semanal. Si la disponibilidad termina tras la primera semana, los envíos posteriores pueden ejecutarse pero el Challenge no estará disponible para ganar.

Example: Challenge de 6 meses con Targeted Delivery mensual

Quieres que los customers participen de enero a junio, y una Targeted Delivery que asigne o recuerde una vez al mes durante esos seis meses.

What you configure	Example
Disponibilidad del Challenge	1 ene – 30 jun (seis meses completos)
Display del Challenge	Mismas fechas, o un poco antes si el Challenge debe verse antes del primer envío
Recurrencia de Targeted Delivery	Mensual, seis envíos (p. ej. el día 1 de cada mes, ene–jun)
Periodo del Atributo calculado	Objetivo una vez al mes: current_month (o equivalente). Un objetivo continuo de 6 meses: un periodo que cubra toda la ventana de participación.
Política de expiración	Victoria una vez al mes: al final de la ventana de cálculo (el Challenge se reinicia cada mes). Una sola victoria en seis meses: meses/días después de ganar, o simplemente que la disponibilidad cierre el Challenge.

La Targeted Delivery mensual solo controla cuándo se notifica o asigna a la Audience. No amplía la disponibilidad del Challenge ni reinicia el progreso. Si la disponibilidad terminara en enero, los envíos mensuales posteriores seguirían disparándose, pero los customers no podrían ganar fuera de esa ventana.

Configuration

La configuración del challenge ocurre en un solo flujo del Owner App — incluidos los premios:

Step	Owner App path
Crear el challenge (formato, Select a Customer, niveles y premios)	Gamified Campaigns → Challenges → New Challenge

Select a Customer: elige Loyalty Club (disponible para miembros del club) o Targeted (solo los customers asignados vía Targeted Delivery pueden ver y participar). Ver Create a Challenge.

Consulta Create a Challenge para la guía paso a paso y Premios para tipos de premio y reglas de selección.

tip

En el perfil del customer, Active Challenges es una tabla expandible: una fila por challenge, con filas anidadas por cada nivel (umbral, alcanzado, fecha de victoria).

API Reference

La Streaming API expone cuatro endpoints para integrar challenges:

Method	Endpoint	Description
GET	/customers/{customer_id}/challenges	Catálogo completo de challenges del customer, con progreso y estado de enrollment. Los enrolled aparecen primero. Solo challenges activos dentro de fechas y país del customer.
GET	/challenges	Todos los challenges disponibles, filtrados por país.
GET	/challenges/{id}	Un challenge concreto por ID.
POST	/challenges/{id}/enroll	Inscribe a un customer. Valida: enrollment permitido, challenge dentro de fechas, país elegible, tope de enrollments no alcanzado, customer no ya enrolled.

Building a Progress Bar

Las barras de progreso son muy recomendables: dan visibilidad del avance y motivan a completar. Usa el endpoint /customers/{customer_id}/challenges para obtener los datos.

Key Response Fields

Para cada challenge del catálogo, el endpoint devuelve:

Field	Description
attribute_value	Último valor calculado del atributo. Es el progreso actual hacia el siguiente (o único) umbral. Se actualiza con la frecuencia del atributo — no en tiempo real.
attribute_name	Nombre del Atributo calculado usado como métrica de progreso.
current_level	Posición de nivel actual del customer en la escalera del challenge.
to_reach_next_level_value	Valor que falta para el siguiente nivel (siguiente umbral menos valor actual).
structure	Array de niveles. Cada nivel incluye level, name, threshold, reached, won_at opcional y los premios de ese nivel.
structure[].threshold	Objetivo de ese nivel.
structure[].reached	true si attribute_value >= el umbral de ese nivel; false en caso contrario.
structure[].won_at	Fecha/hora en que se ganó ese nivel. Solo presente si reached = true.
last_execution_time	Cuándo se recalculó por última vez el attribute_value.

Ejemplo: Si el siguiente umbral es 100 y attribute_value = 70, entonces to_reach_next_level_value = 30. Pinta la barra al 70 % hacia el siguiente nivel. En un challenge progresivo, muestra también los niveles completados desde structure[].

Award in the Response

Cada respuesta de challenge incluye un array awards para mostrar premios con compatibilidad hacia atrás. El detalle más rico (cupones de descuento y tipos mixtos por nivel) está en prizes por nivel en structure[] y/o a nivel challenge, según el contrato de integración.

Field	Description
awards[].type	Tipo de premio, p. ej. "score" para puntos o "reward" para reward/regalo.
awards[].amount	Puntos que gana el customer. Solo si type = "score".
awards[].reward_id	ID del reward a otorgar. Solo si type = "reward".
awards[].reward_name	Nombre del reward (localizado según Accept-Language si hay multilenguaje). Solo si type = "reward".
awards[].loyalty_score_id	ID de la regla de loyalty asociada al premio.
Level prizes[]	Objetos de premio por nivel (puntos, cupón de descuento, reward, juego) para la app — úsalos cuando necesites más detalle que awards.

tip

Se recomienda implementar barras de progreso en la app del customer. Quienes ven su avance hacia un objetivo convierten más y completan más challenges.