Descripción general
Los eventos personalizados registran acciones de los usuarios que vienen de sistemas externos (comercio electrónico, CRM, analítica). Aparecen en la cronología del contacto, y sus objetivos te permiten crear segmentos RFM (Recencia, Frecuencia, Monetario).
Cronología del contacto
Cada evento personalizado crea una entrada en la cronología del contacto, así que ves el historial completo de sus interacciones:
Cada evento muestra su event_name como tipo de la entrada en la cronología (por ejemplo, “order.completed”, “subscription.started”). El campo properties guarda contexto adicional, visible en los detalles de la entrada.
Tipos de objetivo
Los segmentos se basan en los objetivos. Cada evento puede registrar un objetivo:
| Tipo | Caso de uso | goal_value |
|---|---|---|
purchase | Pedidos de comercio electrónico, pagos únicos | Obligatorio |
subscription | Suscripciones SaaS, membresías | Obligatorio |
lead | Formularios de contacto, solicitudes de demo | Opcional |
signup | Registros de cuentas | Opcional |
booking | Citas, consultas | Opcional |
trial | Activaciones de pruebas gratuitas | Opcional |
other | Eventos de conversión personalizados | Opcional |
Crear segmentos RFM
El análisis RFM (Recencia, Frecuencia, Monetario) encuentra a tus mejores clientes. Usa el editor de segmentos con condiciones de Objetivo:
Monetario: gasto total
Selecciona el tipo de objetivo Compra y el agregado total, y luego indica un valor mínimo para encontrar a los clientes que más gastan.
Frecuencia: número de compras
Selecciona el tipo de objetivo Compra y el agregado número, y luego indica una cantidad mínima para encontrar a los compradores recurrentes.
Recencia: actividad reciente
Usa el filtro de periodo “en los últimos X días” para encontrar a los clientes con compras recientes.
Ejemplos de segmentos RFM
- Clientes VIP: gasto de 1000 $ o más Y 5 pedidos o más Y compra en los últimos 60 días
- Alto valor en riesgo: gasto de 500 $ o más Y ninguna compra en 90 días
- Nuevos con alto potencial: primera compra de más de 200 $ en los últimos 30 días
Opciones de agregado
| Opción | Descripción |
|---|---|
| Total | Suma de todos los valores del objetivo (gasto acumulado) |
| Número | Cantidad de eventos (número de pedidos) |
| Promedio | Valor medio del objetivo (valor medio del pedido) |
| Mínimo | Valor del objetivo más bajo |
| Máximo | Valor del objetivo más alto |
Opciones de periodo
| Opción | Descripción |
|---|---|
| En cualquier momento | Todo el historial |
| En los últimos X días | Ventana móvil |
| En rango de fechas | Un periodo concreto |
| Antes de la fecha | Corte histórico |
| Después de la fecha | Desde una fecha concreta |
Registrar eventos
Evento único
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"email": "customer@example.com",
"event_name": "order.completed",
"external_id": "order_12345",
"properties": {
"items": ["Product A", "Product B"],
"currency": "USD"
},
"goal_type": "purchase",
"goal_value": 149.99
}'
Importación por lotes
Importa hasta 50 eventos a la vez:
curl -X POST "https://your-instance.com/api/customEvents.import" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"events": [
{
"email": "user1@example.com",
"event_name": "order.completed",
"external_id": "order_001",
"goal_type": "purchase",
"goal_value": 99.99
},
{
"email": "user2@example.com",
"event_name": "order.completed",
"external_id": "order_002",
"goal_type": "purchase",
"goal_value": 249.99
}
]
}'
Formato del nombre del evento
Los nombres de eventos deben ir en minúsculas y usar letras, números, puntos, guiones bajos, guiones o barras:
order.completedsubscription/startedform_submituser-signup
Nota
Los objetivos registrados por Analíticas web llegan a la cronología del contacto con una regla más estricta: solo letras ASCII, números, puntos y barras, y todo lo demás (guiones y caracteres acentuados incluidos) se sustituye por un guion bajo. Un objetivo web llamado user-signup llega como user_signup. Si envías el mismo evento por las dos vías, elige un nombre que sobreviva a ambas.
Gestionar reembolsos
Usa un goal_value negativo para los reembolsos, así los cálculos de LTV siguen siendo correctos:
{
"email": "customer@example.com",
"event_name": "order.refunded",
"external_id": "refund_12345",
"goal_type": "purchase",
"goal_value": -50.00
}
Permisos
Los eventos personalizados no tienen permiso propio: dependen de Contactos. Registrar o importar un evento requiere el nivel Escribir de Contactos, y leerlo requiere el nivel Leído. Por eso, conceder lectura en Contactos también abre los eventos registrados en tus contactos y la cronología que alimentan. Consulta Administradores y claves API.
Notas
customEvents.upsertcrea el contacto cuando no existe ninguno con ese correo.customEvents.importno crea ningún contacto- Los eventos solo se actualizan si
occurred_ates más reciente que el existente - Para un borrado lógico, define
deleted_at(ponlo anullpara restaurar) - Solo un evento nuevo (un
external_idnuevo) inicia las automatizaciones que se disparan con su nombre; desde la 44.0, una actualización, un borrado lógico o una restauración no lo hacen - Consulta la referencia de la API para la documentación completa del endpoint
