Installationsleitfäden

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 und beschränken Sie seine zulässigen Ursprünge. Kehren Sie zu Embed zurück, wählen Sie diesen Schlüssel aus, schließen Sie die Anpassung des gehosteten Widgets ab 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	Erzwingt die Sprache der Widget-Oberfläche auf einer bestimmten Seite.

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 alle für Ihr Projekt konfigurierten Einschränkungen zulässiger Ursprünge.
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 zulässige Ursprünge bleiben Projektanmeldedaten und keine Werte der Konfigurationsdatei.

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 anhand der Sprache der aktuellen Seite oder verlassen Sie sich auf den Wert von <html lang> der Seite.

Lassen Sie den Loader in Ihrer dauerhaften Anwendungsshell. Erstellen oder entfernen Sie ihn während normaler clientseitiger Routenwechsel nicht neu.

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.

Öffnen Sie Ihren GTM-Container.
Erstellen Sie ein neues Tag vom Typ Custom HTML.
Fügen Sie das ChattyBox-Snippet ein.
Verwenden Sie einen Trigger All Pages oder einen engeren Trigger nur für Seiten, auf denen das Widget angezeigt werden soll.
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

ChattyBox benötigt kein WordPress-Plugin. 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 in einen globalen Footer-Bereich 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>

Fügen Sie das Widget nicht zu wp-admin-, Checkout-, Konto- oder privaten Mitgliederseiten hinzu, es sei denn, diese Seiten sind absichtlich öffentlich und werden unterstützt.

Ü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-/Ursprungsfehler.

Vor der Installation​

Was in das Skript gehört​

Einfaches HTML​

Next.js / React-App-Shell​

Docusaurus​

Benutzerdefinierte Oberfläche​

Allgemeines CMS/benutzerdefiniertes HTML​

Google Tag Manager​

WordPress​

Überprüfung​

Privacy choices