Activity Generation Configs
Configuración solo de ciclo de vida que define cómo se generan las actividades de retención.
Descripción general
Una Activity Generation Config (AGC) describe cómo la plataforma deriva el estado del ciclo de vida de retención de un usuario. Es una configuración solo de ciclo de vida: metadatos base, una audiencia opcional y exactamente tres pilares de ciclo de vida obligatorios.
Toda AGC pertenece a un proyecto: los endpoints trabajan sobre las AGC del proyecto activo, y una AGC de otro proyecto responde 404 como si no existiera. Su nombre es único dentro del proyecto.
| Pilar | Propósito |
|---|---|
activation | Clasifica si (y con qué intensidad) un usuario se ha activado, en base a sus primeros momentos de acción. |
engagement | Agrupa a los usuarios activos en niveles de engagement (p. ej. casual, core, power). |
resurrection | Detecta usuarios que regresan tras un período de inactividad y clasifica recuperación vs. abandono. |
Los tres pilares son 1:1 con la AGC: toda AGC siempre tiene exactamente una configuración de activation, engagement y resurrection. No puedes crear una AGC con un pilar faltante, ni crear un pilar que no esté asociado a una AGC.
No existe configuración de dispatch independiente: una AGC solo define la clasificación del ciclo de vida.
Estado
Toda AGC tiene un status:
| Estado | Significado |
|---|---|
draft | Estado inicial de toda AGC nueva. |
active | La configuración está pensada para correr. |
paused | Sacada de ejecución. Conserva su id y su definición, y se puede volver a publicar. |
El estado sólo cambia con dos acciones, ambas con el permiso activity-generation-config:update:
status no se acepta en ningún cuerpo de creación ni de actualización. Sólo las configuraciones active están pensadas para correr: lístalas con GET /api/activity-generation-configs?status=active.
Audiencia efectiva
audienceId es la audiencia propia de la AGC, y es opcional. Las lecturas — GET /:id y la lista — devuelven además effectiveAudienceId, la audiencia sobre la que corre la AGC:
audienceId, cuando la AGC tiene audiencia propia;- si no, la audiencia raíz del proyecto (ver Proyectos → Audiencia raíz).
effectiveAudienceId nunca es null. Se calcula al leer la AGC: no se almacena y no se envía en ningún cuerpo.
Config hashes
GET /:id devuelve un objeto configHashes — un hash determinístico por pilar (16 caracteres hexadecimales) para cada uno de los tres pilares:
{
"activation": "9f1c2a3b4d5e6f70",
"engagement": "a1b2c3d4e5f60718",
"resurrection": "0f1e2d3c4b5a6978"
}Los clientes usan estos hashes para detectar de forma económica cuándo cambió la configuración de un pilar, sin tener que comparar el payload anidado completo. El hash se calcula solo sobre el contenido semántico del pilar: los campos volátiles (id, timestamps) se eliminan y las colecciones hijas se hashean de forma independiente del orden, por lo que reordenar hijos sin cambiar sus valores no altera el hash.
Autenticación
Todos los endpoints requieren un token JWT Bearer, la cabecera x-tenant-id que identifica el tenant sobre cuyo esquema opera la solicitud, y la cabecera x-project-id que identifica el proyecto en el que trabaja la solicitud (ver Autenticación → Contexto de Proyecto).
-H "Authorization: Bearer <token>"
-H "x-tenant-id: <tenant-id>"
-H "x-project-id: <project-id>"Permisos
| Permiso | Otorga |
|---|---|
activity-generation-config:view | Listar y leer AGCs |
activity-generation-config:create | Crear una AGC |
activity-generation-config:update | Actualizar metadatos, reemplazar pilares de ciclo de vida, publicar y pausar |
activity-generation-config:delete | Archivar (soft delete) una AGC |
Convención de serialización: los cuerpos de solicitud de crear, actualizar y actualizar el ciclo de vida son snake_case (por ejemplo source_table, user_retention_status_config_id), mientras que las respuestas GET son camelCase (por ejemplo sourceTable, userRetentionStatusConfigId).
Endpoints
List Configs
Listar metadatos de AGC (sin config anidada, sin config hashes).
Get Config
Leer una AGC con sus tres pilares anidados y los config hashes.
Create Config
Crear una AGC con los tres pilares de ciclo de vida (transaccional).
Update Lifecycle
Reemplazo in-place de uno o más pilares de ciclo de vida.
Update Config
Actualizar solo los metadatos de la AGC (nombre, descripción, audiencia).
Publish Config
Pasar una AGC de draft o paused a active.
Pause Config
Pasar una AGC active a paused, conservando su id.
Delete Config
Archivar una AGC; sus tres pilares se archivan en cascada.