Live Search Intelligente — Guida completa

Presentazione e prerequisiti

DFLiveSearch sostituisce la ricerca nativa di PrestaShop con un motore live in AJAX: un pannello di risultati si apre fin dai primi caratteri, con l’immagine, il marchio, il nome, il prezzo e i badge promozionali di ogni prodotto. Il modulo aggiunge inoltre un motore di ricerca intelligente (marchio, sinonimi, tolleranza agli errori di battitura, pertinenza ponderata), caroselli di suggerimenti (ricerche popolari e prodotti consigliati), una dashboard analitica completa e avvisi email sulle ricerche senza risultato.

• Compatibile con PrestaShop 8.0 fino a 9.x, tema Classic e temi derivati, tema Warehouse (iqit).
• PHP 8.1 e superiore.
• Multinegozio e multilingua (FR/EN/ES/DE/IT/PT).
• Nessuna sovrascrittura di file: solo hook nativi.

Installazione

Installa il modulo come qualsiasi altro modulo PrestaShop:

1. Scarica l’archivio dflivesearch.zip dal tuo account cliente.
2. Nel back-office, vai su Moduli > Gestore dei moduli.
3. Clicca su Carica un modulo e rilascia l’archivio.
4. Una volta installato, clicca su Configura.

All’installazione, il modulo registra i suoi hook, crea le sue tabelle e pre-compila un testo segnaposto (placeholder) tradotto nelle sei lingue. Vengono inoltre pre-compilati alcuni gruppi di sinonimi comuni e il dizionario di correzione degli errori viene costruito a partire dal tuo catalogo. Il campo di ricerca live è immediatamente attivo sul tuo negozio.

Aggiornamento

L’aggiornamento avviene normalmente dal Gestore dei moduli. Lo script di upgrade integrato crea le nuove tabelle, applica i valori predefiniti delle nuove opzioni (sinonimi, pertinenza, tolleranza agli errori, ricerca nel marchio, aspetto della barra) senza toccare la tua configurazione esistente, poi ricostruisce il dizionario di correzione. Non è richiesta alcuna azione manuale. Dopo l’aggiornamento, svuota la cache di PrestaShop e rigenera gli asset per eliminare il vecchio JavaScript.

Configurazione generale

La pagina di configurazione raccoglie le impostazioni del comportamento della ricerca:

• Attivare il modulo: attiva o disattiva il campo di ricerca live sul negozio.
• Testo segnaposto (placeholder): testo mostrato nel campo, traducibile per lingua.
• Numero minimo di caratteri: soglia di attivazione della ricerca (2 per impostazione predefinita).
• Numero massimo di prodotti: limite di risultati mostrati nel pannello.
• Mostrare i prezzi e mostrare gli sconti: controllano la presenza del prezzo e del badge promozione sulle schede dei risultati. Le regole di PrestaShop si applicano sempre in aggiunta a queste impostazioni (vedi «Visualizzazione dei prezzi» più avanti).
• Ricerche popolari e ricerche recenti: visualizzazione dei caroselli di suggerimenti prima della digitazione.
• Autocompletamento: suggerimenti di termini (prodotti, categorie, marchi, ricerche popolari) durante la digitazione, con navigazione da tastiera (frecce su/giù, Invio, Esc) ed evidenziazione del termine inserito. Il numero massimo di suggerimenti è configurabile.
• Aggiunta rapida al carrello e selettore di quantità: opzioni per aggiungere un prodotto direttamente dai risultati.
• Prodotti personalizzati: tiene conto dello storico del cliente connesso per le raccomandazioni automatiche.

Aspetto

La sezione Aspetto permette di adattare la ricerca alla tua identità grafica:

• Colore principale: colore dei pulsanti e degli accenti (predefinito #2196F3).
• Colore principale (hover): colore al passaggio del mouse sui pulsanti (predefinito #1976D2).
• Larghezza max della finestra: larghezza massima del pannello di ricerca. Accetta un valore CSS come 900px, 1200px o 100%.
• Dimensione della barra di ricerca (dalla versione 1.4.0): Small, Medium o Large. Regola l’altezza, la dimensione del testo e quella dell’icona della barra mostrata nell’intestazione.
• Larghezza della barra di ricerca: larghezza massima della barra stessa (400px, 50%, 30rem…). Lascia il campo vuoto per occupare tutta la larghezza del contenitore del tema.
• Raggio degli angoli della barra: da 0 (angoli retti) a 50 px (forma a pillola).
• Scorciatoia da tastiera: apre la ricerca con Ctrl+K (Cmd+K su Mac) o il tasto / da qualsiasi punto della pagina. Su desktop viene mostrato un badge indicativo («Ctrl K» o «⌘K») nella barra. L’opzione è disattivabile.

Dalla versione 1.4.0, la finestra di ricerca è completamente accessibile da tastiera: la barra è focalizzabile e si apre con Invio o Spazio, il focus resta all’interno della finestra durante la navigazione con Tab, Esc la chiude e il focus torna sulla barra. Un pulsante di cancellazione appare nel campo non appena viene digitato del testo, e le animazioni rispettano la preferenza di sistema prefers-reduced-motion.

Compatibilità con i temi e trigger personalizzati

Dalla versione 1.5.0, la finestra di ricerca viene staccata dall’intestazione al caricamento della pagina: funziona anche quando il tema nasconde il suo contenitore (intestazione desktop nascosta su mobile) o lo rende sticky. Coesistono tre modi per aprire la ricerca:

• La barra di ricerca del modulo, inserita tramite gli hook displayTop o displaySearch.
• Qualsiasi elemento del tuo tema con la classe dflivesearch-trigger o l’attributo data-dflivesearch-trigger: il modulo vi collega automaticamente l’apertura della ricerca (clic e tastiera, con gli attributi ARIA).
• I pulsanti di ricerca nativi del tema Warehouse (iqit): la lente dell’intestazione mobile (#mobile-btn-search) e quella desktop (#iqit-search-btn) aprono direttamente il modulo, al posto del menu a discesa di iqitsearch. Nessuna modifica ai template richiesta.

Prodotti consigliati

I prodotti consigliati appaiono in carosello non appena si apre il campo di ricerca. Sono disponibili due modalità tramite l’impostazione Origine dei prodotti consigliati:

• Automatica: il modulo seleziona i più venduti (e tiene conto dello storico cliente se l’opzione «Prodotti personalizzati» è attivata).
• Manuale: scegli con precisione i prodotti in evidenza.

In modalità manuale, appare un selettore dedicato: cerca un prodotto per nome o riferimento, clicca per aggiungerlo, poi riordina le miniature trascinandole. L’ordine definito viene rispettato nella visualizzazione lato negozio.

Comportamento della ricerca

Ricerca per parole

La ricerca funziona per parole: ogni parola inserita deve essere trovata (nel nome, nel marchio, nel riferimento, nel codice EAN o nella descrizione breve), in qualsiasi ordine. Una query come «stetoscopio semplice padiglione» trova quindi il prodotto anche se queste parole non sono consecutive nel nome. Dalla versione 1.2.0, ogni parola viene anche estesa ai suoi sinonimi e la ricerca copre i riferimenti delle varianti (vedi la sezione «Ricerca intelligente»).

Prodotti con combinazioni

Per un prodotto con combinazioni, il pulsante di aggiunta al carrello è sostituito da un pulsante «Vedi opzioni» che rimanda alla scheda prodotto, affinché il cliente scelga la sua combinazione prima dell’aggiunta. Quando il cliente ha cercato il riferimento esatto di una combinazione, questo pulsante conduce direttamente alla variante interessata.

Disponibilità e stock

I prodotti esauriti restano visibili nei risultati e riportano un badge «Esaurito». Questo badge non appare per i prodotti il cui ordine fuori stock è autorizzato (impostazione «Accetta ordini» di PrestaShop): questi restano aggiungibili al carrello.

Visualizzazione dei prezzi

Dalla versione 1.5.0, il modulo applica le regole di visualizzazione dei prezzi di PrestaShop, in aggiunta alla propria impostazione «Mostrare i prezzi»:

• Modalità catalogo (Preferenze > Prodotti): nessun prezzo né pulsante carrello viene mostrato nei risultati.
• Gruppi clienti: se il gruppo del visitatore ha l’opzione «Mostra i prezzi» disattivata (caso comune nel B2B per i visitatori non connessi), i prezzi vengono nascosti.
• Opzione prodotto: un prodotto con «Mostra prezzo» deselezionato sulla sua scheda non mostra né prezzo né sconto.

In tutti questi casi, anche il pulsante di aggiunta al carrello viene rimosso e l’aggiunta viene rifiutata lato server: il cliente viene reindirizzato alla scheda prodotto. L’impostazione «Mostrare gli sconti» nasconde il prezzo barrato e il badge di sconto senza toccare il prezzo corrente.

Ricerca intelligente: marchio, sinonimi, errori di battitura e pertinenza

Dalla versione 1.2.0, DFLiveSearch integra un motore di ricerca intelligente. Tutte queste impostazioni si trovano nella sezione Ricerca intelligente della pagina di configurazione.

Ricerca nel marchio

Dalla versione 1.5.0, l’opzione «Cerca nel nome del marchio» (attiva per impostazione predefinita) interroga anche il produttore del prodotto. Una query come «Littmann stetoscopio» trova il prodotto giusto anche se il marchio non fa parte del suo nome: ogni parola viene cercata nel nome, nella descrizione breve, nei codici e nel marchio. Il marchio viene mostrato sulle schede dei risultati, sopra il nome del prodotto, e i nomi dei marchi vengono proposti nell’autocompletamento. Una corrispondenza esatta sul marchio è classificata meglio di una corrispondenza parziale sul nome.

Sinonimi

Il dizionario di sinonimi collega termini equivalenti: un cliente che cerca «tv» trova anche i prodotti chiamati «televisione» o «tele». L’editor è multilingua (una scheda per lingua). Inserisci un gruppo per riga, con i termini separati da virgole:

tv, tele, televisione, televisore
computer, pc, portatile
cuffie, auricolari, headphones

Tutti i termini di una stessa riga sono considerati equivalenti: cercarne uno estende automaticamente la query agli altri. Attiva o disattiva la funzionalità tramite l’opzione Attivare i sinonimi. Alcuni gruppi comuni sono pre-compilati all’installazione; adattali al tuo catalogo.

Tolleranza agli errori di battitura

Quando una ricerca non restituisce risultati, il modulo tenta automaticamente di correggere l’errore a partire da un dizionario costruito dal tuo catalogo (nomi di prodotti, riferimenti, marchi, categorie). Se la correzione dà risultati, vengono mostrati direttamente con la dicitura «Risultati per…» e un link per tornare all’ortografia originale.

• Tolleranza agli errori di battitura: attiva o disattiva la correzione automatica.
• Distanza di correzione max: numero massimo di caratteri differenti tollerato (da 1 a 3; 2 consigliato). Un valore più alto corregge più errori ma aumenta il rischio di falsi positivi.
• Mostrare «Forse cercavi?»: mostra il banner di correzione. Disattivata, la correzione si applica silenziosamente.

La correzione si basa su una preselezione fonetica (SOUNDEX) seguita da un calcolo della distanza di Levenshtein: ritrova ad esempio «televisione» a partire da «televisone». Le parole di meno di tre caratteri non vengono corrette; le equivalenze brevi (come «tv») sono gestite dai sinonimi.

Dizionario di correzione

Il dizionario di correzione (tabella dflivesearch_lexicon) viene costruito all’installazione e può essere ricostruito in qualsiasi momento tramite il pulsante Ricostruire il dizionario della pagina di configurazione. L’area informativa mostra il numero di parole indicizzate e la data dell’ultima ricostruzione. Dalla versione 1.5.0, i nomi dei marchi vengono indicizzati oltre ai nomi dei prodotti, ai riferimenti e alle categorie.

Pertinenza dei risultati

I risultati sono ordinati secondo un punteggio di pertinenza ponderato: corrispondenza esatta del nome (punteggio più alto), nome che inizia con la query, marchio esatto, query contenuta nel nome, marchio parziale, poi riferimento ed EAN. Due boost completano questa classifica:

• Boost prodotti disponibili: a pertinenza comparabile, i prodotti disponibili salgono in cima alla lista.
• Boost più venduti: favorisce i prodotti più venduti, a partire dalle statistiche di vendita di PrestaShop.

Entrambe le opzioni sono attivabili in modo indipendente nella sezione Ricerca intelligente.

Ricerca per riferimento di variante

La ricerca copre gli identificatori propri delle combinazioni: riferimento, EAN, UPC e riferimento fornitore di ogni variante. Digitare il riferimento o il codice a barre di una combinazione fa quindi emergere il prodotto padre. Quando la query somiglia a un codice, il risultato punta direttamente alla combinazione corretta (link alla variante esatta) e la scheda mostra il riferimento e il prezzo di quella variante.

Dashboard e statistiche

Il modulo registra ogni ricerca (termine inserito, numero di risultati, eventuale clic su un prodotto, conversione in ordine). La dashboard del back-office mostra:

• il totale delle ricerche e il numero di ricerche uniche;
• i tassi di successo, di clic e di conversione;
• un grafico di evoluzione delle ricerche per giorno;
• la top 20 delle ricerche con clic e conversioni;
• la top 20 delle ricerche senza risultato;
• un export CSV dell’insieme dei dati.

Il tracciamento delle conversioni avviene tramite l’hook actionOrderStatusPostUpdate: un ordine effettuato dopo un clic nei risultati di ricerca viene conteggiato come convertito. Dalla versione 1.3.0, ogni ordine viene conteggiato una sola volta, indipendentemente dai successivi cambi di stato.

Avvisi email

Il sistema di avvisi sorveglia i termini che non restituiscono alcun risultato. Non appena un termine supera la soglia configurabile (5 per impostazione predefinita), un avviso email viene inviato all’indirizzo di tua scelta e una notifica appare nell’header del back-office. Ogni avviso può essere marcato come letto o eliminato. I template email sono forniti nelle sei lingue (IT/EN/FR/ES/DE/PT) e l’oggetto viene inviato nella lingua predefinita del negozio. Queste ricerche senza risultato sono una fonte preziosa per rilevare le lacune del catalogo, gli errori di battitura frequenti o i sinonimi mancanti da aggiungere.

Conservazione dei dati

I log di ricerca sono conservati 90 giorni per impostazione predefinita (durata configurabile). Un pulsante di pulizia manuale è disponibile nel back-office e, dalla versione 1.3.0, una pulizia automatica viene applicata in continuo secondo il periodo di conservazione configurato.

FAQ e risoluzione dei problemi

La ricerca «marchio + prodotto» non restituisce nulla

Verifica che l’opzione «Cerca nel nome del marchio» (sezione Ricerca intelligente) sia attivata, disponibile dalla versione 1.5.0, e che il produttore sia associato sulla scheda prodotto. Dopo l’aggiornamento, svuota la cache e rigenera gli asset.

Appaiono prezzi che dovrebbero essere nascosti

Il rispetto della modalità catalogo, dei gruppi clienti senza prezzi e dell’opzione «Mostra prezzo» del prodotto è disponibile dalla versione 1.5.0. Aggiorna il modulo, svuota la cache di PrestaShop e rigenera gli asset. Verifica anche che l’opzione «Mostrare i prezzi» del modulo corrisponda a ciò che ti aspetti.

La ricerca non si apre su mobile (tema Warehouse)

Aggiorna alla versione 1.5.0: la finestra di ricerca è ora indipendente dall’intestazione e la lente dell’intestazione mobile di Warehouse apre direttamente il modulo. Svuota la cache di PrestaShop, rigenera gli asset e svuota la cache del browser (la concatenazione CCC del tema può servire il vecchio JavaScript). Se avevi modificato un template del tema per inserire un trigger, quella modifica resta compatibile.

Come configurare i sinonimi?

Nella sezione «Ricerca intelligente» della configurazione, inserisci un gruppo di sinonimi per riga (termini separati da virgole) nella scheda di ogni lingua, poi salva. Verifica che l’opzione «Attivare i sinonimi» sia attiva.

Come cambiare la dimensione o la forma della barra di ricerca?

Nella sezione «Aspetto», scegli la dimensione della barra (Small / Medium / Large), la larghezza massima e il raggio degli angoli. Un raggio di 50 dà una barra a forma di pillola. Queste impostazioni riguardano solo la barra mostrata nell’intestazione; la finestra dei risultati si regola con «Larghezza max della finestra».

Come disattivare la scorciatoia Ctrl+K?

Nella sezione «Aspetto», imposta l’opzione «Scorciatoia da tastiera» su No. Il badge scompare dalla barra e i tasti Ctrl+K, Cmd+K e / non aprono più la ricerca.

Una ricerca con un errore restituisce una pagina vuota

Verifica che l’opzione «Tolleranza agli errori di battitura» sia attivata e che il dizionario di correzione contenga parole (area informativa della configurazione). Dopo un import importante, clicca su «Ricostruire il dizionario». Puoi anche aumentare la «Distanza di correzione max».

La ricerca non trova un riferimento di variante

La ricerca per riferimento di variante (rif, EAN, UPC, rif fornitore) è disponibile dalla versione 1.2.0. Aggiorna, svuota la cache e rigenera gli asset. Per ottenere il link diretto alla variante esatta, la query deve somigliare a un codice (contenere almeno una cifra).

La ricerca non restituisce nulla per più parole

La ricerca funziona per parole indipendenti dall’ordine. Se hai appena aggiornato, svuota la cache di PrestaShop e rigenera gli asset per caricare il nuovo JavaScript.

Il pannello di autocompletamento nasconde i risultati

L’autocompletamento si chiude automaticamente quando il campo perde il focus o con il tasto Esc. Assicurati di usare l’ultima versione e svuota la cache se il vecchio comportamento persiste.

Un badge «esaurito» appare su un prodotto ordinabile

Il modulo legge l’impostazione «Accetta ordini» nella scheda Quantità della scheda prodotto (memorizzata in StockAvailable su PrestaShop 8). Verifica questa impostazione: se autorizza l’ordine, nessun badge verrà mostrato.

Cosa succede alla disinstallazione?

La disinstallazione rimuove in modo pulito gli hook, le variabili di configurazione e le sei tabelle del modulo. Nessun dato residuo viene lasciato nel database.