Configuración del widget

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

1. Atributos data-* en el <script> cuando se usa auto-init — la forma soportada en plantillas server-rendered (WordPress, ASP.NET, PHP, etc.).
2. NeuroonWidgetConfig vía la API JavaScript window.NeuroonWidget.init(config) cuando necesitas callbacks, cart integration o control programático.

Ambas vías producen la misma instancia. Si pasas ambas, lo que llega vía init(config) tiene prioridad sobre los data-*.

Atributos data-*

Atributo	Requerido	Default	Notas
data-token	sí	—	Widget Token de 24 h firmado por tu servidor con la Shop API Key (HMAC).
data-container	no	#neuroon-search	Selector CSS o id del contenedor.
data-theme	no	auto	auto | light | dark. Si es auto, se evalúa prefers-color-scheme y se actualiza al cambiar.
data-locale	no	autodetect (fallback es)	Códigos válidos: es, en, fr, de, it, pt, ca, eu, gl.
data-api-url	no	https://api.neuroon.ai	Override del API base URL. Conmuta a Development con https://dev-api.neuroon.ai.
data-placeholder	no	(string i18n)	Texto del input vacío.
data-suggestions	no	true	false deshabilita el dropdown de sugerencias.
data-filters	no	true	false deshabilita filtros y el drawer.
data-primary-color	no	(theme default)	Hex/rgb del color primario (legacy; preferir StyleOverrides).

El parser ignora silenciosamente cualquier atributo data-* no listado arriba.

NeuroonWidgetConfig

interface NeuroonWidgetConfig {
  container: string | HTMLElement
  token: string
  apiUrl?: string
  theme?: 'auto' | 'light' | 'dark'
  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
}

callbacks

interface Callbacks {
  onTokenExpiring?: () => Promise<string>
  onTokenRefreshed?: (newToken: string) => void
}

Sólo hay callbacks para gestión del Widget Token. No hay callbacks públicos para search, result-click, filter-change, conversion ni error. Para reaccionar a actividad del widget, suscríbete a los CustomEvents del DOM — ver Events.

cart

Cuando cart.enabled = true, el widget se integra con el carrito del host (WooCommerce, custom). El host implementa todas las callbacks; el widget las invoca con la firma agnóstica de plataforma:

interface CartConfig {
  enabled: boolean
  initialCount?: number
  onGetCart: () => Promise<CartState>
  onAddToCart: (productId: string, quantity: number, externalProductId?: string) => Promise<CartOperationResult>
  onRemoveFromCart: (itemKey: string) => Promise<CartOperationResult>
  onUpdateQuantity: (itemKey: string, quantity: number) => Promise<CartOperationResult>
  onCheckout: () => void
  canAddToCart?: (product: Product) => boolean
  externalUpdateEvent?: string  // default 'neuroon:cart-update'
  onSetDestinationCountry?: (countryCode: string) => Promise<CartOperationResult | void>
}

Patrón completo end-to-end en Recipe · Custom cart bridge.

monitoring (opcional)

interface MonitoringConfig {
  applicationId: string
  clientToken: string
  // …SDK options
}

Solo lo activan clientes "managed" por Neuroon. Si lo configuras, el bundle inicializa @datadog/browser-rum de forma asíncrona.

styles

Acepta un objeto plano (mismos valores en ambos temas) o uno por tema ({ light: {...}, dark: {...} }). Ver theming.md para la lista de variables --nrn-* y los casts a triplete RGB.

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

• Theming — StyleOverrides y variables --nrn-*.
• Internacionalización — los 9 idiomas y custom translations.
• Eventos del widget — qué emite y qué escucha del host.
• Reference → Modelos de datos — Product, SearchResponse, CartState.