> ## 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.

# Such-Widget einbinden

> Bette die Panderra-Suche mit KI-Berater als Overlay in deinen Shop oder deine Website ein — ein Script-Tag, ein HTML-Element.

Das Panderra-Such-Widget legt sich als Overlay über deine Seite: eine
Produktsuche mit vier Ergebnis-Stufen und einem eingebauten KI-Berater
(„Berater fragen"). Es läuft in einem **Shadow DOM** — eigene Styles, die nicht
mit deinem Shop-CSS kollidieren — und kommt als **eine** JavaScript-Datei, ohne
externe Abhängigkeiten.

<Note>
  Das Widget erbt die Schrift deiner Seite und hält die Oberfläche neutral. Die
  einzige Marken-Farbe steuerst du über das `accent`-Attribut (siehe unten) — so
  fügt es sich in jedes Shop-Theme ein.
</Note>

## Voraussetzungen

<Check>**Widget-Token** (`wt_…`) — im Admin-UI unter **Einstellungen → Widget** erstellt. Der Token ist öffentlich (er steht im Quelltext deiner Seite) und nur auf Such- und Chat-Zugriff beschränkt.</Check>
<Check>**API-URL** deiner Panderra-Instanz, z. B. `https://app.panderra.ai`.</Check>

## Schnellstart

<Steps>
  <Step title="Einbettungs-Code holen">
    Den fertigen Script-Tag mit deinem Token findest du im Admin-UI unter
    **Einstellungen → Widget**. Die folgenden Schritte erklären, woraus er
    besteht.
  </Step>

  <Step title="Script laden">
    Lade das Widget-Bundle einmal pro Seite — am besten kurz vor `</body>`:

    ```html theme={null}
    <script src="https://app.panderra.ai/widget/ai-knowledger-widget.js" defer></script>
    ```
  </Step>

  <Step title="Widget-Element einsetzen">
    Platziere das Custom-Element irgendwo im `<body>`. Es rendert nichts
    Sichtbares, bis es geöffnet wird:

    ```html theme={null}
    <ai-knowledger-search
      token="wt_dein_token"
      api-url="https://app.panderra.ai"
      trigger="#shop-suche"
      popular-terms="Vergaser, Auspuff, Zündkerze"
      accent="#476247"
    ></ai-knowledger-search>
    ```
  </Step>

  <Step title="Trigger verbinden">
    `trigger` nimmt einen oder mehrere CSS-Selektoren (komma-getrennt). Ein
    Klick oder Fokus auf ein passendes Element öffnet das Overlay —
    typischerweise dein vorhandenes Suchfeld:

    ```html theme={null}
    <input id="shop-suche" type="search" placeholder="Suchen…" />
    ```

    Ohne `trigger` öffnest du das Widget programmatisch über
    [`window.Panderra.openSearch()`](/widget/steuern-und-events).
  </Step>
</Steps>

## Attribute

<ParamField path="token" type="string" required>
  Widget-Token (`wt_…`) aus dem Admin-UI. Bindet das Widget an deinen Tenant.
</ParamField>

<ParamField path="api-url" type="string" required>
  Basis-URL deiner Panderra-Instanz, z. B. `https://app.panderra.ai`.
</ParamField>

<ParamField path="trigger" type="string">
  CSS-Selektor(en), die das Overlay öffnen. Mehrere komma-getrennt
  (`#suche, .header-search`).
</ParamField>

<ParamField path="accent" type="string">
  Marken-Akzentfarbe als Hex (`#476247`). Alle abgeleiteten Töne (Hover,
  Schatten, Tints) folgen automatisch. Ohne Angabe nutzt das Widget einen
  neutralen Default.
</ParamField>

<ParamField path="popular-terms" type="string">
  Komma-getrennte Begriffe, die als anklickbare Vorschläge erscheinen, solange das
  Suchfeld leer ist.
</ParamField>

<ParamField path="placeholder" type="string">
  Platzhalter-Text im Suchfeld.
</ParamField>

<ParamField path="session-id" type="string">
  Optionale Host-Session-ID (z. B. die Shop-Session). Gruppiert Suchanfragen
  derselben Sitzung in der Statistik. Ohne Angabe vergibt das Widget eine eigene,
  tab-lokale ID.
</ParamField>

<ParamField path="advisor-enabled" type="string">
  `"true"` / `"false"` — blendet den „Berater fragen"-Button (KI-Chat) ein oder
  aus. Default: an.
</ParamField>

<ParamField path="show-scores" type="string">
  `"true"` / `"false"` — zeigt pro Treffer einen Relevanz-Score. Nützlich beim
  Onboarding und Tuning, für Endkunden eher aus. Default: aus.
</ParamField>

### Feintuning (optional)

Diese Attribute haben sinnvolle Defaults und müssen selten gesetzt werden:

| Attribut              | Default | Wirkung                                              |
| --------------------- | ------- | ---------------------------------------------------- |
| `debounce-suggest-ms` | `150`   | Verzögerung bis Vorschläge erscheinen (ab 2 Zeichen) |
| `debounce-search-ms`  | `300`   | Verzögerung bis die Auto-Suche feuert (ab 3 Zeichen) |
| `vielleicht-initial`  | `3`     | Anzahl initial sichtbarer „Vielleicht"-Treffer       |
| `vielleicht-step`     | `5`     | Nachladeschritt für „Vielleicht"-Treffer             |
| `pin-max-count`       | `10`    | Maximal anheftbare Artikel                           |
| `empty-state-message` | —       | Eigener Text, wenn nichts gefunden wurde             |
| `site-id`             | —       | Site-Kontext für Multi-Site-Tenants                  |

## Weiter

<Card title="Widget steuern und Events" href="/widget/steuern-und-events" icon="code">
  Das Overlay per JavaScript öffnen, auf ungelesene Nachrichten reagieren und
  Conversions zurückmelden.
</Card>
