Analítica y seguimiento

El widget reporta dos tipos de eventos al backend:

• Eventos automáticos (clicks de producto, conversiones detectadas) emitidos por el widget en respuesta a la interacción del usuario.
• Eventos manuales (eventos de negocio custom) enviados desde tu host vía POST /api/widget/analytics/event o el endpoint de batch.

Todo el tráfico va por la cabecera X-Widget-Token y comparte el rate-limit del filtro WidgetRateLimitFilter.

Eventos automáticos

Evento	Endpoint	Cuándo
Click de producto	POST /api/widget/track/click	Usuario hace click en una card o CTA de un resultado.
Conversión asistida	POST /api/widget/track/conversion	El widget detecta una conversión por el conversionSelector (cuando tracking.conversions = true).

Ambos endpoints están definidos en WidgetTrackingController.java. El payload incluye searchLogId y productId (más orderId, orderValue, currency, timeToConversionMs, userSessionId opcionales en conversion) para cerrar el bucle de attribution.

Conversiones server-to-server

La conversión por click-side es útil para demo y SPAs simples. Para attribution fiable en e-commerce real, conecta también el server-to-server: POST /api/plugin/shops/{shopId}/track/conversion con Shop API Key desde tu backend cuando se completa el pedido. Ver Quickstart paso 5.

Eventos manuales

Para eventos que el widget no detecta (impresión de banner, click en categoría, etc.) usa el endpoint genérico:

POST/api/widget/analytics/event

curl -X POST https://api.neuroon.ai/api/widget/analytics/event \
  -H "X-Widget-Token: $WIDGET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "category_click",
    "searchLogId": "log_abc",
    "productId": "p_1",
    "metadata": { "category": "running" }
  }'

Controlador: WidgetAnalyticsController.java.

Batch

Para reducir round-trips desde clientes con alto volumen:

POST/api/widget/analytics/events/batch

curl -X POST https://api.neuroon.ai/api/widget/analytics/events/batch \
  -H "X-Widget-Token: $WIDGET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "eventType": "result_impression", "searchLogId": "log_abc", "productId": "p_1", "position": 1 },
      { "eventType": "result_impression", "searchLogId": "log_abc", "productId": "p_2", "position": 2 }
    ]
  }'

El batch acepta hasta 100 eventos por petición (@Size(min = 1, max = 100) en BatchRequest).

Recomendación: acumula 5–20 eventos o flushea cada 2 s, lo que ocurra antes. navigator.sendBeacon es ideal para flush en unload.

Schema de un evento

Campo	Tipo	Requerido	Notas
eventType	string (max 30)	sí	Identificador del evento. Debe coincidir con un valor de WidgetAnalyticsEventType.
searchLogId	string (max 255)	recomendado	Vincula el evento a la sesión de búsqueda.
conversationId	string (max 36)	no	UUID de la conversación.
productId	string (max 255)	no	ID del producto relacionado, si aplica.
userSessionId	string (max 255)	no	Sesión de usuario opaca.
responseType	string (max 20)	no	Tipo de respuesta del agente cuando proceda.
enricherType	string (max 30)	no	Enricher que originó el evento.
position	integer	no	Posición en la lista (impresión/click).
metadata	object	no	Pares libres key → string | number | boolean (hasta 20 entradas).

Validación exacta: EventRequest en WidgetAnalyticsController.java.

Datos personales

No envíes PII en metadata (email, nombre, IP, identificadores de cliente). El widget está pensado como un canal de product analytics, no de CRM.

Rate limits

El filtro WidgetRateLimitFilter aplica un límite distinto por familia de endpoint (todos son por minuto, por shop):

Familia de endpoint	Límite/min
/api/widget/search/*	200
/api/widget/suggestions	300
/api/widget/compare	10
/api/widget/analytics/* (event y events/batch)	500
/api/widget/track/* (click, conversion) y demás	100

Si te pasas, recibes 429 Too Many Requests con Retry-After, X-RateLimit-Limit y X-RateLimit-Remaining. Ver Autenticación → Rate Limits.

Próximas lecturas

• Reference → Modelos de datos — schema Event.
• API → Plugin tracking — server-to-server.
• Quickstart paso 5 — flujo end-to-end.