Événements et API JavaScript

Le widget expose window.findalo : un bus d'événements de tout ce qui se passe dans le moteur de recherche et des méthodes pour le contrôler depuis ton code. Ton JS peut vivre dans ta boutique ou dans l'éditeur du panneau (Apparence → Avancé).

Événements

Événement	Payload	Quand
search	{ query, total, took_ms, match_mode, lang }	Chaque recherche exécutée (query de 2+ caractères). match_mode indique si les résultats sont directs ou suggérés (« fallback »).
zero	{ query, total: 0, took_ms, match_mode, lang }	Recherche avec 0 résultat. Rare : le moteur de recherche ne laisse jamais l'écran vide — le vrai signal « aucun résultat » est search avec match_mode « fallback ».
click	{ product_id, product_name, product_url, price, currency, query, position }	Clic sur un produit des résultats.
add-to-cart	{ product_id, product_name, price, currency, quantity, cart_count }	Produit ajouté au panier depuis le moteur de recherche.
quick-view	{ product_id, product_name, product_url, price, currency, query, position }	Ouverture de l'aperçu rapide d'un produit.
cart-open	{ cart_count }	Ouverture du panneau du panier depuis l'en-tête du moteur de recherche.
express-purchase	{ payment_intent, order_id, reference }	Achat finalisé via le checkout express (s'il est actif).
open	{ prefill }	Ouverture du moteur de recherche. prefill porte la query initiale s'il y en a une.
close	{}	Fermeture du moteur de recherche.
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

Envoyer les recherches à ton GA4

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

(Pour GA4, il y a une intégration sans code dans le panneau — Analytique → Renvoi vers ton GA4. N'écris la tienne que si tu as besoin de quelque chose de différent.)

Détecter les recherches sans résultats réels

// Le moteur de recherche ne laisse jamais l'écran vide : si rien ne
// matche, il montre des suggestions avec match_mode 'fallback'. C'est
// le vrai signal « aucun résultat » — l'événement 'zero' ne se
// déclenche presque jamais.
findalo.on('search', (e) => {
  if (e.match_mode === 'fallback') {
    // ex. ouvrir ton chat de support avec la query
  }
});

Ouvrir le moteur de recherche depuis tes propres éléments

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

// ou directement avec une query :
findalo.search('crema hidratante');

Méthodes et propriétés

Méthode / propriété	Ce qu'elle fait
findalo.on(event, callback)	S'abonne à un événement du bus. Retourne une fonction pour se désabonner.
findalo.open(query?)	Ouvre le moteur de recherche, avec en option une query initiale.
findalo.search(query)	Ouvre le moteur de recherche et exécute la query.
findalo.close()	Ferme le moteur de recherche.
findalo.tenant	Slug du moteur de recherche (lecture seule).
findalo.lang	Langue active du widget (lecture seule).
findalo.version	Version de l'API JS (lecture seule).
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.

Garantie : les noms d'événements et les clés de leurs payloads sont un contrat stable — nous pouvons ajouter de nouveaux champs, jamais renommer ni supprimer les existants.