Saltar al contenido

Funciones

Eventos personalizados y objetivos

Registra el comportamiento de los usuarios y sus objetivos de conversión para crear segmentos RFM y completar la cronología de los contactos.

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:

Cronología de un contacto con eventos personalizados

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:

TipoCaso de usogoal_value
purchasePedidos de comercio electrónico, pagos únicosObligatorio
subscriptionSuscripciones SaaS, membresíasObligatorio
leadFormularios de contacto, solicitudes de demoOpcional
signupRegistros de cuentasOpcional
bookingCitas, consultasOpcional
trialActivaciones de pruebas gratuitasOpcional
otherEventos de conversión personalizadosOpcional

Crear segmentos RFM

El análisis RFM (Recencia, Frecuencia, Monetario) encuentra a tus mejores clientes. Usa el editor de segmentos con condiciones de Objetivo:

Editor de segmentos con un objetivo de eventos personalizados

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ónDescripción
TotalSuma de todos los valores del objetivo (gasto acumulado)
NúmeroCantidad de eventos (número de pedidos)
PromedioValor medio del objetivo (valor medio del pedido)
MínimoValor del objetivo más bajo
MáximoValor del objetivo más alto

Opciones de periodo

OpciónDescripción
En cualquier momentoTodo el historial
En los últimos X díasVentana móvil
En rango de fechasUn periodo concreto
Antes de la fechaCorte histórico
Después de la fechaDesde 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.completed
  • subscription/started
  • form_submit
  • user-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.upsert crea el contacto cuando no existe ninguno con ese correo. customEvents.import no crea ningún contacto
  • Los eventos solo se actualizan si occurred_at es más reciente que el existente
  • Para un borrado lógico, define deleted_at (ponlo a null para restaurar)
  • Solo un evento nuevo (un external_id nuevo) 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