Installationsleitfäden

:::note Versionsstatus Das veröffentlichte npm-SDK 0.1.4 ermöglicht das Entfernen seiner Mounts mit remove(). Nach der Initialisierung des gehosteten Widgets widget.js v15 kann es auch mit window.ChattyBox.destroy() zerstört werden. :::

Die gehostete widget.js-Integration ist der Weg ohne Build-Schritt, wenn ChattyBox die Oberfläche und den Transport verwalten soll. Wenn Ihre App dieselbe Oberfläche aus npm-Code initialisieren soll, verwenden Sie mountWidget(). Wenn Sie die Oberfläche selbst verwalten möchten, verwenden Sie das Headless-SDK.

Vor der Installation

Schließen Sie zuerst den Ablauf Erste Schritte ab: Konfigurieren und importieren Sie die Quelle, prüfen Sie indexierte Seiten und verifizieren Sie repräsentative Antworten unter Chatbot testen.

Bereiten Sie unter Installieren eine Installation für Ihre Website vor oder verwalten Sie unter Schlüssel und Domains einen browsersicheren Schlüssel. Prüfen Sie die Origins des Schlüssels: Ein für eine Website-Domain vorbereiteter Schlüssel kann bereits auf diese Origin beschränkt sein; Schlüssel ohne Einschränkungen funktionieren über mehrere Origins hinweg. Unter Origins bearbeiten können Sie optionale Einschränkungen aktivieren und die benötigten Produktions-, Vorschau-, Staging- und localhost-Origins hinzufügen. Bei aktivierten Einschränkungen erfolgt der exakte Abgleich nach Schema, Hostname und Port: https://example.com, https://preview.example.com und http://localhost:3000 sind separate Einträge.

Geben Sie unter Installation auf der Website zuerst eine HTTP(S)-Website-URL ein. Die Auswahl zeigt nur nicht abgelaufene Schlüssel, die uneingeschränkt oder für die Origin dieser URL zugelassen sind. Geben Sie für einen eingeschränkten Schlüssel eine erlaubte Origin ein; unter Schlüssel und zulässige Domains verwalten können Sie seine Einschränkungen prüfen. Falls das Formular nicht verfügbar ist, schließen Sie zuerst den im Dashboard angezeigten Einrichtungsschritt ab. Wählen Sie einen passenden Schlüssel aus und kopieren Sie das generierte Snippet mit dem öffentlichen Schlüssel und der API-URL Ihres Projekts:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Für dokumentationsorientierte Plattformen finden Sie Anleitungen für MkDocs AI chatbot, VitePress AI chatbot und GitBook AI chatbot.

Ersetzen Sie YOUR_API_KEY durch den öffentlichen Widget-Schlüssel aus Ihrem Dashboard. Übernehmen Sie den Wert von data-api-url genau so, wie er im Dashboard angezeigt wird. In der Produktion ist dies eine stabile https://...convex.site/chat-URL für die öffentliche Widget-API.

Was in das Skript gehört

Verwenden Sie Skriptattribute für Werte, die verfügbar sein müssen, bevor das Widget starten kann:

Attribut	Erforderlich	Verwendung
src	Ja	Lädt das ChattyBox-Widget-JavaScript.
data-api-key	Ja	Identifiziert den öffentlichen Widget-Schlüssel Ihres Projekts.
data-api-url	Ja	Sendet Widget-Anfragen an die ChattyBox-API.
data-locale	Nein	Fordert bei der Initialisierung eine UI-Sprache an, nur wenn Script-Overrides im Projekt erlaubt sind.
data-chattybox-widget="true"	Nein	Ermöglicht dynamischen Loadern und dem SDK, ein vorhandenes Script zu finden; empfohlen für das Einfügen aus Anwendungscode.
data-debug="true"	Nein	Aktiviert Browserdiagnosen; standardmäßig deaktiviert.
data-color	Nein	Explizite Akzentfarben-Überschreibung nach erfolgreichem Abruf der Konfiguration; verwenden Sie einen sechsstelligen Hex-Farbwert. Dashboard-Einstellungen werden empfohlen.
data-position	Nein	Explizite Positionsüberschreibung nach erfolgreichem Abruf der Konfiguration: bottom-right, bottom-left, top-right oder top-left. Dashboard-Einstellungen werden empfohlen.

Verwenden Sie die Dashboard-Einstellungen für alles, was ohne erneute Bereitstellung Ihrer Website verwaltet werden soll:

• Widget-Farben, Position, Symbol, Titel und Willkommensnachricht.
• Standard-Sprachmodus und die Frage, ob Überschreibungen mit data-locale erlaubt sind.
• Öffentliche Schlüssel erstellen und löschen sowie optionale Origin-Einschränkungen pro Schlüssel. Öffnen Sie Schlüssel und Domains > Origins bearbeiten, um Einschränkungen zu aktivieren und Produktions-, Staging-, Vorschau- oder localhost-Origins hinzuzufügen oder zu entfernen.
• Inhaltsimport und -aktualisierung, Chatbot-Tests, Analysen und unbeantwortete Fragen.

Wenn Sie die Sperre für Konfiguration als Code aktivieren, stammen Assistent, Quelle, Laufzeit und unterstützte Widget-Einstellungen aus der bereitgestellten Konfiguration statt aus Dashboard-Formularen. Die Sperre ist irreversibel und blockiert auch manuelle Inhaltsaktionen. Öffentliche Schlüssel und optionale Origin-Einschränkungen bleiben separate Projekteinstellungen und sind keine Werte der Konfigurationsdatei.

Die API-URL kann die HTTP-Deployment-Root sein oder mit /chat enden; der Loader entfernt abschließende Schrägstriche und ein abschließendes /chat, um Endpunkte abzuleiten. Eine Convex-.cloud-URL wird nicht in .site umgewandelt. Fügen Sie keine Query-Strings oder Fragmente hinzu. Das SDK erkennt das oben genannte Marker-Attribut, aber nicht unbedingt jedes manuelle Script mit demselben src. Installieren Sie nur einen Loader. Das veröffentlichte npm-SDK 0.1.4 referenziert nur Mounts mit identischen Optionen gemeinsam und weist einen geänderten Schlüssel, Endpunkt, Script-URL, Locale- oder Debug-Wert zurück, solange noch Handles vorhanden sind. Das gehostete Widget übernimmt Dashboard-Konfigurationsänderungen nicht automatisch; initialisieren Sie es erneut, damit gespeicherte Einstellungen wirksam werden. Im aktuellen Quellstand des gehosteten Loaders widget.js v16 können sich produktseitige UI-Texte aktualisieren, wenn <html lang> oder data-locale die aufgelöste Locale ändert – gemäß der Locale-Richtlinie des Projekts. Prüfen Sie den bereitgestellten Loader, bevor Sie sich auf Client-Updates verlassen; dieses Verhalten betrifft den gehosteten Loader und nicht das veröffentlichte npm-SDK 0.1.4. Aktivierte Origin-Einschränkungen verwenden Origin oder ersatzweise den Referer-Origin; fehlende oder nicht erlaubte Origins führen zu 401 Invalid API key. Das ist keine Authentifizierung.

Einfaches HTML

Fügen Sie das Snippet einmal am Ende von body, direkt vor </body>, ein. Das funktioniert für statisches HTML, handcodierte Websites und Vorlagen mit einer globalen Fußzeile.

<!doctype html>
<html lang="en">
  <head>
    <title>Example Site</title>
  </head>
  <body>
    <main>
      <!-- Page content -->
    </main>

    <script
      src="https://chattybox.ai/widget.js"
      data-api-key="YOUR_API_KEY"
      data-api-url="YOUR_WIDGET_API_URL"
      async
    ></script>
  </body>
</html>

Next.js / React-App-Shell

Fügen Sie das Widget bei einer Next.js-App-Router-Website mit next/script in app/layout.tsx ein, damit es einmal für die gesamte App geladen wird.

import Script from "next/script";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://chattybox.ai/widget.js"
          data-api-key="YOUR_API_KEY"
          data-api-url="YOUR_WIDGET_API_URL"
          data-chattybox-widget="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Fügen Sie das Skript bei einer React-Single-Page-App einmal in die übergeordnete App-Shell oder HTML-Vorlage ein. Injizieren Sie es nicht aus jeder Routenkomponente.

import { useEffect } from "react";

export function ChattyBoxWidget() {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return null;
}

Docusaurus

Erstellen oder aktualisieren Sie bei Docusaurus src/theme/Root.tsx, damit das Widget auf allen Dokumentationsseiten verfügbar ist.

import React, { useEffect } from "react";

export default function Root({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Wenn Ihre Docusaurus-Website übersetzte Routen besitzt, setzen Sie data-locale vor dem Laden nur bei erlaubtem Override oder verwenden Sie den Automatikmodus und <html lang>. Im festen Modus gilt die Standard-Locale des Projekts, sofern kein erlaubtes Override gesetzt ist. Im aktuellen Quellstand des gehosteten Widgets widget.js v16 können sich produktseitige UI-Texte aktualisieren, wenn <html lang> oder data-locale die aufgelöste Locale ändert – abhängig von der Locale-Richtlinie des Projekts. Prüfen Sie den bereitgestellten Loader, bevor Sie sich auf dieses Verhalten verlassen; seine Version ist unabhängig von der Version des veröffentlichten npm-SDK 0.1.4. Selbst verfasste Titel und Begrüßungstexte sowie generierte Antworten werden nicht automatisch übersetzt.

Lassen Sie den Loader bei normalen Routenwechseln in Ihrer dauerhaften Anwendungsshell. Für einen absichtlichen Abbau oder Widerruf der Einwilligung entfernen Sie alle Mount-Handles des SDK 0.1.4: Das letzte passende Handle weist den gehosteten Loader widget.js v15 an, seine UI/Styles zu entfernen und Initialisierung, Wiederholungen (bis zu 10 Versuche innerhalb von 30 Sekunden) und laufende Chats abzubrechen. Nach der Initialisierung von v15 ist auch window.ChattyBox.destroy() verfügbar. Eine bereits serverseitig verarbeitete Anfrage lässt sich dadurch nicht rückgängig machen. Das gehostete Widget wird an document.body angehängt und nicht innerhalb der Komponente gerendert, die es lädt.

Benutzerdefinierte Oberfläche

Das gehostete Widget ist optional. Wenn Sie vollständige Kontrolle über Rendering, Nachrichtenstatus und Interaktionsdesign wünschen, verwenden Sie das JavaScript-SDK mit demselben öffentlichen Widget-API-Schlüssel und derselben Widget-API-URL.

Allgemeines CMS/benutzerdefiniertes HTML

Die meisten CMS-Plattformen verfügen über einen globalen Bereich für benutzerdefinierten Code, eine Fußzeile oder eine Theme-Vorlage. Fügen Sie das Skript dort ein, damit jede öffentliche Seite das Widget laden kann.

Verwenden Sie diesen Weg für Webflow, Framer, Squarespace, benutzerdefinierte Codebereiche von Wix, Shopify-Themes, HubSpot-Vorlagen und benutzerdefinierte CMS-Plattformen, bei denen Sie globales HTML bearbeiten können.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Bestätigen Sie vor der Veröffentlichung, dass das CMS data-api-key, data-api-url oder async nicht aus benutzerdefinierten Skripten entfernt.

Google Tag Manager

Verwenden Sie Google Tag Manager, wenn Ihr Team Drittanbieter-Skripte bereits über GTM verwaltet.

1. Öffnen Sie Ihren GTM-Container.
2. Erstellen Sie ein neues Tag vom Typ Custom HTML.
3. Fügen Sie das ChattyBox-Snippet ein.
4. Verwenden Sie einen Trigger All Pages oder einen engeren Trigger nur für Seiten, auf denen das Widget angezeigt werden soll.
5. Sehen Sie sich den Container in der Vorschau an, überprüfen Sie, ob das Widget geladen wird, und veröffentlichen Sie anschließend.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Wenn Ihre Website den Consent-Modus oder eine Tag-Consent-Richtlinie verwendet, stellen Sie sicher, dass das Widget auf den Seiten geladen werden darf, auf denen Besucher Hilfe benötigen.

Bei einer SPA verhindert ein enger gefasster GTM-Trigger das erstmalige Laden auf ausgeschlossenen Routen, entfernt aber kein Widget, das auf einer anderen Route bereits geladen wurde. Lösen Sie den Loader nicht bei jedem Wechsel des Navigationsverlaufs erneut aus.

Content-Security-Policy (CSP)

Erlauben Sie für den standardmäßigen gehosteten Loader https://chattybox.ai in script-src und den Ursprung der Widget-API in connect-src. Das Widget fügt ein Stylesheet und Inline-Style-Attribute ein; derzeit gibt es keine Nonce-Option. Eine Richtlinie, die Inline-Styles verbietet, blockiert daher Teile der Oberfläche. Wenn Ihre Richtlinie es zulässt, erlauben Sie für diese Styles 'unsafe-inline' oder verwenden Sie eine benutzerdefinierte, CSP-kompatible Oberfläche. Das Laden von Inter beim Öffnen des Launchers benötigt außerdem https://fonts.googleapis.com in style-src sowie https://fonts.gstatic.com in font-src. Erlauben Sie in img-src den Ursprung aller konfigurierten Icon-Bilder. Prüfen Sie Einwilligungs- und Sicherheitsanforderungen, bevor Sie die CSP lockern.

WordPress-Plugin-Anleitung

Für eine WordPress-Installation ohne Code verwenden Sie das ChattyBox-WordPress-Plugin. Folgen Sie der WordPress-Plugin-Anleitung, um es zu installieren, zu konfigurieren, Routen auszuschließen und zu überprüfen. Der Produktions-API-Endpunkt wird automatisch konfiguriert.

Das Plugin lädt das gehostete Widget bei öffentlichen Frontend-Anfragen, ohne Ihr Theme zu bearbeiten. Es wird absichtlich nicht in wp-admin, Feeds, REST-Anfragen oder AJAX-Anfragen geladen. Dies ist keine Datenschutz- oder Zugriffskontrolle für jede Frontend-Seite. Richten Sie bei Bedarf Ausschlüsse für Checkout-, Konto-, passwortgeschützte oder Mitgliederseiten über den Plugin-Filter ein und testen Sie sie; alternativ verwenden Sie eine gezielt begrenzte manuelle Installation. Die Einstellung der Loader-URL ändert nicht den integrierten Produktions-API-Endpunkt des Plugins; für eine andere API-Bereitstellung verwenden Sie das manuelle Snippet.

Wenn Sie eine manuelle Skriptinstallation bevorzugen, verwenden Sie einen der Skriptbereiche, die Ihre WordPress-Einrichtung bereits unterstützt:

• Theme-Einstellungen mit Header- oder Footer-Skripten.
• Ein Child-Theme, das die Footer-Vorlage steuert.
• Ein Plugin für Header-/Footer-Skripte.
• Google Tag Manager, wenn Ihre WordPress-Website ihn bereits verwendet.

Fügen Sie das Snippet an einer globalen Footer-Stelle ein, damit es auf veröffentlichten Seiten, Beiträgen, Dokumenten und Wissensdatenbankartikeln erscheint, auf denen der Chatbot verfügbar sein soll.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Vermeiden Sie das Hinzufügen des Widgets zu wp-admin-, Checkout-, Konto- oder privaten Mitgliederseiten, es sei denn, diese Seiten sind absichtlich öffentlich und werden unterstützt.

Drupal-Modul

Für Drupal 10 oder 11 ist Composer der empfohlene Installationsweg. Fügen Sie das öffentliche GitHub-VCS-Repository zur composer.json im Stammverzeichnis des verwendenden Drupal-Projekts hinzu:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Installieren und aktivieren Sie anschließend das markierte Modul:

composer require openstaticfish/chattybox-drupal:^0.1
drush en chattybox

Öffnen Sie Configuration > Web services > ChattyBox, fügen Sie den öffentlichen Widget-API-Schlüssel aus Installieren → Installation auf der Website ein und aktivieren Sie den Chatbot. Die lokal geprüfte Modulversion verwendet einen fest codierten API-Endpunkt: Vergleichen Sie ihn mit Ihrem Snippet und verwenden Sie für eine andere API-Bereitstellung die manuelle Integration. Das Modul ist standardmäßig deaktiviert. Es überspringt administrative und Nicht-HTML-Anfragen, aber nicht alle privaten Frontend-Inhalte. Eine Änderung der Script-URL ändert nicht den integrierten Produktions-API-Endpunkt. Weitere Informationen zu Routenausschlüssen und dem manuellen Fallback finden Sie in der Anleitung zum Drupal-Chatbot-Modul.

Überprüfung

Arbeiten Sie nach der Installation die Launch-Checkliste ab, bevor Sie den Chatbot ankündigen:

• Öffnen Sie eine öffentliche Seite in einem Inkognito-Fenster.
• Bestätigen Sie, dass der Widget-Launcher erscheint.
• Öffnen Sie das Widget und stellen Sie eine echte Kundenfrage.
• Prüfen Sie bei einer unterstützten Antwort die Quellenangaben und stellen Sie danach eine nicht unterstützte Frage, um das Fallback zu prüfen (es kann ohne Quellen sein).
• Prüfen Sie die Browserkonsole auf fehlendes data-api-key, fehlendes data-api-url oder Schlüssel-Fehler. Prüfen Sie, ob Origin-Einschränkungen für den Schlüssel aktiviert sind und ob die gewünschte Origin gegebenenfalls erlaubt ist.