Configuración del widget

Esta página es la fuente de verdad única de NeuroonWidgetConfig, verificada línea por línea contra el código fuente del widget (src/types.ts + src/context/ConfigContext.tsx) — no contra otras páginas de esta documentación. Si otra página del sitio (incluso el Snippet Builder) discrepa de lo que dice aquí, esta página tiene razón.

El widget acepta configuración por dos vías:

1. Atributos data-* en el <script> para auto-init (server-rendered).
2. NeuroonWidgetConfig vía window.NeuroonWidget.init(config) para control programático.

Ambas vías producen la misma instancia. Si pasas ambas, init(config) tiene prioridad.

Atributos data-*

Atributo	Requerido	Default	Qué hace
data-token	sí	—	Widget Token firmado por tu servidor
data-container	no	#neuroon-search	Selector CSS del contenedor. Si no coincide con ningún elemento, el auto-init aborta con un warning en consola
data-theme	no	auto	light, dark, auto
data-locale	no	autodetect (fallback es)	es, en, fr, de, it, pt, ca, eu, gl
data-api-url	no	https://api.neuroon.ai	Override del host de la API. Disponible desde v0.9.19 — en versiones anteriores este atributo se ignoraba silenciosamente y apiUrl solo era alcanzable vía init()
data-placeholder	no	""	Texto del input vacío
data-suggestions	no	true	"false" desactiva sugerencias
data-filters	no	true	"false" desactiva filtros
data-primary-color	no	—	No hace nada. Existe en el parser y valida el formato del color, pero el mapeo a CSS está vacío — no pinta ningún override visual. Usa styles.primary vía init() en su lugar

Estos son los únicos atributos que el widget lee del <script> — cualquier otro data-* se reenvía al tag pero se ignora en silencio. Para translations, cart, tracking, callbacks, monitoring o refreshEndpoint, usa init() programático.

NeuroonWidgetConfig

interface NeuroonWidgetConfig {
  container: string | HTMLElement
  token: string
  apiUrl?: string                        // default: 'https://api.neuroon.ai'
  fallbackApiUrl?: string                // opcional — API secundaria si la búsqueda contra apiUrl falla (desde v0.9.23)
  refreshEndpoint?: string               // URL para refrescar el token; ver nota debajo
  theme?: 'auto' | 'light' | 'dark' | 'detect'  // default: 'auto'
  locale?: 'es' | 'en' | 'fr' | 'de' | 'it' | 'pt' | 'ca' | 'eu' | 'gl'
  translations?: Partial<Translations>
  styles?: StyleOverrides | { light?: StyleOverrides; dark?: StyleOverrides }
  features?: FeatureFlags
  ui?: UIOptions
  tracking?: TrackingConfig
  callbacks?: Callbacks
  monitoring?: MonitoringConfig
  cart?: CartConfig
}

refreshEndpoint vs. callbacks.onTokenExpiring

Si defines refreshEndpoint, el widget lo usa para refrescar el token automáticamente. Si no lo defines pero sí das callbacks.onTokenExpiring, usa ese callback. Si no das ninguno de los dos, el widget no refresca el token — expirará cada 24 h y tendrás que reinicializarlo.

FeatureFlags

interface FeatureFlags {
  suggestions?: boolean     // default: true  — dropdown de sugerencias
  filters?: boolean         // default: true  — filtros guiados
  voiceSearch?: boolean     // default: true  — búsqueda por voz (requiere soporte del navegador)
  imageSearch?: boolean     // default: true  — búsqueda por imagen
  aiAssistant?: boolean     // default: true  — asistente conversacional
  comparison?: boolean      // default: true  — comparador de productos (máx. 4)
  mentions?: boolean        // default: true  — @menciones y drag&drop de productos en el chat
  streaming?: boolean       // default: true  — streaming de tokens en respuestas del agente
  agentSearch?: boolean     // default: true  — modo de búsqueda conversacional/agéntico
  fastSearch?: boolean      // default: false — modo de búsqueda instantánea, no conversacional (desde v0.9.19)
}

agentSearch y fastSearch no pueden estar ambos en false

Son los dos modos de búsqueda del widget. Si intentas desactivar ambos, el widget fuerza agentSearch de vuelta a true (con un warning en consola en desarrollo) — siempre queda al menos un modo activo. Si activas los dos (bothActive), el usuario final ve un selector para alternar entre modo conversacional y modo rápido. fastSearch pega a un endpoint distinto (/api/widget/search/fast), independiente del pipeline conversacional.

UIOptions

interface UIOptions {
  placeholder?: string           // default: ''             — texto del input vacío
  resultsPerPage?: number        // default: 20             — resultados por página
  showPrices?: boolean           // default: true           — mostrar precios
  showBrands?: boolean           // default: true           — mostrar marcas
  layout?: 'grid' | 'list'       // default: 'grid'          — ⚠️ no tiene efecto (ver nota)
  displayMode?: 'fullscreen' | 'panel'  // default: 'fullscreen'
  fabPosition?: string           // default: 'bottom-right' — posición del botón flotante
  fabHint?: string                // default: ''              — texto del tooltip del FAB
  overlayContainer?: HTMLElement | null  // default: null    — confina el overlay a este elemento (desde v0.9.26)
}

layout no está cableado

layout se valida y se acepta, pero ningún componente lo lee para cambiar entre grid y lista. Documentarlo como funcional sería mentir — está aquí para que sepas que declarar layout: 'list' hoy no produce ningún cambio visual.

overlayContainer confina el chat/resultados a un contenedor propio

Por defecto el widget abre el chat/resultados como overlay a pantalla completa (un portal fijado al body, por encima de todo lo demás). Si pasas overlayContainer (un elemento del DOM), el overlay se confina dentro de ese elemento en lugar de tapar toda la pantalla — útil para incrustar el widget dentro de un panel de tamaño fijo. La funcionalidad se introdujo en v0.9.23; usa v0.9.26 o superior, versión donde se estabilizaron varios bugs de aislamiento del overlay confinado.

callbacks

interface Callbacks {
  onSearch?: (query: string) => void
  onResultClick?: (product: Product) => void
  onFilterChange?: (filters: AppliedFilters) => void
  onError?: (error: Error) => void
  onTokenExpiring?: () => Promise<string>
  onTokenRefreshed?: (newToken: string) => void
}

Los 6 campos están realmente cableados (verificado en App.tsx, useSearch.ts, useProductHandlers.ts, useSearchHandlers.ts). También existe onConversion?: (product: Product) => void en el tipo, pero no está cableado a nada — la atribución real de conversiones va por la cookie neuroon_clicks, no por este callback.

TrackingConfig

interface TrackingConfig {
  clicks?: boolean             // default: true   — trackea clics en productos (real)
}

clicks dispara POST /api/widget/track/click en cada clic/add-to-cart de un producto y controla si se escribe la cookie de atribución neuroon_clicks, leída por el plugin de WordPress al completarse el pedido. El callback onConversion (ver arriba) sigue sin estar conectado a ningún flujo — la atribución real siempre va por esta cookie, no por ese callback.

monitoring (opcional)

interface MonitoringConfig {
  applicationId: string
  clientToken: string
  // …opciones del SDK de Datadog RUM
}

Si lo configuras, el widget inicializa @datadog/browser-rum-slim de forma asíncrona — el RUM auto-instrumentado de Datadog (recursos, interacciones, long tasks) sí funciona. Los hooks de tracking custom del widget (trackAction/trackError) existen en el código pero ningún componente los invoca hoy — no esperes eventos custom propios en tu dashboard de Datadog, solo lo que Datadog captura automáticamente.

cart

Ver Integración de carrito para el contrato completo de CartConfig, CartState y CartOperationResult.

styles

Acepta un objeto plano (mismos valores para ambos temas) o uno por tema ({ light: {...}, dark: {...} }). Ver Theming y CSS Variables para la lista completa de campos.

Validación

Regla	Mensaje
token ausente	[NeuroonWidget] token is required
container ausente	[NeuroonWidget] container is required
apiUrl no es URL válida	[NeuroonWidget] Invalid apiUrl
theme no soportado	warning, fallback a auto
locale no soportado	warning, fallback a es
resultsPerPage <= 0	[NeuroonWidget] resultsPerPage must be greater than 0

Próximas lecturas

• Snippet Builder — genera tu configuración con un formulario, en 2 minutos.
• Instalación — script tag, SRI, CSP.
• Theming — StyleOverrides y variables --nrn-*.
• Integración de carrito — CartConfig, CartState.
• Eventos del widget — CustomEvents del DOM.