Endpoint de Segmentación

El endpoint /api/visitors/segment permite gestionar la segmentación de visitantes en función de su comportamiento, características demográficas o acciones realizadas en el sitio. La API verifica automáticamente si existen segmentos configurados para la URL proporcionada y asigna los segmentos correspondientes al visitante y/o lead.

Especificación de la API

• URL: /api/visitors/segment
• Método: POST
• Formato de datos: JSON
• Autenticación: API Key en encabezado X-SA-API-KEY

Parámetros de Búsqueda

Para identificar un segmento específico, puedes usar cualquiera de estos parámetros:

• segment_id o s: ID del segmento
• name o n: Nombre del segmento

Parámetros del Request

* segment_id (o s) o name (o n) se vuelven requeridos si existen múltiples segmentos para la URL proporcionada.

Comportamiento Automático

La API realiza las siguientes acciones al recibir una solicitud:

1. Busca segmentos existentes que coincidan con la URL proporcionada
2. Si encuentra un único segmento:
   • Lo usa directamente para la asignación
3. Si encuentra múltiples segmentos:
   • Busca coincidencia usando segment_id (o s) o name (o n)
   • Si no se proporciona ninguno de estos parámetros, retorna un error 400 solicitando especificar el segmento
4. Si no encuentra ningún segmento:
   • Crea uno nuevo con los datos proporcionados
   • Si se proporciona segment_id o name, los usa para el nuevo segmento
   • Si no se proporciona ninguno, genera un ID automáticamente
5. Asigna el segmento al visitante
6. Si se proporciona un lead_id, también actualiza la segmentación del lead

Ejemplo de payload (un segmento conocido)

{
  "site_id": "site_123abc",
  "url": "https://ejemplo.com/productos/zapatos",
  "visitor_id": "vis_789xyz",
  "segment_id": "seg_123456"
}

Ejemplo de payload (nuevo segmento)

{
  "site_id": "site_123abc",
  "url": "https://ejemplo.com/productos/zapatos",
  "visitor_id": "vis_789xyz",
  "name": "Compradores de calzado",
  "rules": [
    {
      "field": "page.url",
      "operator": "contains",
      "value": "/productos",
      "type": "page"
    }
  ]
}

Respuesta Exitosa

{
  "success": true,
  "segment_id": "seg_123456",
  "name": "Compradores de calzado",
  "created_at": 1646123456789,
  "estimated_size": 245,
  "visitor_id": "vis_789xyz",
  "lead_id": "lead_456def",
  "auto_assigned_segments": [
    {
      "segment_id": "seg_abc123",
      "name": "Visitantes de categoría zapatos",
      "assigned_at": 1646123456789
    }
  ]
}

Respuesta de Error (Múltiples Segmentos)

{
  "success": false,
  "error": {
    "code": "multiple_segments_found",
    "message": "Se encontraron múltiples segmentos para la URL proporcionada. Por favor, especifique segment_id o name.",
    "segments": [
      {
        "segment_id": "seg_123456",
        "name": "Compradores de calzado"
      },
      {
        "segment_id": "seg_789012",
        "name": "Visitantes de zapatos"
      }
    ]
  }
}

Operadores disponibles

Valores temporales especiales

Para los campos de tipo fecha/hora, se pueden usar valores relativos:

• now - Momento actual
• now-Xm - X minutos atrás (ej: now-30m)
• now-Xh - X horas atrás (ej: now-12h)
• now-Xd - X días atrás (ej: now-7d)
• now-Xw - X semanas atrás (ej: now-2w)
• now-XM - X meses atrás (ej: now-3M)
• today - Inicio del día actual
• yesterday - Inicio del día anterior
• this_week - Inicio de la semana actual
• last_week - Inicio de la semana anterior
• this_month - Inicio del mes actual
• last_month - Inicio del mes anterior

Límites

• Máximo de segmentos por sitio: 50
• Máximo de reglas por segmento: 20
• Máximo de operaciones de cálculo de segmentos concurrentes: 5

Buenas prácticas

1. Crear segmentos significativos: Diseña segmentos que tengan valor para tu análisis de negocio.

2. Limitar complejidad: Las reglas muy complejas pueden afectar al rendimiento del cálculo.

3. Usar segmentos dinámicos: Para la mayoría de los casos, los segmentos dinámicos son más útiles ya que se actualizan automáticamente.

4. Documentar bien: Usa descripciones claras para que otros miembros del equipo entiendan el propósito del segmento.

Prueba la API