Eventos y API JavaScript

El widget expone window.findalo: un bus de eventos de todo lo que pasa en el buscador y métodos para controlarlo desde tu código. Tu JS puede vivir en tu tienda o en el editor del panel (Apariencia → Avanzado).

Eventos

Evento	Payload	Cuándo
search	{ query, total, took_ms, match_mode, lang }	Cada búsqueda ejecutada (query de 2+ caracteres). match_mode indica si los resultados son directos o sugeridos («fallback»).
zero	{ query, total: 0, took_ms, match_mode, lang }	Búsqueda con 0 resultados. Raro: el buscador nunca deja la pantalla vacía — la señal real de «sin resultados» es search con match_mode «fallback».
click	{ product_id, product_name, product_url, price, currency, query, position }	Click en un producto de los resultados.
add-to-cart	{ product_id, product_name, price, currency, quantity, cart_count }	Producto añadido al carrito desde el buscador.
quick-view	{ product_id, product_name, product_url, price, currency, query, position }	Apertura de la vista rápida de un producto.
cart-open	{ cart_count }	Apertura del panel de la cesta desde la cabecera del buscador.
express-purchase	{ payment_intent, order_id, reference }	Compra completada vía checkout exprés (si está activo).
open	{ prefill }	Apertura del buscador. prefill lleva la query inicial si la hay.
close	{}	Cierre del buscador.
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.

Ejemplos

Enviar las búsquedas a tu GA4

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

(Para GA4 hay integración sin código en el panel — Analítica → Reenvío a tu GA4. Escribe la tuya solo si necesitas algo distinto.)

Detectar búsquedas sin resultados reales

// El buscador nunca deja la pantalla vacía: si nada casa, muestra
// sugeridos con match_mode 'fallback'. Esa es la señal real de
// «sin resultados» — el evento 'zero' casi nunca dispara.
findalo.on('search', (e) => {
  if (e.match_mode === 'fallback') {
    // ej. abrir tu chat de soporte con la query
  }
});

Abrir el buscador desde tus propios elementos

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

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

Métodos y propiedades

Método / propiedad	Qué hace
findalo.on(evento, callback)	Se suscribe a un evento del bus. Devuelve una función para desuscribirse.
findalo.open(query?)	Abre el buscador, opcionalmente con una query inicial.
findalo.search(query)	Abre el buscador y ejecuta la query.
findalo.close()	Cierra el buscador.
findalo.tenant	Slug del buscador (solo lectura).
findalo.lang	Idioma activo del widget (solo lectura).
findalo.version	Versión del API JS (solo 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.

Garantía: los nombres de eventos y las claves de sus payloads son contrato estable — podemos añadir campos nuevos, nunca renombrar ni eliminar los existentes.