Esdeveniments i API JavaScript

El widget exposa window.findalo: un bus d'esdeveniments de tot el que passa al cercador i mètodes per controlar-lo des del teu codi. El teu JS pot viure a la teva botiga o a l'editor del panell (Aparença → Avançat).

Esdeveniments

Esdeveniment	Payload	Quan
search	{ query, total, took_ms, match_mode, lang }	Cada cerca executada (query de 2+ caràcters). match_mode indica si els resultats són directes o suggerits («fallback»).
zero	{ query, total: 0, took_ms, match_mode, lang }	Cerca amb 0 resultats. Rar: el cercador mai no deixa la pantalla buida — el senyal real de «sense resultats» és search amb match_mode «fallback».
click	{ product_id, product_name, product_url, price, currency, query, position }	Clic en un producte dels resultats.
add-to-cart	{ product_id, product_name, price, currency, quantity, cart_count }	Producte afegit a la cistella des del cercador.
quick-view	{ product_id, product_name, product_url, price, currency, query, position }	Obertura de la vista ràpida d'un producte.
cart-open	{ cart_count }	Obertura del panell de la cistella des de la capçalera del cercador.
express-purchase	{ payment_intent, order_id, reference }	Compra completada via checkout exprés (si està actiu).
open	{ prefill }	Obertura del cercador. prefill porta la query inicial si n'hi ha.
close	{}	Tancament del cercador.
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.

Exemples

Enviar les cerques al teu GA4

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

(Per a GA4 hi ha integració sense codi al panell — Analítica → Reenviament al teu GA4. Escriu la teva només si necessites alguna cosa diferent.)

Detectar cerques sense resultats reals

// El cercador mai no deixa la pantalla buida: si res no casa, mostra
// suggerits amb match_mode 'fallback'. Aquest és el senyal real de
// «sense resultats» — l'esdeveniment 'zero' gairebé mai dispara.
findalo.on('search', (e) => {
  if (e.match_mode === 'fallback') {
    // p. ex. obrir el teu xat de suport amb la query
  }
});

Obrir el cercador des dels teus propis elements

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

// o directament amb una query:
findalo.search('crema hidratante');

Mètodes i propietats

Mètode / propietat	Què fa
findalo.on(esdeveniment, callback)	Se subscriu a un esdeveniment del bus. Retorna una funció per desubscriure's.
findalo.open(query?)	Obre el cercador, opcionalment amb una query inicial.
findalo.search(query)	Obre el cercador i executa la query.
findalo.close()	Tanca el cercador.
findalo.tenant	Slug del cercador (només lectura).
findalo.lang	Idioma actiu del widget (només lectura).
findalo.version	Versió de l'API JS (només lectura).
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.

Garantia: els noms dels esdeveniments i les claus dels seus payloads són contracte estable — podem afegir camps nous, mai no renomenar ni eliminar els existents.