Eventos e API JavaScript

O widget expõe window.findalo: um bus de eventos de tudo o que acontece na pesquisa e métodos para a controlar a partir do seu código. O seu JS pode viver na sua loja ou no editor do painel (Aparência → Avançado).

Eventos

Evento	Payload	Quando
search	{ query, total, took_ms, match_mode, lang }	Cada pesquisa executada (query de 2+ caracteres). match_mode indica se os resultados são diretos ou sugeridos («fallback»).
zero	{ query, total: 0, took_ms, match_mode, lang }	Pesquisa com 0 resultados. Raro: o widget nunca deixa o ecrã vazio — o sinal real de «sem resultados» é search com match_mode «fallback».
click	{ product_id, product_name, product_url, price, currency, query, position }	Clique num produto dos resultados.
add-to-cart	{ product_id, product_name, price, currency, quantity, cart_count }	Produto adicionado ao carrinho a partir da pesquisa.
quick-view	{ product_id, product_name, product_url, price, currency, query, position }	Abertura da vista rápida de um produto.
cart-open	{ cart_count }	Abertura do painel do carrinho a partir do cabeçalho da pesquisa.
express-purchase	{ payment_intent, order_id, reference }	Compra concluída via checkout expresso (se estiver ativo).
open	{ prefill }	Abertura da pesquisa. prefill leva a query inicial, se existir.
close	{}	Fecho da pesquisa.
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.

Exemplos

Enviar as pesquisas para o seu GA4

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

(Para o GA4 há integração sem código no painel — Analítica → Reencaminhamento para o seu GA4. Escreva a sua só se precisar de algo diferente.)

Detetar pesquisas sem resultados reais

// O widget nunca deixa o ecrã vazio: se nada corresponde, mostra
// sugeridos com match_mode 'fallback'. Esse é o sinal real de
// «sem resultados» — o evento 'zero' quase nunca dispara.
findalo.on('search', (e) => {
  if (e.match_mode === 'fallback') {
    // ex. abrir o seu chat de suporte com a query
  }
});

Abrir a pesquisa a partir dos seus próprios elementos

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

// ou diretamente com uma query:
findalo.search('crema hidratante');

Métodos e propriedades

Método / propriedade	O que faz
findalo.on(evento, callback)	Subscreve um evento do bus. Devolve uma função para anular a subscrição.
findalo.open(query?)	Abre a pesquisa, opcionalmente com uma query inicial.
findalo.search(query)	Abre a pesquisa e executa a query.
findalo.close()	Fecha a pesquisa.
findalo.tenant	Slug do motor de pesquisa (apenas leitura).
findalo.lang	Idioma ativo do widget (apenas leitura).
findalo.version	Versão da API JS (apenas leitura).
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: os nomes dos eventos e as chaves dos seus payloads são contrato estável — podemos adicionar campos novos, nunca renomear nem eliminar os existentes.