> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panderra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget steuern & Events

> Öffne das Panderra-Widget per JavaScript, reagiere auf ungelesene Chat-Nachrichten und melde Conversions zurück an die Lernschleife.

Das Widget spricht in zwei Richtungen mit deiner Seite:

* **Du steuerst das Widget** über Methoden auf `window.Panderra` (öffnen,
  schließen, Conversion melden).
* **Das Widget meldet sich** über `panderra:*`-Events, die es auf dem
  `<ai-knowledger-search>`-Element auslöst.

Faustregel: **kommandieren = Methode, zuhören = Event.**

## Steuern: `window.Panderra`

`window.Panderra` ist verfügbar, sobald das Bundle geladen ist. Rufst du eine
Methode auf, **bevor** das Widget fertig gemountet ist, wird der Aufruf
gepuffert und nachgeholt — du musst also nicht auf ein „ready"-Signal warten.

```js theme={null}
// Such-Overlay öffnen (optional mit vorausgefüllter Suche)
window.Panderra.openSearch()
window.Panderra.openSearch('Vergaser')

// Direkt im KI-Berater öffnen (bestehender Verlauf bleibt erhalten)
window.Panderra.openChat()

// Overlay schließen
window.Panderra.close()
```

| Methode                    | Wirkung                                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `openSearch(query?)`       | Öffnet das Overlay in der Suche. Mit `query` wird sofort gesucht.                                          |
| `openChat()`               | Öffnet das Overlay direkt im KI-Berater.                                                                   |
| `close()`                  | Schließt das Overlay.                                                                                      |
| `trackConversion(payload)` | Meldet einen Suchergebnis-Klick außerhalb des Widgets — siehe [Conversion-Tracking](#conversion-tracking). |

<Tip>
  Typischer Einsatz: ein eigener „Frag die KI"-Button irgendwo auf der Seite, der
  `window.Panderra.openChat()` aufruft. So findet der Endkunde den Berater, ohne
  erst die Suche öffnen zu müssen.
</Tip>

## Zuhören: Events

Die Events laufen auf dem `<ai-knowledger-search>`-Element und durchdringen das
Shadow DOM (`composed: true`):

```js theme={null}
const widget = document.querySelector('ai-knowledger-search')

// Nach jeder frischen Ergebnis-Ladung (Auto-Suche + Enter)
widget.addEventListener('panderra:search-results', (e) => {
  console.log(e.detail.query, e.detail.results, e.detail.searchLogId)
})

// Wenn der Nutzer mit Enter bestätigt — dein Signal zum Navigieren
widget.addEventListener('panderra:search-submit', (e) => {
  location.href = `/suche?q=${encodeURIComponent(e.detail.query)}`
})

// Ungelesene Operator-Nachricht (Live-Chat) — fürs Badge am Launcher
widget.addEventListener('panderra:unread', (e) => {
  setBadge(e.detail.count)   // steigt bei neuer Nachricht, 0 sobald gelesen
})
```

| Event                     | `detail`                          | Wann                                                                                    |
| ------------------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
| `panderra:search-results` | `{ query, results, searchLogId }` | Nach jeder frischen Ergebnis-Ladung                                                     |
| `panderra:search-submit`  | `{ query, results, searchLogId }` | Nutzer bestätigt per Enter — Moment zum Navigieren                                      |
| `panderra:unread`         | `{ count }`                       | Operator-Nachricht trifft ein, während der Chat nicht sichtbar ist; `0`, sobald gelesen |

## Conversion-Tracking

Wenn du per `panderra:search-submit` auf deine **eigene** Ergebnisseite
weiterleitest, verlässt der Nutzer das Widget. Der anschließende Klick auf einen
Artikel passiert außerhalb — und ginge der Lernschleife verloren.
`trackConversion` meldet ihn zurück:

```js theme={null}
// Auf deiner Ergebnisseite, beim Klick auf einen Artikel:
artikelLink.addEventListener('click', () => {
  window.Panderra.trackConversion({ productId: 'A-12345' })
})
```

<ParamField path="productId" type="string" required>
  Produkt-ID / SKU des geklickten Artikels.
</ParamField>

<ParamField path="searchLogId" type="string">
  Die Suche, zu der der Klick gehört. Optional — fehlt sie, nutzt das Widget die
  zuletzt gemerkte Suche (übersteht einen Reload im selben Tab).
</ParamField>

<ParamField path="sessionId" type="string">
  Host-Session-ID. Optional — fällt sonst auf die Such-Session des Widgets zurück.
</ParamField>

<ParamField path="section" type="string">
  Aus welcher Stufe der Artikel kam: `treffer`, `ergebnisse`, `aehnliche`,
  `vielleicht` oder `pinned`. Nur für die Statistik.
</ParamField>

<Note>
  Für den typischen Ablauf (Suche im Widget → Enter → Weiterleitung → Klick im
  **selben Tab**) reicht `trackConversion({ productId })` ohne weitere IDs — das
  Widget merkt sich die Suche über die Sitzung. Willst du es tab-übergreifend
  exakt, gibst du die `searchLogId` aus `panderra:search-submit` über die
  Weiterleitung mit (z. B. als URL-Parameter) und reichst sie hier wieder ein.
</Note>

## Beispiel: JTL-Shop-Integration

So greift alles ineinander — Enter leitet auf die Standard-Ergebnisseite, der
Artikelklick dort schließt die Lernschleife:

```js theme={null}
const widget = document.querySelector('ai-knowledger-search')

// 1. Enter im Widget → auf die native Shop-Ergebnisseite, searchLogId mitnehmen
widget.addEventListener('panderra:search-submit', (e) => {
  const q = encodeURIComponent(e.detail.query)
  const log = encodeURIComponent(e.detail.searchLogId ?? '')
  location.href = `/suche?q=${q}&pq=${log}`
})

// 2. Auf der Ergebnisseite: jeden Artikelklick zurückmelden
const searchLogId = new URLSearchParams(location.search).get('pq') || undefined
document.querySelectorAll('.produkt-kachel a').forEach((link) => {
  link.addEventListener('click', () => {
    window.Panderra.trackConversion({
      productId: link.dataset.artikelId,
      searchLogId,
    })
  })
})
```