:::note Getrennte Versionen Das veröffentlichte npm-SDK ist 0.1.4. Der aktuelle Quellcode des gehosteten Loaders ist widget.js v16; die bereitgestellte Version kann davon abweichen und muss überprüft werden. Die nachfolgend erwähnten v15-Verhaltensweisen beziehen sich auf die historisch dokumentierte Version des gehosteten Loaders. :::

Mit einem KI-Coding-Assistenten integrieren

Die empfohlene Integration für Anwendungscode ist das @openstaticfish/chattybox-npm-Paket. Anwendungscode kann damit den öffentlichen Schlüssel und die API-URL konfigurieren, das gepflegte schwebende ChattyBox-Widget aus einem persistenten Browser-Layout laden oder den Headless-Client für eine vollständig eigene Benutzeroberfläche verwenden.

Das eigenständige Skript widget.js wird am Ende als No-Build-Fallback für Websites dokumentiert, die keine npm-Pakete installieren können.

Vor dem Start

Schließen Sie die Einrichtung des Chatbots ab, bevor Sie einen Assistenten bitten, Ihre Anwendung zu bearbeiten:

• Überprüfen Sie repräsentative Antworten und Quellenangaben unter Chatbot testen.
• Prüfen oder erstellen Sie unter Installieren → Schlüssel und Domains einen öffentlichen Browserschlüssel und kontrollieren Sie seine Origin-Einstellungen. Ein für eine Website vorbereiteter Schlüssel kann bereits auf diese Origin beschränkt sein; Schlüssel ohne Einschränkungen funktionieren von allen Origins aus. Einschränkungen sind eine optionale zusätzliche Härtung, keine Besucherauthentifizierung.
• Wählen Sie unter Installieren → Installation auf der Website einen passenden Schlüssel aus und kopieren Sie den Ausschnitt. Verwenden Sie dessen data-api-url, falls vorhanden; andernfalls ermitteln Sie vor der Integration den korrekten HTTP-Endpunkt der Widget-API aus Ihrer Deployment-Konfiguration.
• Entscheiden Sie, ob ein dauerhaftes schwebendes Widget zur Anwendung passt oder ob Sie eine eigene UI mit routenspezifischer Platzierung und Teardown benötigen.

Der öffentliche Widget-Schlüssel und die API-URL sind für den Browser bestimmt. Umgebungsspezifische Werte sollten Sie dennoch nicht committen. Geben Sie niemals ein Konfigurations-Deployment-Token (es ist geheim), Admin-Zugangsdaten oder eine nicht zugehörige Umgebungsdatei weiter.

Empfohlen: Gepflegte Benutzeroberfläche über npm einbinden

Dies ist der Standard-Prompt für React, Next.js, Vite und andere browserbasierte Anwendungen, die Pakete verwenden.

Anweisung

ChattyBox-npm-Paket integrieren

Integriere ChattyBox in diese Anwendung mit dem npm-Paket @openstaticfish/chattybox.

Öffentliche Browser-Konfiguration:
- API-Schlüssel: [PASTE PUBLIC WIDGET KEY]
- API-URL: [PASTE WIDGET API URL]

Untersuche zuerst Framework, Routing-Modell, Paketmanager, Konventionen für Umgebungsvariablen und das dauerhafte Anwendungslayout. Teile mir vor der Bearbeitung mit, welche Dateien du ändern möchtest. Frage nach, wenn unklar ist, auf welchen Routen ChattyBox erscheinen soll.

Anforderungen:
1. Installiere @openstaticfish/chattybox mit dem Paketmanager, der bereits in diesem Repository verwendet wird.
2. Speichere den öffentlichen API-Schlüssel und die API-URL nach der Konvention des Frameworks für browserseitig verfügbare Umgebungsvariablen. Füge Platzhalternamen zu einer Beispiel-Umgebungsdatei hinzu, aber committe keine echten Werte.
3. Importiere Chattybox aus @openstaticfish/chattybox und erstelle einen Client mit apiKey und baseUrl.
4. Rufe client.mountWidget() nur im Browser und erst nach document.body aus einer persistenten Anwendungshülle auf. Das schwebende Widget wird unter document.body eingefügt, nicht in die Komponente.
5. Behalte den Loader bei zulässigen SPA-Navigationen bei. SDK `0.1.4` zählt Referenzen nur bei identischen Mount-Optionen; rufe `remove()` bei einem beabsichtigten Teardown für jedes zurückgegebene Handle auf. Beim dokumentierten gehosteten Loader v15 entfernt das letzte Handle die zugehörige UI und deren Styles und bricht laufende Initialisierung, Wiederholungsversuche und Chats ab; `window.ChattyBox.destroy()` ist das entsprechende API des gehosteten Loaders. Prüfe Routenwechsel und Consent-Änderungen: Lade das Widget nicht vor dem erforderlichen Consent oder auf sensiblen bzw. privaten Routen und entferne es bei Routenausschluss oder Consent-Widerruf. Prüfe, ob der bereitgestellte Loader Teardown unterstützt: Die UI auszublenden oder nur das Script-Element zu entfernen reicht nicht. Ein bereits vom Server verarbeiteter Request lässt sich durch Cleanup nicht rückgängig machen.
6. Binde widget.js nicht manuell ein, erstelle keinen Backend-Proxy und führe keinen zweiten Loader ein. mountWidget weist einen abweichenden Schlüssel, eine andere API-URL, Script-URL, Locale oder Debug-Option zurück, bis alle vorhandenen Handles entfernt wurden; alte Optionen werden niemals stillschweigend beibehalten.
7. Bewahre vorhandene Navigation, Rendering-Grenzen, Lokalisierung, Analytics, Einwilligung und Styling. Die Locale-Option des SDK richtet sich nach der projektweiten Richtlinie für Script-Overrides; SDK `0.1.4` bietet weder eine reaktive Locale-Update-API noch ein `ready`-Promise. Der aktuelle Quellcode des gehosteten Widgets v16 kann produktspezifische Labels aktualisieren, wenn sich die aufgelöste Locale ändert, und beachtet dabei die Locale-Richtlinie des Projekts; prüfe die bereitgestellte Loader-Version, bevor du dich darauf verlässt, denn dieses Verhalten wird unabhängig versioniert. Der dokumentierte gehostete Loader v15 plant höchstens 10 Chatversuche innerhalb eines 30-Sekunden-Wiederholungsfensters ein; das ist keine feste maximale Laufzeit für einen bereits laufenden Request. Das Headless-`sendMessage()` wiederholt nicht automatisch. SDK `0.1.4` validiert `baseUrl` und kapselt Fehler beim Lesen des Antwort-Bodys.
8. Nimm die kleinste fokussierte Änderung vor und deploye sie nicht.
9. Führe Build, Lint, Type-Check und die relevanten Tests des Repositorys aus.
10. Berichte geänderte Dateien, zu setzende Umgebungsvariablen, den Einbindungsort der Benutzeroberfläche und wie sie auf der bereitgestellten Website getestet wird.

Der folgende Code veranschaulicht einen Browser-Lifecycle-Callback und ist kein Aufruf auf Modulebene für Server Rendering. Rufe ihn erst auf, wenn document.body existiert, und behalte das Handle für beabsichtigten Teardown:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowser() {
  return client.mountWidget();
}

// Handle für zulässige Navigation und beabsichtigten Teardown behalten.

Eine eigene Benutzeroberfläche erstellen

Wählen Sie dies, wenn Ihre Anwendung Nachrichtenliste, Eingabe, Ladezustände, Fehler, Quellenangaben und Position selbst verwalten soll, anstatt die gepflegte Benutzeroberfläche einzubinden.

Anweisung

Eine Headless-ChattyBox-Oberfläche erstellen

Erstelle eine benutzerdefinierte Chatbot-Oberfläche mit dem npm-Paket @openstaticfish/chattybox und seinem Headless-Client.

Öffentliche Browser-Konfiguration:
- API-Schlüssel: [PASTE PUBLIC WIDGET KEY]
- API-URL: [PASTE WIDGET API URL]

Untersuche zuerst Framework, Komponentensystem, Zustandsmuster, Styling, Barrierefreiheitskonventionen und Testkonfiguration der Anwendung. Schlage vor der Bearbeitung die Komponentengrenzen und Dateien vor.

Anforderungen:
1. Installiere @openstaticfish/chattybox mit dem vorhandenen Paketmanager des Repositorys.
2. Konfiguriere einen Chattybox-Client mit apiKey und baseUrl über browserseitig verfügbare Umgebungsvariablen; committe keine echten Werte.
3. Verwende sendMessage() und speichere conversationId im Besucher- oder Sitzungszustand, um Nachrichten zu gruppieren; setze sie bei einem Benutzer- oder Sitzungswechsel zurück. Teile sie niemals zwischen voneinander unabhängigen Besuchern. Das Modell erhält bis zu 12 aktuelle gespeicherte Nachrichten mit jeweils höchstens 2.000 Zeichen, nicht das vollständige Transkript oder ein dauerhaftes Gedächtnis. Ein öffentlicher Schlüssel, Origin-Einschränkungen und Conversation-IDs authentifizieren keine Besucher und schützen keine privaten Unterhaltungen. Vermeide sensible Informationen: Nachrichten können gespeichert werden und für Projektinhaber sichtbar sein. Das Löschen des lokalen Zustands entfernt keine Serverdatensätze.
4. Rendere Antworten sicher als Text oder bereinigtes Markdown und HTTP(S)-Quellen als barrierefreie Links; bewahre dabei ihre Reihenfolge. Füge niemals nicht vertrauenswürdiges rohes HTML oder Links mit unsicheren Schemas ein.
5. Implementiere Zustände für ausstehend, leer, Fehler und Wiederholung. Fallback-Antworten können keine Quellen haben; es gibt kein allgemeines Feld `wasAnswered`. Wenn das Backend `providerError` liefert, behandle es als optionales Feld und grenze seinen Typ vor der Verwendung sicher ein; zeige einen allgemeinen Provider-Fehler statt einer normalen Antwort und wiederhole eine abgeschlossene Anfrage mit Idempotenzschlüssel nicht blind. Das veröffentlichte SDK `0.1.4` typisiert aktuelle Response-Felder möglicherweise nicht; behandle sie als fehlend möglich. Behandle sowohl `ChattyboxError` als auch nicht umschlossene Netzwerkfehler; `code` ist optional.
6. Weise leere Nachrichten oder Nachrichten mit mehr als 2.000 Zeichen nach dem Entfernen führender und nachgestellter Leerzeichen zurück, verhindere doppelte Übermittlungen und achte auf gute Tastatur- und Screenreader-Bedienbarkeit. Headless sendMessage() wiederholt nicht automatisch: Verwende pro logischer Nachricht einen eindeutigen idempotencyKey und sende bei Wiederholungen exakt dieselbe Eingabe erneut; wiederhole nicht blind jeden 409-Fehler. SDK `0.1.4` wiederholt getWidgetConfig() nur einmal nach HTTP 400; der dokumentierte gehostete Loader v15 wiederholt separat seine Start-GETs.
7. Binde die Oberfläche nur in den von mir angegebenen Routen oder dem angegebenen Layout ein.
8. Verwende vorhandene Komponenten und Styles, statt ein neues Designsystem hinzuzufügen.
9. Lade widget.js nicht und rufe mountWidget() nicht auf.
10. Führe Build, Lint, Type-Check und die relevanten Tests aus und berichte anschließend geänderte Dateien und einen Prüfplan.

Hinweise zu Frameworks

Geben Sie dem Assistenten bei Bedarf einen zusätzlichen Satz:

• Next.js App Router: „Verwende eine kleine Client Component in einem persistenten Layout und rufe mountWidget() in einem nur im Browser ausgeführten Effekt auf, nicht während des Renderns.“
• React SPA: „Mount aus der persistenten App-Shell. Wenn die Komponente das letzte Handle von SDK 0.1.4 besitzt, gib remove() für einen beabsichtigten Teardown zurück; andernfalls behalte den gemeinsam genutzten Loader bei zulässigen Routenwechseln bei.“
• Docusaurus: „Initialisiere in src/theme/Root im Browser und behalte den Loader während zulässiger Doku-Navigation bei. Prüfe die bereitgestellte Version des gehosteten Loaders und dessen Locale-Verhalten, bevor du dich auf clientseitige Sprachupdates verlässt; Änderungen der Dashboard-Konfiguration erfordern weiterhin eine Neuinitialisierung.“
• Vue, Nuxt, Svelte oder ein anderes Framework: „Verwende den client-only Mount-Lifecycle in einem persistenten Layout; wähle eine Headless-Oberfläche, wenn ein entsprechender Teardown erforderlich ist.“

Eine vorhandene SDK-Integration prüfen

Anweisung

Meine ChattyBox-SDK-Integration prüfen

Prüfe diese ChattyBox-Integration, ohne sie zu deployen oder nicht zugehörigen Code zu ändern.

Prüfe, ob:
1. @openstaticfish/chattybox installiert und importiert wird, statt sein Verhalten zu duplizieren.
2. Ein Chattybox-Client den vorgesehenen öffentlichen API-Schlüssel und die API-URL erhält.
3. Browser-Umgebungsvariablen den Regeln dieses Frameworks für öffentliche Variablen folgen, ohne private Zugangsdaten offenzulegen.
4. Ein gehostetes Widget eine persistente Shell nutzt und `remove()` nur für beabsichtigten UI-Teardown, Routenausschlüsse nach SPA-Navigation oder den Widerruf von Consent verwendet. Eine eigene UI muss ein echtes Component-Cleanup haben.
5. Clientseitige Navigation und erneute Mounts in der Entwicklung keine doppelten Instanzen erzeugen.
6. Vorhandene Rendering-Grenzen, Lokalisierung, Analytics, Einwilligung, Barrierefreiheit und Layout erhalten bleiben. Origin-Einschränkungen sind optional und keine Besucherauthentifizierung; eingeschränkte Schlüssel benötigen eine erlaubte Request-Origin, und Node-fetch sendet Browser-Header nicht automatisch. Prüfe, dass private Routen und der Widerruf von Consent ein initialisiertes Widget tatsächlich entfernen, statt es nur auszublenden.
7. Die Implementierung geeignete Tests und kein unabhängiges Refactoring enthält.

Gib die Ergebnisse nach Schweregrad mit Dateipfaden und Zeilenverweisen zurück. Schlage nur die kleinsten sicheren Korrekturen vor und nenne die genauen Prüf-Befehle.

Kein npm oder Build-Schritt?

Verwenden Sie den widget.js-Installationsleitfaden nur, wenn die Website das npm-Paket nicht verwenden kann – etwa bei einfachem HTML, einem benutzerdefinierten Codefeld eines CMS oder Google Tag Manager.

Anweisung

Fallback-Widget-Skript installieren

Installiere das gehostete ChattyBox-Widget auf dieser Website mit dem exakten Skript, das in meiner ChattyBox-Ansicht Installation auf der Website erzeugt wurde:

[PASTE COMPLETE WIDGET SCRIPT]

Untersuche die Website zuerst und ermittle die sicherste Einfügestelle auf öffentlichen Seiten. Lade das unveränderte Skript genau einmal und nur bei erteiltem erforderlichem Consent; schließe private/Admin-/Checkout-Routen aus. Entferne bei SPA-Routenwechseln oder Consent-Widerruf ein bereits initialisiertes Widget gezielt, bevor ein ausgeschlossener Zustand eintritt, und initialisiere es nur dann erneut, wenn es zulässig ist. Prüfe, ob der bereitgestellte Loader Teardown unterstützt: Die UI auszublenden oder nur das Script-Element zu entfernen reicht nicht, und Teardown kann bereits verarbeitete Requests nicht rückgängig machen. Bewahre das CSP-Verhalten, lege keine privaten Zugangsdaten offen, deploye die Änderung nicht und berichte den geänderten Ort sowie einen Browser-Testplan.

Ergebnis testen

1. Prüfen Sie den Diff und bestätigen Sie, dass keine echten Zugangsdaten committet wurden.
2. Führen Sie den normalen Build, Lint, Type-Check und die Tests des Projekts aus.
3. Deployen Sie über den normalen Prüfprozess.
4. Überprüfen Sie die vorgesehenen Routen in einem privaten Browserfenster, einschließlich clientseitiger Navigation.
5. Stellen Sie eine unterstützte Frage, folgen Sie einer Quellenangabe und testen Sie das Fallback-Verhalten.
6. Prüfen Sie das mobile Layout, die Tastaturbedienung und die Browserkonsole.

Fahren Sie mit der SDK-Referenz und der Start-Checkliste fort.