Configuración del Widget

El widget de Neuroon se configura mediante atributos data-* en el script tag o mediante JavaScript.

Configuración con data attributes

<script
  src="https://cdn.neuroon.ai/widget.js"
  data-token="YOUR_TOKEN"
  data-container="#neuroon-search"
  data-theme="auto"
  data-locale="es"
  data-placeholder="¿Qué estás buscando?">
</script>

Opciones disponibles (data attributes)

Atributo	Tipo	Default	Descripción
data-token	string	requerido	Token de autenticación del widget
data-container	string	requerido	Selector CSS del contenedor
data-theme	string	"auto"	Tema: "light", "dark", "auto"
data-locale	string	"es"	Idioma: "es", "en"
data-placeholder	string	""	Placeholder del input de búsqueda
data-primary-color	string	""	Color primario (ej: #6366f1)
data-suggestions	string	"true"	Habilitar autocompletado: "true", "false"
data-filters	string	"true"	Habilitar panel de filtros: "true", "false"

Configuración avanzada

Los data-attributes cubren la configuración básica. Para opciones avanzadas (features, UI, callbacks), usa la API de JavaScript.

Configuración con JavaScript

Para mayor control, usa la API de JavaScript:

const widget = NeuroonWidget.init({
  container: '#neuroon-search',
  token: 'YOUR_TOKEN',
  apiUrl: 'https://api.neuroon.ai',
  theme: 'auto',
  locale: 'es',
  features: {
    suggestions: true,
    filters: true,
    voiceSearch: true,
    imageSearch: true,
    aiAssistant: false,
  },
  ui: {
    placeholder: '¿Qué estás buscando?',
    resultsPerPage: 20,
    showPrices: true,
    showBrands: true,
    layout: 'grid',
  },
  tracking: {
    clicks: true,
  },
  callbacks: {
    onResultClick: (product) => console.log('Click:', product),
    onFilterChange: (filters) => console.log('Filtros:', filters),
  },
});

Features

Controla qué funcionalidades están disponibles en el widget.

interface FeatureFlags {
  suggestions?: boolean;   // Autocompletado (default: true)
  filters?: boolean;       // Panel de filtros (default: true)
  voiceSearch?: boolean;   // Búsqueda por voz (default: true)
  imageSearch?: boolean;   // Búsqueda por imagen (default: true)
  aiAssistant?: boolean;   // Asistente IA con respuestas (default: false)
}

Búsqueda por voz

features: {
  voiceSearch: true, // Habilitado por defecto
}

• Requiere HTTPS (excepto localhost)
• Navegadores soportados: Chrome, Safari, Edge
• Idioma: Español (es-ES)

Búsqueda por imagen

features: {
  imageSearch: true, // Habilitado por defecto
}

• Formatos soportados: JPEG, PNG, WebP
• Tamaño máximo: 10MB
• Permite captura de cámara o upload de archivo

Asistente IA

features: {
  aiAssistant: true, // Deshabilitado por defecto
}

Cuando está activo, el widget muestra respuestas contextuales del asistente IA junto con los resultados de búsqueda.

Disponibilidad

El asistente IA está disponible en planes Growth y superiores.

Filtros guiados

Los filtros guiados se generan automáticamente basándose en la intención de búsqueda del usuario. Incluyen:

• Categorías relevantes
• Marcas sugeridas
• Rangos de precio
• Tags relacionados

No requieren configuración adicional, solo que filters: true.

UI Options

Personaliza la interfaz del widget.

interface UIOptions {
  placeholder?: string;                    // Placeholder del input
  resultsPerPage?: number;                 // Productos por página (default: 20)
  showPrices?: boolean;                    // Mostrar precios (default: true)
  showBrands?: boolean;                    // Mostrar marcas (default: true)
  layout?: 'grid' | 'list';                // Layout de resultados (default: 'grid')
  displayMode?: 'fullscreen' | 'panel';    // Modo de visualización (default: 'fullscreen')
}

displayMode

Controla cómo se muestra el widget:

Valor	Descripción
fullscreen	Overlay a pantalla completa (default)
panel	Panel lateral integrado en la página

ui: {
  displayMode: 'fullscreen', // Por defecto
}

Tema

El widget soporta 3 modos de tema:

Valor	Comportamiento
light	Tema claro siempre
dark	Tema oscuro siempre
auto	Sigue prefers-color-scheme del sistema (default)

theme: 'auto', // Sigue la preferencia del sistema operativo

Recomendación

El modo auto es ideal para la mayoría de sitios. Si tu sitio tiene tema fijo, usa light o dark según corresponda.

Tracking

Configura el tracking de eventos del widget.

interface TrackingConfig {
  clicks?: boolean;            // Tracking de clicks en productos (default: true)
  conversions?: boolean;       // Tracking de conversiones (default: false)
  conversionSelector?: string; // Selector CSS del botón de conversión
}

Tracking de clicks

Habilitado por defecto. Registra cuando un usuario hace clic en un producto para mejorar la relevancia de búsqueda.

tracking: {
  clicks: true,
}

Tracking de conversiones

Registra cuando un usuario realiza una conversión (añadir al carrito, compra, etc.) después de hacer clic en un producto.

tracking: {
  clicks: true,
  conversions: true,
  conversionSelector: '.add-to-cart-button', // Selector CSS opcional
}

Cuando conversions: true, el widget registra automáticamente las conversiones para los productos clickeados, mejorando las recomendaciones futuras.

Token

El token tiene una validez de 1 hora. Para sesiones largas donde el usuario permanece en la página, se recomienda recargar la página periódicamente o implementar una solución de refresh en tu backend.

Manejo de expiración

Si el token expira:

• Las búsquedas posteriores fallarán con error de autenticación
• El usuario deberá recargar la página para obtener un nuevo token

Recomendación

Para aplicaciones SPA donde el usuario puede permanecer más de 1 hora, considera regenerar el token periódicamente desde tu backend.

Callbacks

Los callbacks permiten ejecutar código personalizado cuando ocurren eventos en el widget.

callbacks: {
  onSearch: (query) => {
    // Se ejecuta después de cada búsqueda
    gtag('event', 'search', { search_term: query });
  },
  onResultClick: (product) => {
    // Se ejecuta cuando el usuario hace clic en un producto
    gtag('event', 'select_item', {
      item_id: product.id,
      item_name: product.name,
    });
  },
  onFilterChange: (filters) => {
    // Se ejecuta cuando cambian los filtros
    console.log('Filtros aplicados:', filters);
  },
  onError: (error) => {
    // Se ejecuta cuando ocurre un error
    console.error('Widget error:', error.message);
  },
}

Más información

Consulta la documentación de callbacks para ver la lista completa de callbacks disponibles y sus parámetros.

Configuración completa

const widget = NeuroonWidget.init({
  // Requeridos
  container: '#neuroon-search',
  token: 'YOUR_TOKEN',

  // Opcionales
  apiUrl: 'https://api.neuroon.ai',
  theme: 'auto',
  locale: 'es',

  // Features
  features: {
    suggestions: true,
    filters: true,
    voiceSearch: true,
    imageSearch: true,
    aiAssistant: false,
  },

  // UI
  ui: {
    placeholder: '¿Qué estás buscando?',
    resultsPerPage: 20,
    showPrices: true,
    showBrands: true,
    layout: 'grid',
    displayMode: 'fullscreen',
  },

  // Tracking
  tracking: {
    clicks: true,
    conversions: false,
    conversionSelector: '.add-to-cart-button',
  },

  // Styles (ver Theming)
  styles: {
    primary: '#06b6d4',
    // ...más variables
  },

  // Translations (ver Traducciones)
  translations: {
    // ...custom translations
  },

  // Callbacks
  callbacks: {
    onSearch: (query) => {},
    onResultClick: (product) => {},
    onFilterChange: (filters) => {},
    onError: (error) => {},
  },
});

Siguiente paso

• Theming - Personaliza los colores y estilos
• Traducciones - Personaliza los textos
• JavaScript API - Control programático del widget
• Callbacks - Responde a eventos
• Accesibilidad - Cumplimiento WCAG 2.2 AA