Einen Assistenten in eine Website einbetten

Live zu gehen ist größtenteils Kopieren und Einfügen. Sie fügen Ihrer Seite drei Dinge hinzu – das Seekdown-Runtime-Skript, ein Container-Element und ein kurzes Snippet zum Starten –, und das war's. Das ist genau das Snippet, das das Produkt für Sie erzeugt.

Bevor Sie beginnen

Fügen Sie die Domain der Website zu den erlaubten Origins hinzu.
Erzeugen Sie einen API-Schlüssel, wenn der Sicherheitsmodus API ist.
Halten Sie die Assistenten-ID bereit.

Snippet

<div id="seekdown-assistant-root"></div>

<!-- Include the public Seekdown runtime -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- Initialize the assistant with your assistantId and accessToken -->
<script>
  document.addEventListener('DOMContentLoaded', function () {
    if (window.skdwn?.startAssistant) {
      let seekdownAssistantOptions = {
        assistantId: 'your-assistant-id',
        accessToken: 'your-api-key-or-identity-access-token',
      };

      skdwn.startAssistant(seekdownAssistantOptions);
    } else {
      console.error('skdwn.startAssistant is not available.');
    }
  });
</script>

Das Zugriffstoken ist optional

Geben Sie accessToken nur an, wenn der Sicherheitsmodus API (ein Assistenten-Schlüssel) oder OIDC (das JWT Ihres Anbieters) ist. Ein Assistent im Modus None kann allein mit assistantId starten.

Wo Sie das Snippet platzieren

Platzieren Sie das Runtime-<script> und den Container-<div> direkt vor dem schließenden </body>-Tag, damit die Seite geladen ist, bevor der Assistent startet.
Der Container <div id="seekdown-assistant-root"></div> muss auf der Seite vorhanden sein – der Assistent wird darin eingehängt.
Wenn Ihre Website eine strikte Content-Security-Policy durchsetzt, erlauben Sie das Skript und die Verbindung zu saas.seekdown.ai, sonst lädt die Runtime nicht.

Das kommentierte Einbettungs-Snippet – das Runtime-Skript, der Container seekdown-assistant-root und der Initialisierungsaufruf.

Initialisierungsoptionen

startAssistant(options) erwartet ein Optionsobjekt. Nur wenige Optionen sind erforderlich – mit den übrigen legen Sie fest, für wen der Assistent da ist und wie er aussieht:

Option	Erforderlich	Wofür sie dient
`assistantId`	Ja	Welcher Assistent geladen wird.
`container`	Nein	Wo das Widget eingehängt wird – ein CSS-Selektor oder ein DOM-Element. So können mehrere Assistenten auf einer Seite leben, jeder in seinem eigenen Container. Standard ist das Element mit der ID `seekdown-assistant-root`. Siehe Mehrere Assistenten auf einer Seite.
`accessToken`	Für API / OIDC	Der Assistenten-Schlüssel (Modus API) oder das JWT Ihres Anbieters (OIDC). Lassen Sie es bei einem Assistenten im Modus None weg.
`serviceURL`	Automatisch	Die URL des Seekdown-Dienstes. Standard ist `https://saas.seekdown.ai`, Sie lassen sie also normalerweise weg.
`userId`	Nein	Eine stabile Identität für den Besucher. Wenn Sie keine festlegen, erzeugt Seekdown eine UUID und speichert sie im Browser – so behält ein wiederkehrender Besucher sein Gespräch und zählt als ein eindeutiger Nutzer. Legen Sie sie fest, um den Besucher mit Ihrer eigenen Konto-ID zu verknüpfen.
`userInformation`	Nein	Ein flacher Satz von Schlüssel-Wert-Strings über den Besucher (z. B. `email`, `plan`, `locale`). Sie werden als Eigenschaften `user.*` mit den Analysen übertragen, sodass Sie die Nutzung segmentieren können.
`additionalContext`	Nein	Ein String mit zusätzlichem Kontext, der dem Prompt des Assistenten hinzugefügt und seinen Templates zur Laufzeit bereitgestellt wird – zum Beispiel eine kurze Zeile, die den angemeldeten Nutzer oder die aktuelle Seite beschreibt.
`config`	Nein	Lokale Überschreibungen, die tief in die Remote-Konfiguration des Assistenten eingemischt werden – Theme, Layout, die schwebende Schaltfläche, sogar Template-Überschreibungen. So können Sie denselben Assistenten auf verschiedenen Websites mit unterschiedlichem Aussehen einbetten.
`baseURL`	Nein	Basis-URL für statische Assets des Assistenten; selten nötig.
`isDebug`	Nein	Bei `true` wird der Template-Zustand in der Konsole protokolliert – nützlich beim Entwickeln von Template-Überschreibungen.

Pro Besucher personalisieren

Mit userId, userInformation und additionalContext wirkt der Assistent kontobewusst – übergeben Sie zum Beispiel den Plan des angemeldeten Nutzers, damit die Templates ihn begrüßen oder Antworten anpassen können, ohne etwas Geheimes in der Seite preiszugeben.

Lebenszyklus-Events

startAssistant(options, events?) akzeptiert ein optionales zweites Argument, mit dem Sie sich in den Lebenszyklus einklinken können:

onStarted() – wird ausgelöst, sobald der Assistent eingehängt ist und (falls aktiviert) das vorherige Gespräch wiederhergestellt hat. Nutzen Sie es, um einen Ladeindikator auszublenden oder „Assistent bereit“ zu tracken.
onError(error, info) – wird ausgelöst, wenn die Initialisierung fehlschlägt; info.componentStack liefert Kontext. Nutzen Sie es, um einen Fallback anzuzeigen oder es erneut zu versuchen.

<script>
  skdwn.startAssistant(
    {
      assistantId: 'your-assistant-id',
      accessToken: 'your-api-key',
      userId: 'customer-42',
      userInformation: { plan: 'pro', locale: 'en-US' },
      additionalContext: 'Signed-in user is on the Pro plan at Acme.',
      config: { settings: { baseTheme: 'dark' } },
    },
    {
      onStarted: function () { console.log('Assistant ready'); },
      onError: function (err, info) { console.error(err, info.componentStack); },
    }
  );
</script>

Mehrere Assistenten auf einer Seite

Sie können mehrere Assistenten gleichzeitig auf derselben Seite betreiben – zum Beispiel ein Suchfeld im Header und einen Support-Chat als schwebende Schaltfläche. Die Regel ist einfach: Laden Sie die Runtime einmal, geben Sie jedem Assistenten seinen eigenen Container, und rufen Sie startAssistant einmal pro Assistent mit einem container auf. Das Starten eines Assistenten beendet nie die anderen.

<!-- Load the runtime once -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- One container (with a unique id) per assistant -->
<div id="assistant-search"></div>
<div id="assistant-support"></div>

<script>
  const base = { accessToken: 'your-api-key', serviceURL: 'https://saas.seekdown.ai' };

  // Header search assistant
  skdwn.startAssistant({
    ...base,
    assistantId: 'as-search',
    container: '#assistant-search',
    config: { settings: { baseTemplate: 'overlay' } },
  });

  // Floating support chat
  skdwn.startAssistant({
    ...base,
    assistantId: 'as-support',
    container: '#assistant-support',
    config: { settings: { floatingActionButton: { useFloatingActionButton: true } } },
  });
</script>

Jede Instanz ist vollständig isoliert – eigene Verbindung, Konfiguration, Templates und eigener Zustand –, sodass sie sich eine assistantId teilen oder verschiedene verwenden können, ohne sich gegenseitig zu stören.

Einen bestimmten Assistenten ansprechen. Die Runtime stellt eine kleine API unter window.skdwn bereit:

Eigenschaft / Methode	Rückgabe
`skdwn.instances`	Ein Array aller aktiven Assistenten auf der Seite.
`skdwn.instance`	Der kontextbezogene Assistent – derjenige, dessen Oberfläche das aktuelle Event ausgelöst hat oder gerade rendert. Darauf lösen Template-Handler (`onclick="skdwn.instance.helpers.…"`) auf, sodass jedes Widget immer sich selbst steuert.
`skdwn.instanceFor(target)`	Der Assistent, der in einem bestimmten Container (Selektor oder Element) eingehängt ist, oder `undefined`. Nutzen Sie ihn, um ein bestimmtes Widget aus Ihrem eigenen Seitencode zu steuern.

// Open the support chat from your own button
const support = window.skdwn.instanceFor('#assistant-support');
window.skdwn.instance = support;                 // point the context at it
support.helpers.toggleShowFloatingWindow(true);  // helpers act on the current context

Ein paar praktische Hinweise

- Das Runtime-<script> wird einmal geladen – es stellt das einzige Objekt window.skdwn bereit. - Container-IDs müssen eindeutig sein; lassen Sie container weg, um den Standard #seekdown-assistant-root zu verwenden. - Starts werden in eine Warteschlange gestellt (ein Container kann nicht zweimal gleichzeitig eingehängt werden), aber das Starten eines zweiten Assistenten beendet den ersten nicht. - Einen Assistenten neu zu starten heißt, startAssistant erneut mit demselben container aufzurufen – nur dieser wird neu gestartet.

Das Ergebnis prüfen

Öffnen Sie die Seite und prüfen Sie, ob der Assistent erscheint und antwortet.

Fehlerbehebung

Wenn das Widget fehlt, prüfen Sie die Skript-URL, den Container und die Browserkonsole.
Wenn der Zugriff blockiert wird, prüfen Sie die erlaubten Origins und das Token.