Zum Hauptinhalt springen

Drupal-Chatbot-Modul

Verwenden Sie das offizielle ChattyBox-Drupal-Modul für eine Composer-verwaltete Installation auf einer Drupal-10- oder Drupal-11-Website. Das lokal geprüfte ChattyBox-Drupal-Modul in Version 0.1.0 fügt seinen gehosteten Widget-Loader bei geeigneten nichtadministrativen Anfragen mit dem Drupal-Anfrageformat HTML hinzu. Es verwendet einen fest codierten API-Endpunkt. Diese Anleitung behandelt die operative Einrichtung. Die Seite zum Drupal-KI-Chatbot-Modul stellt das Produkt und den Ablauf zur Bewertung vor.

Vor der Installation​

Schließen Sie zuerst den Ablauf Erste Schritte ab: Verbinden Sie Ihre öffentliche Drupal-URL, überprüfen Sie indexierte Seiten und verifizieren Sie repräsentative Antworten unter Chatbot testen. Prüfen Sie unter Installieren → Schlüssel und Domains einen bestehenden öffentlichen Widget-Schlüssel oder erstellen Sie einen; prüfen Sie in beiden Fällen dessen Origin-Einstellungen. Wählen Sie unter Installieren → Installation auf der Website einen passenden Schlüssel aus und kopieren Sie dessen data-api-key-Wert aus dem Installations-Snippet.

Composer-Installation​

Diese Installation verwendet das öffentliche GitHub-Repository als Composer-VCS-Quelle. Fügen Sie vor composer require den folgenden Repository-Eintrag hinzu und prüfen Sie vor der Installation die aktuelle Paketverfügbarkeit und die Tags.

Fügen Sie das öffentliche GitHub-Repository zur composer.json-Datei im Stammverzeichnis des verwendenden Drupal-Projekts hinzu:

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

Wenn das Projekt bereits einen Abschnitt repositories besitzt, führen Sie den Eintrag chattybox-drupal dort zusammen. Installieren Sie anschließend das markierte Modul:

composer require openstaticfish/chattybox-drupal:^0.1

Das Paket ist als drupal-module deklariert und benötigt Drupal ^10 || ^11; das Modul selbst deklariert PHP 8.1 als Mindestversion, Ihre Drupal-Version kann jedoch eine neuere PHP-Version erfordern. Standardmäßige Drupal-Composer-Installationspfade legen es häufig unter web/modules/contrib/ ab, projektbezogene Pfadzuordnungen können aber abweichen. ^0.1 ist eine Versionsbeschränkung und keine exakte Festlegung: Composer löst eine Version auf und speichert sie in der Lock-Datei. Verwenden Sie eine exakte Version, wenn Reproduzierbarkeit erforderlich ist.

Prüfen Sie vor einem Upgrade den öffentlichen Quellcode des Drupal-Moduls und die getaggten Änderungen; klären Sie, welcher Aktualisierungsweg für Ihre Installation verfügbar ist.

Um stattdessen den aktuellen Entwicklungs-Branch zu testen:

composer require openstaticfish/chattybox-drupal:dev-main

Aktivieren und konfigurieren​

  1. Aktivieren Sie ChattyBox unter Extend oder führen Sie drush en chattybox aus.
  2. Öffnen Sie Configuration > Web services > ChattyBox.
  3. Fügen Sie nur den öffentlichen Widget-API-Schlüssel aus dem Website-Installations-Snippet ein.
  4. Belassen Sie die URL des gehosteten Widget-Skripts, sofern ChattyBox Ihnen keine Vorschau- oder selbst gehostete Loader-URL bereitgestellt hat.
  5. Lassen Sie die Sprachüberschreibung leer, damit die Sprachrichtlinie des Projekts gilt, oder geben Sie einen unterstützten kleingeschriebenen Code wie en, fr oder de ein. Eine unterstützte Überschreibung hat nur Vorrang, wenn das Projekt Script-Überschreibungen erlaubt. Laut dem aktuell geprüften Quellcode des gehosteten Widgets v16 werden im automatischen Modus nacheinander Seitensprache, Browsersprachen und die konfigurierte Standardsprache versucht; nicht unterstützte Werte werden übersprungen, anschließend wird auf Englisch zurückgegriffen. Im festen Modus wird die unterstützte Projekt-Standardsprache verwendet, andernfalls Englisch. Prüfen Sie den bereitgestellten Loader, bevor Sie sich auf dieses separat versionierte Verhalten verlassen.
  6. Aktivieren Sie den Chatbot und speichern Sie die Konfiguration.

Das geprüfte Modul bindet den Widget-Loader bei Admin-Routen oder Anfragen, deren Drupal-Anfrageformat nicht HTML ist, nicht ein; es prüft weder den Content-Type der endgültigen Antwort noch, ob Frontend-Inhalte privat sind. Wenn der Hook das Laden zulässt, hängt es die deklarierte Drupal-Bibliothek für den Loader ein und stellt über drupalSettings den öffentlichen Schlüssel, den fest codierten Endpunkt und die optionale Sprache bereit.

Bei Neuinstallationen ist das Modul deaktiviert; Schlüssel und Sprachüberschreibung sind leer. Das Einstellungsformular befindet sich unter /admin/config/services/chattybox und erfordert die Berechtigung administer chattybox configuration. Das Modul lädt das Widget, crawlt oder synchronisiert aber keine Drupal-Inhalte.

Der API-Endpunkt ist in der geprüften Modulversion fest codiert; er wird weder aus dem Schlüssel ermittelt noch automatisch aktualisiert. Eine Änderung der Loader-URL ändert diesen Endpunkt nicht. Vergleichen Sie ihn mit dem Website-Installations-Snippet. Verwendet dieses Snippet eine andere API-Bereitstellung, nutzen Sie deren manuelle Widget-Integration ohne das Modul. Entfernte Script-URLs müssen HTTPS verwenden (HTTP ist nur für lokale Entwicklungs-Hosts zulässig).

Schlüssel ohne Einschränkungen funktionieren von allen Browser-Origins aus; ein für eine Website vorbereiteter Schlüssel kann bereits auf deren Origin beschränkt sein. Für optionale Einschränkungen unter Installieren → Schlüssel und Domains müssen Sie jedes vorgesehene Schema, jeden Hostnamen und jeden Port angeben. Bei einer fehlenden oder nicht erlaubten effektiven Origin liefert ein eingeschränkter Schlüssel 401 Invalid API key; die Origin stammt aus Origin oder, falls dieser Header fehlt, aus der Origin von Referer. Origin-Einschränkungen sind eine zusätzliche Absicherung, keine Besucherauthentifizierung.

Weitere Routen ausschließen​

Das Modul überspringt Admin-Routen automatisch. Ein benutzerdefiniertes Modul kann das Widget auf weiteren öffentlichen Routen mit hook_chattybox_load_widget_alter() deaktivieren:

Prüfungen auf Admin-Routen schützen nicht die Vertraulichkeit sämtlicher Frontend-Inhalte. Schließen Sie bei Bedarf Checkout-, Konto- und Mitgliedschaftsrouten aus; der folgende Routenname dient nur als Beispiel. Das Modul ergänzt für die Entscheidung des Hooks weder Cache-Kontexte noch Cache-Tags. Implementieren und prüfen Sie für jede Bedingung eine anwendungsspezifische Cache-Variation und -Invalidierung – sowohl für Fälle mit als auch ohne angehängte Assets und über Drupal- sowie zwischengeschaltete Caches hinweg. Ein Ausschluss ist keine Zugriffskontrolle.

/**
 * Implements hook_chattybox_load_widget_alter().
 */
function mymodule_chattybox_load_widget_alter(&$should_load, $config, $route_match) {
  if ('commerce_checkout.form' === $route_match->getRouteName()) {
    $should_load = FALSE;
  }
}

Manueller Fallback​

Composer ist der empfohlene Installationsweg. Wenn Ihr Drupal-Deployment Composer nicht verwenden kann, kopieren Sie das Modul nach web/modules/custom/chattybox oder in ein anderes Verzeichnis für benutzerdefinierte Module, aktivieren Sie es und konfigurieren Sie es unter Configuration > Web services > ChattyBox.

Geben Sie keine ChattyBox-Verwaltungszugangsdaten im Modul ein. Der öffentliche Widget-API-Schlüssel ist für Frontend-Markup vorgesehen.

Verwenden Sie nur einen Loader: Aktivieren Sie das Modul nicht gleichzeitig mit einem Theme-Snippet, GTM-Tag oder SDK-Mount. Das geprüfte Modul fügt sein Script nicht ein, wenn es ein beliebiges markiertes Element script[data-chattybox-widget="true"] findet. Es prüft oder konfiguriert dieses Script nicht neu und erkennt keine unmarkierten Scripts.

Der automatische Loader des Moduls prüft vor der Initialisierung keine Einwilligung. Wenn vor Anfragen eine Einwilligung erforderlich ist, verwenden Sie statt dieses automatischen Loaders eine einwilligungsfähige Integration. Verhindern Sie bei SPA-Routenwechseln oder Widerruf der Einwilligung das Laden auf ausgeschlossenen Routen und bauen Sie ein initialisiertes Widget aktiv über eine vom bereitgestellten Loader unterstützte Integration ab; bloßes Ausblenden oder Entfernen des Script-Tags reicht nicht. Initialisieren Sie es nur dann erneut, wenn dies zulässig ist. Ein Abbau kann bereits vom Server verarbeitete Anfragen nicht rückgängig machen.

Überprüfung​

Nach der Konfiguration des Moduls:

  • Öffnen Sie eine öffentliche Drupal-Seite in einem Inkognito-Fenster.
  • Bestätigen Sie, dass der Widget-Launcher einmal erscheint.
  • Stellen Sie eine echte Besucherfrage.
  • Prüfen Sie, dass eine unterstützte Antwort indexierte öffentliche Drupal-Seiten zitiert und eine nicht unterstützte Frage den Fallback zeigt, der keine Quellen haben kann.
  • Prüfen Sie in der Browserkonsole, ob data-api-key oder data-api-url fehlen oder Schlüssel-Fehler auftreten.
  • Testen Sie ein- und ausgeschlossene Routen mit kalten und warmen Drupal-, Seiten- und CDN-Caches. Bauen Sie relevante Caches nach Änderungen an Einstellungen oder Hooks neu auf. Ein serverseitiger Routenausschluss baut ein bereits bei der clientseitigen Navigation geladenes Widget nicht ab.

Arbeiten Sie die Launch-Checkliste ab, bevor Sie den Chatbot ankündigen.