Events und JavaScript-API
Das Widget stellt window.findalo bereit:
einen Event-Bus für alles, was in der Suche passiert, und Methoden, um sie aus deinem Code zu steuern.
Dein JS kann in deinem Shop leben oder im Editor des Dashboards (Darstellung → Erweitert).
Events
| Event | Payload | Wann |
|---|---|---|
| search | { query, total, took_ms, match_mode, lang } | Jede ausgeführte Suche (Query mit 2+ Zeichen). match_mode zeigt an, ob die Ergebnisse direkte Treffer oder Vorschläge sind („fallback“). |
| zero | { query, total: 0, took_ms, match_mode, lang } | Suche mit 0 Ergebnissen. Selten: Die Suche lässt den Bildschirm nie leer — das echte Signal für „keine Ergebnisse“ ist search mit match_mode „fallback“. |
| click | { product_id, product_name, product_url, price, currency, query, position } | Klick auf ein Produkt in den Ergebnissen. |
| add-to-cart | { product_id, product_name, price, currency, quantity, cart_count } | Produkt aus der Suche heraus in den Warenkorb gelegt. |
| quick-view | { product_id, product_name, product_url, price, currency, query, position } | Öffnen der Quick View eines Produkts. |
| cart-open | { cart_count } | Öffnen des Warenkorb-Panels über die Kopfzeile der Suche. |
| express-purchase | { payment_intent, order_id, reference } | Abgeschlossener Kauf über den Express-Checkout (falls aktiv). |
| open | { prefill } | Öffnen der Suche. prefill enthält die initiale Query, falls vorhanden. |
| close | {} | Schließen der Suche. |
| 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. |
Beispiele
Die Suchen an dein GA4 senden
findalo.on('search', (e) => {
gtag?.('event', 'site_search', { search_term: e.query, results: e.total });
}); (Für GA4 gibt es eine No-Code-Integration im Dashboard — Analytics → Weiterleitung an dein GA4. Schreib deine eigene nur, wenn du etwas anderes brauchst.)
Suchen ohne echte Ergebnisse erkennen
// Die Suche lässt den Bildschirm nie leer: Matcht nichts, zeigt sie
// Vorschläge mit match_mode 'fallback'. Das ist das echte Signal für
// „keine Ergebnisse“ — das Event 'zero' feuert fast nie.
findalo.on('search', (e) => {
if (e.match_mode === 'fallback') {
// z. B. deinen Support-Chat mit der Query öffnen
}
}); Die Suche über deine eigenen Elemente öffnen
document.querySelector('#hero-suche')
?.addEventListener('click', () => findalo.open());
// oder direkt mit einer Query:
findalo.search('feuchtigkeitscreme'); Methoden und Properties
| Methode / Property | Was sie macht |
|---|---|
| findalo.on(event, callback) | Abonniert ein Event des Busses. Gibt eine Funktion zum Abbestellen zurück. |
| findalo.open(query?) | Öffnet die Suche, optional mit einer initialen Query. |
| findalo.search(query) | Öffnet die Suche und führt die Query aus. |
| findalo.close() | Schließt die Suche. |
| findalo.tenant | Slug der Suchmaschine (nur lesend). |
| findalo.lang | Aktive Sprache des Widgets (nur lesend). |
| findalo.version | Version der JS-API (nur lesend). |
| 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: Die Event-Namen und die Keys ihrer Payloads sind stabiler Vertrag — wir können neue Felder hinzufügen, aber bestehende nie umbenennen oder entfernen.