Skip to Content
Uncodie Market Fit está disponible 🎉
Rest APIVisitorsEndpoint de Track

Endpoint de Track

El endpoint /api/visitors/track es el punto central para registrar eventos de visitantes en tu sitio web. Este endpoint es utilizado por el script de tracking para enviar datos sobre las acciones de los usuarios, pageviews, clics, y eventos personalizados.

API de Tracking de Visitantes

Prueba el endpoint de tracking de visitantes

Especificación de la API

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

Parámetros del Request

ParámetroTipoRequeridoDescripción
site_idstringSíIdentificador único del sitio
event_typestringSíTipo de evento (pageview, click, custom, purchase, action, mousemove, scroll, keypress, resize, focus, form_submit, form_change, form_error, error, performance, session_recording)
event_namestringNoNombre del evento personalizado (requerido si event_type es custom)
urlstringSíURL donde ocurrió el evento
referrerstringNoURL de referencia
visitor_idstringNoID único del visitante (generado por el script si no se proporciona)
session_idstringNoID de la sesión actual
segment_idstringNoID del segmento al que pertenece el visitante
timestampnumberNoMarca de tiempo en milisegundos (se usa la del servidor si no se proporciona)
propertiesobjectNoPropiedades adicionales del evento
user_agentstringNoUser-Agent del navegador
ipstringNoDirección IP (se captura automáticamente por el servidor)

Ejemplo de payload para pageview

{
  "site_id": "site_123abc",
  "event_type": "pageview",
  "url": "https://ejemplo.com/productos",
  "referrer": "https://google.com",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "segment_id": "seg_premium_users",
  "timestamp": 1646123456789,
  "properties": {
    "page_title": "Catálogo de Productos",
    "screen_size": "1920x1080",
    "locale": "es-ES"
  }
}

Ejemplo de payload para evento personalizado

{
  "site_id": "site_123abc",
  "event_type": "custom",
  "event_name": "add_to_cart",
  "url": "https://ejemplo.com/productos/zapato-casual",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "segment_id": "seg_active_shoppers",
  "timestamp": 1646123456789,
  "properties": {
    "product_id": "prod_123",
    "product_name": "Zapato Casual Negro",
    "price": 49.99,
    "currency": "EUR",
    "quantity": 1
  }
}

Ejemplo de payload para evento de compra

{
  "site_id": "site_123abc",
  "event_type": "purchase",
  "url": "https://ejemplo.com/checkout/confirmation",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "segment_id": "seg_buyers",
  "timestamp": 1646123456789,
  "properties": {
    "order_id": "ord_12345",
    "total_amount": 99.99,
    "currency": "EUR",
    "payment_method": "credit_card",
    "items": [
      {
        "product_id": "prod_123",
        "product_name": "Zapato Casual Negro",
        "price": 49.99,
        "quantity": 2
      }
    ],
    "shipping_address": {
      "country": "ES",
      "city": "Madrid"
    }
  }
}

Ejemplo de payload para evento de acción

{
  "site_id": "site_123abc",
  "event_type": "action",
  "event_name": "form_submission",
  "url": "https://ejemplo.com/contact",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "form_id": "contact_form",
    "form_name": "Contact Form",
    "fields_completed": ["name", "email", "message"],
    "completion_time": 120,
    "success": true
  }
}

Ejemplo de payload para evento de movimiento del mouse

{
  "site_id": "site_123abc",
  "event_type": "mousemove",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "x": 500,
    "y": 300,
    "viewport": {
      "width": 1920,
      "height": 1080
    },
    "element": {
      "tag": "button",
      "class": "submit-button",
      "id": "checkout-btn",
      "text": "Checkout"
    }
  }
}

Ejemplo de payload para evento de scroll

{
  "site_id": "site_123abc",
  "event_type": "scroll",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "scroll_x": 0,
    "scroll_y": 500,
    "max_scroll": 2000,
    "viewport_height": 1080,
    "document_height": 3080,
    "percentage_scrolled": 25
  }
}

Ejemplo de payload para evento de teclado

{
  "site_id": "site_123abc",
  "event_type": "keypress",
  "url": "https://ejemplo.com/contact",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "key": "Enter",
    "key_code": 13,
    "element": {
      "tag": "input",
      "type": "text",
      "name": "email"
    },
    "is_sensitive": false
  }
}

Ejemplo de payload para evento de redimensionamiento

{
  "site_id": "site_123abc",
  "event_type": "resize",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "width": 1920,
    "height": 1080,
    "previous_width": 1366,
    "previous_height": 768,
    "orientation": "landscape"
  }
}

Ejemplo de payload para evento de foco/blur

{
  "site_id": "site_123abc",
  "event_type": "focus",
  "url": "https://ejemplo.com/contact",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "element": {
      "tag": "input",
      "type": "text",
      "name": "email",
      "placeholder": "Enter your email"
    },
    "focus_duration": 120000
  }
}

Ejemplo de payload para evento de formulario

{
  "site_id": "site_123abc",
  "event_type": "form_submit",
  "url": "https://ejemplo.com/contact",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "form_id": "contact-form",
    "form_name": "Contact Form",
    "fields": [
      {
        "name": "name",
        "type": "text",
        "filled": true
      },
      {
        "name": "email",
        "type": "email",
        "filled": true
      },
      {
        "name": "message",
        "type": "textarea",
        "filled": true
      }
    ],
    "completion_time": 120000,
    "success": true
  }
}

Ejemplo de payload para evento de rendimiento

{
  "site_id": "site_123abc",
  "event_type": "performance",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "navigation": {
      "load_time": 1250,
      "dom_content_loaded": 850,
      "first_paint": 920,
      "first_contentful_paint": 980
    },
    "resources": {
      "total": 25,
      "images": 10,
      "scripts": 8,
      "stylesheets": 4,
      "fonts": 3
    },
    "memory": {
      "used": 150000000,
      "total": 8589934592
    }
  }
}

Ejemplo de payload para evento de error

{
  "site_id": "site_123abc",
  "event_type": "error",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "timestamp": 1646123456789,
  "properties": {
    "error_type": "javascript",
    "message": "Cannot read property 'price' of undefined",
    "stack": "at calculateTotal (script.js:45:12)",
    "filename": "script.js",
    "line_number": 45,
    "column_number": 12,
    "user_agent": "Mozilla/5.0...",
    "browser": "Chrome",
    "browser_version": "98.0.4758.102"
  }
}

Session Recording Event Type

El tipo de evento session_recording permite capturar la actividad del usuario en detalle, incluyendo varios tipos de interacción como movimientos del ratón, clics, desplazamientos y pulsaciones de teclas. Esta capacidad de grabación completa de sesión facilita el análisis detallado del comportamiento del usuario en tu sitio web.

Estructura de la Grabación de Sesión

Una grabación de sesión incluye metadatos básicos como ID de grabación, tiempo de inicio y fin, duración, etc., así como un array de eventos de actividad detallados. Cada evento en el array debe incluir un campo type que indique el subtipo de evento.

{
  "site_id": "site_123abc",
  "event_type": "session_recording",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "segment_id": "seg_power_users",
  "timestamp": 1646123456789,
  "properties": {
    "recording_id": "rec_12345",
    "start_time": 1646123456789,
    "end_time": 1646123789456,
    "duration": 332667,
    "events": [
      { "type": "mousemove", "x": 100, "y": 200, "timestamp": 1646123456789 },
      { "type": "click", "x": 150, "y": 250, "timestamp": 1646123456790, "element": { "tag": "button", "id": "add-to-cart" } }
    ],
    "metadata": {
      "screen_size": "1920x1080",
      "browser": "Chrome",
      "browser_version": "98.0.4758.102",
      "os": "Windows",
      "device_type": "desktop"
    }
  }
}

Subtipos de Eventos Soportados

Los siguientes subtipos de eventos pueden incluirse en los arrays events y activity:

SubtipoPropiedades RequeridasPropiedades OpcionalesDescripción
mousemovex, y, timestampviewport, elementMovimiento del ratón
clickx, y, timestampelementClic del ratón
scrolltimestampx, y, percentage_scrolled, document_height, viewport_heightDesplazamiento de página
keypresstimestamp, keykey_code, element, is_sensitivePulsación de tecla
resizetimestamp, width, height`

Ejemplo de payload para activity bulk

{
  "site_id": "site_123abc",
  "event_type": "activity_bulk",
  "url": "https://ejemplo.com/productos",
  "visitor_id": "vis_abcd1234",
  "session_id": "sess_xyz789",
  "segment_id": "seg_active_users",
  "timestamp": 1646123456789,
  "properties": {
    "events": [
      { "type": "mousemove", "x": 100, "y": 200, "timestamp": 1646123456789 },
      { "type": "click", "x": 150, "y": 250, "timestamp": 1646123456790, "element": { "tag": "button", "id": "add-to-cart" } },
      { "type": "scroll", "x": 0, "y": 300, "timestamp": 1646123456791, "percentage_scrolled": 25 },
      { "type": "keypress", "key": "Enter", "timestamp": 1646123456792, "key_code": 13 }
    ]
  }
}

Respuesta

El endpoint responde con un objeto JSON que incluye:

{
  "success": true,
  "event_id": "evt_12345abcde",
  "visitor_id": "vis_abcd1234",
  "lead_id": "lead_xyz789",
  "session_id": "sess_xyz789",
  "segment_id": "seg_premium_users",
  "timestamp": 1646123456790
}
Last updated on
Endpoint de Sesiones