Live Search Inteligente — Guía completa

Presentación y requisitos

DFLiveSearch reemplaza la búsqueda nativa de PrestaShop por un motor live en AJAX: un panel de resultados se abre desde los primeros caracteres, con la imagen, la marca, el nombre, el precio y las insignias promocionales de cada producto. El módulo añade además un motor de búsqueda inteligente (marca, sinónimos, tolerancia a erratas, relevancia ponderada), carruseles de sugerencias (búsquedas populares y productos recomendados), un panel analítico completo y avisos email sobre las búsquedas sin resultado.

• Compatible con PrestaShop 8.0 a 9.x, tema Classic y temas derivados, tema Warehouse (iqit).
• PHP 8.1 y superior.
• Multi-tienda y multilingüe (FR/EN/ES/DE/IT/PT).
• Sin sobrescritura de archivos: solo hooks nativos.

Instalación

Instala el módulo como cualquier otro módulo de PrestaShop:

1. Descarga el archivo dflivesearch.zip desde tu cuenta de cliente.
2. En el back-office, ve a Módulos > Gestor de módulos.
3. Haz clic en Subir un módulo y suelta el archivo.
4. Una vez instalado, haz clic en Configurar.

En la instalación, el módulo registra sus hooks, crea sus tablas y rellena previamente un texto de marcador (placeholder) traducido a los seis idiomas. También se rellenan algunos grupos de sinónimos comunes y el diccionario de corrección de erratas se construye a partir de tu catálogo. El campo de búsqueda live queda activo inmediatamente en tu tienda.

Actualización

La actualización se realiza con normalidad desde el Gestor de módulos. El script de upgrade integrado crea las nuevas tablas, aplica los valores por defecto de las nuevas opciones (sinónimos, relevancia, tolerancia a erratas, búsqueda en la marca, apariencia de la barra) sin tocar tu configuración existente y luego reconstruye el diccionario de corrección. No se requiere ninguna acción manual. Tras actualizar, vacía la caché de PrestaShop y regenera los assets para purgar el JavaScript antiguo.

Configuración general

La página de configuración reúne los ajustes del comportamiento de la búsqueda:

• Activar el módulo: activa o desactiva el campo de búsqueda live en la tienda.
• Texto de marcador (placeholder): texto mostrado en el campo, traducible por idioma.
• Número mínimo de caracteres: umbral de activación de la búsqueda (2 por defecto).
• Número máximo de productos: límite de resultados mostrados en el panel.
• Mostrar los precios y mostrar los descuentos: controlan la presencia del precio y de la insignia de promoción en las tarjetas de resultados. Las reglas de PrestaShop se aplican siempre además de estos ajustes (ver «Visualización de los precios» más abajo).
• Búsquedas populares y búsquedas recientes: visualización de los carruseles de sugerencias antes de escribir.
• Autocompletar: sugerencias de términos (productos, categorías, marcas, búsquedas populares) mientras se escribe, con navegación por teclado (flechas arriba/abajo, Intro, Esc) y resaltado del término introducido. El número máximo de sugerencias es configurable.
• Añadir rápidamente al carrito y selector de cantidad: opciones para añadir un producto directamente desde los resultados.
• Productos personalizados: tiene en cuenta el historial del cliente conectado para las recomendaciones automáticas.

Apariencia

La sección Apariencia permite adaptar la búsqueda a tu identidad gráfica:

• Color principal: color de los botones y acentos (por defecto #2196F3).
• Color principal (hover): color al pasar el ratón sobre los botones (por defecto #1976D2).
• Ancho máx. de la ventana: ancho máximo del panel de búsqueda. Acepta un valor CSS como 900px, 1200px o 100%.
• Tamaño de la barra de búsqueda (desde la versión 1.4.0): Small, Medium o Large. Ajusta la altura, el tamaño del texto y el del icono de la barra mostrada en tu cabecera.
• Ancho de la barra de búsqueda: ancho máximo de la propia barra (400px, 50%, 30rem…). Deja el campo vacío para ocupar todo el ancho del contenedor del tema.
• Radio de las esquinas de la barra: de 0 (esquinas rectas) a 50 px (forma de píldora).
• Atajo de teclado: abre la búsqueda con Ctrl+K (Cmd+K en Mac) o la tecla / desde cualquier lugar de la página. En escritorio se muestra una insignia indicativa («Ctrl K» o «⌘K») en la barra. La opción puede desactivarse.

Desde la versión 1.4.0, la ventana de búsqueda es totalmente accesible por teclado: la barra es enfocable y se abre con Intro o Espacio, el foco permanece dentro de la ventana durante la navegación con Tab, Esc la cierra y el foco vuelve a la barra. Un botón de borrado aparece en el campo en cuanto se escribe texto, y las animaciones respetan la preferencia del sistema prefers-reduced-motion.

Compatibilidad con temas y activadores personalizados

Desde la versión 1.5.0, la ventana de búsqueda se separa de la cabecera al cargar la página: funciona incluso cuando el tema oculta su contenedor (cabecera de escritorio oculta en móvil) o lo hace sticky. Coexisten tres formas de abrir la búsqueda:

• La barra de búsqueda del módulo, insertada mediante los hooks displayTop o displaySearch.
• Cualquier elemento de tu tema con la clase dflivesearch-trigger o el atributo data-dflivesearch-trigger: el módulo le asocia automáticamente la apertura de la búsqueda (clic y teclado, con los atributos ARIA).
• Los botones de búsqueda nativos del tema Warehouse (iqit): la lupa de la cabecera móvil (#mobile-btn-search) y la de escritorio (#iqit-search-btn) abren directamente el módulo, en lugar del desplegable de iqitsearch. No se requiere ninguna modificación de plantilla.

Productos recomendados

Los productos recomendados aparecen en carrusel nada más abrir el campo de búsqueda. Hay dos modos disponibles mediante el ajuste Origen de los productos recomendados:

• Automático: el módulo selecciona los más vendidos (y tiene en cuenta el historial del cliente si la opción «Productos personalizados» está activada).
• Manual: eliges con precisión los productos destacados.

En modo manual, aparece un selector dedicado: busca un producto por nombre o referencia, haz clic para añadirlo y luego reordena las miniaturas arrastrando y soltando. El orden definido se respeta en la visualización de la tienda.

Comportamiento de la búsqueda

Búsqueda por palabras

La búsqueda funciona por palabras: cada palabra introducida debe encontrarse (en el nombre, la marca, la referencia, el código EAN o la descripción corta), en cualquier orden. Una consulta como «estetoscopio simple campana» encuentra así el producto aunque esas palabras no estén juntas en el nombre. Desde la versión 1.2.0, cada palabra también se extiende a sus sinónimos y la búsqueda cubre las referencias de variantes (ver la sección «Búsqueda inteligente»).

Productos con combinaciones

Para un producto con combinaciones, el botón de añadir al carrito se sustituye por un botón «Ver opciones» que enlaza con la ficha de producto, para que el cliente elija su combinación antes de añadir. Cuando el cliente ha buscado la referencia exacta de una combinación, este botón lleva directamente a la variante correspondiente.

Disponibilidad y stock

Los productos sin stock permanecen visibles en los resultados y llevan una insignia «Sin stock». Esta insignia no aparece en los productos cuyo pedido sin stock está permitido (ajuste «Permitir pedidos» de PrestaShop): esos siguen siendo añadibles al carrito.

Visualización de los precios

Desde la versión 1.5.0, el módulo aplica las reglas de visualización de precios de PrestaShop, además de su propio ajuste «Mostrar los precios»:

• Modo catálogo (Preferencias > Productos): no se muestra ningún precio ni botón de carrito en los resultados.
• Grupos de clientes: si el grupo del visitante tiene la opción «Mostrar los precios» desactivada (caso habitual en B2B para los visitantes no conectados), los precios se ocultan.
• Opción del producto: un producto con «Mostrar precio» desmarcado en su ficha no muestra ni precio ni descuento.

En todos estos casos, el botón de añadir al carrito también se retira y el añadido se rechaza en el servidor: el cliente es redirigido a la ficha de producto. El ajuste «Mostrar los descuentos» oculta el precio tachado y la insignia de descuento sin tocar el precio actual.

Búsqueda inteligente: marca, sinónimos, erratas y relevancia

Desde la versión 1.2.0, DFLiveSearch incluye un motor de búsqueda inteligente. Todos estos ajustes están en la sección Búsqueda inteligente de la página de configuración.

Búsqueda en la marca

Desde la versión 1.5.0, la opción «Buscar en el nombre de la marca» (activada por defecto) consulta también el fabricante del producto. Una consulta como «Littmann estetoscopio» encuentra el producto correcto aunque la marca no forme parte de su nombre: cada palabra se busca en el nombre, la descripción corta, los códigos y la marca. La marca se muestra en las tarjetas de resultados, encima del nombre del producto, y los nombres de marcas se proponen en el autocompletar. Una coincidencia exacta de la marca se clasifica mejor que una coincidencia parcial del nombre.

Sinónimos

El diccionario de sinónimos relaciona términos equivalentes: un cliente que busca «tv» también encuentra los productos llamados «televisión» o «tele». El editor es multilingüe (una pestaña por idioma). Introduce un grupo por línea, con los términos separados por comas:

tv, tele, televisión, televisor
ordenador, pc, portátil
casco, auriculares, cascos

Todos los términos de una misma línea se consideran equivalentes: buscar uno de ellos extiende automáticamente la consulta a los demás. Activa o desactiva la función mediante la opción Activar los sinónimos. Algunos grupos comunes vienen rellenados de fábrica; adáptalos a tu catálogo.

Tolerancia a erratas

Cuando una búsqueda no devuelve resultados, el módulo intenta corregir automáticamente la errata a partir de un diccionario construido desde tu catálogo (nombres de productos, referencias, marcas, categorías). Si la corrección da resultados, se muestran directamente con la mención «Resultados para…» y un enlace para volver a la ortografía original.

• Tolerancia a erratas: activa o desactiva la corrección automática.
• Distancia de corrección máx.: número máximo de caracteres distintos tolerado (1 a 3; 2 recomendado). Un valor más alto corrige más erratas pero aumenta el riesgo de falsos positivos.
• Mostrar «¿Quiso decir?»: muestra el banner de corrección. Desactivada, la corrección se aplica de forma silenciosa.

La corrección se basa en una preselección fonética (SOUNDEX) seguida de un cálculo de distancia de Levenshtein: recupera por ejemplo «televisión» a partir de «televsión». Las palabras de menos de tres caracteres no se corrigen; las equivalencias cortas (como «tv») se gestionan con los sinónimos.

Diccionario de corrección

El diccionario de corrección (tabla dflivesearch_lexicon) se construye en la instalación y puede reconstruirse en cualquier momento mediante el botón Reconstruir el diccionario de la página de configuración. La zona de información muestra el número de palabras indexadas y la fecha de la última reconstrucción. Desde la versión 1.5.0, los nombres de marcas se indexan además de los nombres de productos, las referencias y las categorías.

Relevancia de los resultados

Los resultados se clasifican por una puntuación de relevancia ponderada: coincidencia exacta del nombre (puntuación más alta), nombre que empieza por la consulta, marca exacta, consulta contenida en el nombre, marca parcial, luego referencia y EAN. Dos boosts completan esta clasificación:

• Boost de productos en stock: a relevancia comparable, los productos disponibles suben arriba de la lista.
• Boost de más vendidos: favorece los productos más vendidos, a partir de las estadísticas de ventas de PrestaShop.

Ambas opciones pueden activarse de forma independiente en la sección Búsqueda inteligente.

Búsqueda por referencia de variante

La búsqueda cubre los identificadores propios de las combinaciones: referencia, EAN, UPC y referencia de proveedor de cada variante. Escribir la referencia o el código de barras de una combinación hace aparecer así el producto padre. Cuando la consulta parece un código, el resultado apunta directamente a la combinación correcta (enlace a la variante exacta) y la tarjeta muestra la referencia y el precio de esa variante.

Panel de control y estadísticas

El módulo registra cada búsqueda (término introducido, número de resultados, posible clic en un producto, conversión en pedido). El panel del back-office muestra:

• el total de búsquedas y el número de búsquedas únicas;
• las tasas de éxito, de clic y de conversión;
• un gráfico de evolución de las búsquedas por día;
• el top 20 de búsquedas con clics y conversiones;
• el top 20 de búsquedas sin resultado;
• una exportación CSV del conjunto de los datos.

El seguimiento de conversiones se realiza mediante el hook actionOrderStatusPostUpdate: un pedido realizado tras un clic en los resultados de búsqueda se contabiliza como convertido. Desde la versión 1.3.0, cada pedido se contabiliza una sola vez, independientemente de los cambios de estado posteriores.

Avisos email

El sistema de avisos vigila los términos que no devuelven ningún resultado. En cuanto un término supera el umbral configurable (5 por defecto), se envía un aviso email a la dirección que elijas y aparece una notificación en el encabezado del back-office. Cada aviso puede marcarse como leído o descartarse. Las plantillas de email se incluyen en los seis idiomas (ES/EN/FR/DE/IT/PT) y el asunto se envía en el idioma por defecto de la tienda. Estas búsquedas sin resultado son una fuente valiosa para detectar lagunas del catálogo, erratas frecuentes o sinónimos que faltan por añadir.

Retención de datos

Los logs de búsqueda se conservan 90 días por defecto (duración configurable). Hay un botón de limpieza manual en el back-office y, desde la versión 1.3.0, una purga automática se aplica de forma continua según el periodo de retención configurado.

FAQ y resolución de problemas

La búsqueda «marca + producto» no devuelve nada

Comprueba que la opción «Buscar en el nombre de la marca» (sección Búsqueda inteligente) esté activada, disponible desde la versión 1.5.0, y que el fabricante esté asignado en la ficha de producto. Tras actualizar, vacía la caché y regenera los assets.

Aparecen precios que deberían estar ocultos

El respeto del modo catálogo, de los grupos de clientes sin precios y de la opción «Mostrar precio» del producto está disponible desde la versión 1.5.0. Actualiza el módulo, vacía la caché de PrestaShop y regenera los assets. Comprueba también que la opción «Mostrar los precios» del módulo corresponda a lo que esperas.

La búsqueda no se abre en móvil (tema Warehouse)

Actualiza a la versión 1.5.0: la ventana de búsqueda es ahora independiente de la cabecera y la lupa de la cabecera móvil de Warehouse abre directamente el módulo. Vacía la caché de PrestaShop, regenera los assets y vacía la caché del navegador (la concatenación CCC del tema puede servir el JavaScript antiguo). Si habías modificado una plantilla del tema para colocar un activador, esa modificación sigue siendo compatible.

¿Cómo configurar los sinónimos?

En la sección «Búsqueda inteligente» de la configuración, introduce un grupo de sinónimos por línea (términos separados por comas) en la pestaña de cada idioma y guarda. Comprueba que la opción «Activar los sinónimos» esté activa.

¿Cómo cambiar el tamaño o la forma de la barra de búsqueda?

En la sección «Apariencia», elige el tamaño de la barra (Small / Medium / Large), el ancho máximo y el radio de las esquinas. Un radio de 50 da una barra en forma de píldora. Estos ajustes solo afectan a la barra mostrada en la cabecera; la ventana de resultados se controla con «Ancho máx. de la ventana».

¿Cómo desactivar el atajo Ctrl+K?

En la sección «Apariencia», pon la opción «Atajo de teclado» en No. La insignia desaparece de la barra y las teclas Ctrl+K, Cmd+K y / dejan de abrir la búsqueda.

Una búsqueda con una errata devuelve una página vacía

Comprueba que la opción «Tolerancia a erratas» esté activada y que el diccionario de corrección contenga palabras (zona de información de la configuración). Tras una importación importante, haz clic en «Reconstruir el diccionario». También puedes aumentar la «Distancia de corrección máx.».

La búsqueda no encuentra una referencia de variante

La búsqueda por referencia de variante (ref, EAN, UPC, ref de proveedor) está disponible desde la versión 1.2.0. Actualiza, vacía la caché y regenera los assets. Para obtener el enlace directo a la variante exacta, la consulta debe parecerse a un código (contener al menos una cifra).

La búsqueda no devuelve nada para varias palabras

La búsqueda funciona por palabras independientes del orden. Si acabas de actualizar, vacía la caché de PrestaShop y regenera los assets para cargar el nuevo JavaScript.

El panel de autocompletar oculta los resultados

El autocompletar se cierra automáticamente cuando el campo pierde el foco o con la tecla Esc. Asegúrate de usar la última versión y vacía la caché si el comportamiento antiguo persiste.

Aparece una insignia «sin stock» en un producto que puede pedirse

El módulo lee el ajuste «Permitir pedidos» en la pestaña Cantidades de la ficha de producto (almacenado en StockAvailable en PrestaShop 8). Comprueba este ajuste: si permite el pedido, no se mostrará ninguna insignia.

¿Qué ocurre al desinstalar?

La desinstalación elimina limpiamente los hooks, las variables de configuración y las seis tablas del módulo. No se deja ningún dato residual en la base de datos.