Eventi e API JavaScript

Il widget espone window.findalo: un bus di eventi di tutto ciò che accade nella ricerca e metodi per controllarla dal tuo codice. Il tuo JS può vivere nel tuo negozio o nell'editor del pannello (Aspetto → Avanzato).

Eventi

Evento	Payload	Quando
search	{ query, total, took_ms, match_mode, lang }	Ogni ricerca eseguita (query di 2+ caratteri). match_mode indica se i risultati sono diretti o suggeriti («fallback»).
zero	{ query, total: 0, took_ms, match_mode, lang }	Ricerca con 0 risultati. Raro: il widget non lascia mai la schermata vuota — il vero segnale di «nessun risultato» è search con match_mode «fallback».
click	{ product_id, product_name, product_url, price, currency, query, position }	Clic su un prodotto dei risultati.
add-to-cart	{ product_id, product_name, price, currency, quantity, cart_count }	Prodotto aggiunto al carrello dal widget di ricerca.
quick-view	{ product_id, product_name, product_url, price, currency, query, position }	Apertura della vista rapida di un prodotto.
cart-open	{ cart_count }	Apertura del pannello del carrello dall'intestazione del widget.
express-purchase	{ payment_intent, order_id, reference }	Acquisto completato via checkout express (se attivo).
open	{ prefill }	Apertura del widget di ricerca. prefill contiene la query iniziale, se presente.
close	{}	Chiusura del widget di ricerca.
context	el objeto window.FINDALO_CTX completo	El contexto de navegación ya resuelto, con la parte privada (carrito y cliente) incluida. Dispara una vez por carga de página. Ver /devs/contexto.

Esempi

Inviare le ricerche al tuo GA4

findalo.on('search', (e) => {
  gtag?.('event', 'site_search', { search_term: e.query, results: e.total });
});

(Per GA4 c'è un'integrazione senza codice nel pannello — Analytics → Inoltro al tuo GA4. Scrivi la tua solo se ti serve qualcosa di diverso.)

Rilevare le ricerche senza risultati reali

// Il widget non lascia mai la schermata vuota: se nulla corrisponde, mostra
// suggeriti con match_mode 'fallback'. Quello è il vero segnale di
// «nessun risultato» — l'evento 'zero' non scatta quasi mai.
findalo.on('search', (e) => {
  if (e.match_mode === 'fallback') {
    // es. aprire la tua chat di supporto con la query
  }
});

Aprire la ricerca dai tuoi elementi

document.querySelector('#hero-buscar')
  ?.addEventListener('click', () => findalo.open());

// o direttamente con una query:
findalo.search('crema hidratante');

Metodi e proprietà

Metodo / proprietà	Cosa fa
findalo.on(evento, callback)	Si iscrive a un evento del bus. Restituisce una funzione per annullare l'iscrizione.
findalo.open(query?)	Apre il widget di ricerca, opzionalmente con una query iniziale.
findalo.search(query)	Apre il widget di ricerca ed esegue la query.
findalo.close()	Chiude il widget di ricerca.
findalo.tenant	Slug del motore di ricerca (sola lettura).
findalo.lang	Lingua attiva del widget (sola lettura).
findalo.version	Versione dell'API JS (sola lettura).
findalo.context()	Contexto de navegación de la página: la misma variable window.FINDALO_CTX (tipo de página, ids, idioma, divisa, carrito, cliente). Ver /devs/contexto.
findalo.onContext(callback)	Ejecuta el callback con el contexto COMPLETO (carrito y cliente ya resueltos); si ya lo está, en el acto. Es la vía correcta si dependes del carrito.

Garanzia: i nomi degli eventi e le chiavi dei loro payload sono contratto stabile — possiamo aggiungere campi nuovi, mai rinominare né eliminare quelli esistenti.