Installationsleitfäden

:::note Versionsstatus Das veröffentlichte npm-SDK 0.1.4 mit widget.js v15 unterstützt Teardown über remove() oder window.ChattyBox.destroy() und bricht ausstehende Arbeit ab. :::

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 scrapen Sie die Quelle, überprüfen Sie indexierte Seiten und verifizieren Sie repräsentative Antworten in Test Chat.

Erstellen Sie anschließend unter Public Keys einen browsersicheren Schlüssel. Er funktioniert standardmäßig in Produktion, in Vorschau/Staging und auf localhost. Für eine optionale zusätzliche Absicherung wählen Sie Edit origins, aktivieren Sie Restrict this key to specific origins und fügen Sie die exakt zulässigen Ursprünge hinzu. Wenn aktiviert, werden Schema, Hostname und Port abgeglichen: https://example.com, https://preview.example.com und http://localhost:3000 sind separate Einträge. Kehren Sie zu Embed zurück, wählen Sie den Schlüssel aus und kopieren Sie das generierte Snippet. Es enthält den öffentlichen Schlüssel und die 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 eine UI-Sprache bei Initialisierung an, nur wenn Script-Overrides im Projekt erlaubt sind.

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.
• Erstellen und Löschen öffentlicher Schlüssel sowie optionale Einschränkungen zulässiger Origins pro Schlüssel. Öffnen Sie Public Keys > Edit origins, um eine Einschränkung zu aktivieren und Produktions-, Staging-, Vorschau- oder localhost-Ursprünge hinzuzufügen oder zu entfernen.
• Scraping, erneutes Scraping, Test-Chat, Analytics und Inhaltslücken.

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. Öffentliche Schlüssel und optionale Einschränkungen zulässiger Origins bleiben Projekteinstellungen und keine Werte der Konfigurationsdatei.

Die API-URL darf die HTTP-Deployment-Root oder /chat sein; Loader und SDK normalisieren nur diesen Suffix, nicht eine Convex-.cloud-URL zu .site. Installieren Sie nur einen Loader. Im veröffentlichten SDK 0.1.4 teilen nur identische Mounts das Script; jedes Handle ist eine Referenz, und erst das letzte remove() signalisiert widget.js v15 den vollständigen Teardown von UI, Styles, Font-Links, ausstehender Initialisierung, Wiederholungen, Chat, Script und globaler API. Abweichende Optionen werden abgelehnt, solange Handles bestehen. Das Widget lädt Konfiguration und Übersetzungen einmal und verfolgt keine Dashboard- oder Seitensprachänderungen.

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"
          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 Loader nur bei erlaubtem Override oder verwenden Sie Auto-Modus und <html lang>. Im festen Modus gilt die Projekt-Default-Locale, außer ein Override ist erlaubt; clientseitige Routenwechsel lösen keine Locale-Neuberechnung aus.

Lassen Sie den Loader in Ihrer dauerhaften Anwendungsshell. Erstellen oder entfernen Sie ihn während normaler clientseitiger Routenwechsel nicht neu: Script-Entfernung ist kein UI-Teardown oder Consent-Widerruf.

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.

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.

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 dem Projekt-Tab Embed ein und aktivieren Sie den Chatbot. Der Produktions-API-Endpunkt wird automatisch konfiguriert. 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, dass die Antwort Quellenangaben enthält.
• Prüfen Sie die Browserkonsole auf fehlendes data-api-key, fehlendes data-api-url oder Schlüssel-Fehler. Prüfen Sie Origins nur, wenn Sie für den Schlüssel ausdrücklich eine Einschränkung aktiviert haben.