Zum Hauptinhalt springen

Integration in eine Webseite

Der Website-Messenger von Apptiva Klar lässt sich einfach und schnell auf jeder Webseite einbinden. Die Integration erfolgt über ein Script-Tag und erfordert keine komplexen Setup-Schritte.

Zwei Integrationsvarianten für die Anzeige​

Grundsätzlich gibt es zwei Arten, wie der Chat auf einer Webseite angezeigt und geöffnet werden kann:

  1. Standard-Variante mit FAB (Floating Action Button): Der Messenger blendet unten auf der Webseite ein Chat-Icon ein. Klickt der Benutzer auf diesen Button, öffnet sich das Chatfenster.

  2. Gesteuerte Variante durch die Webseite: Die Webseite übernimmt selbst die Steuerung, wann das Chatfenster angezeigt wird. So kann z. B. ein eigenes Eingabefeld wie "Frage unsere KI ..." verwendet werden. Sendet der Benutzer das Formular ab, kann die Webseite das Chatfenster öffnen und die eingegebene Frage direkt an den Chatbot übergeben.

Für diese zweite Variante nutzt der Webseitenersteller die JavaScript API von Apptiva Klar. Typischerweise wird der FAB dabei mit data-fab-visible="false" ausgeblendet und der Chat über API-Aufrufe gesteuert.

Script-Tag Integration​

Die Integration des Chatbots erfolgt durch das Einbinden eines Script-Tags im HTML-Code deiner Webseite:

<script
  id="chatbot"
  data-server="https://my-chatbot.klar.apptiva.ch"
  data-expand-at-start="all"
  data-link-handling="default"
  defer
  src="https://my-chatbot.klar.apptiva.ch/webclient/embed/bundle.js"
></script>

Seitenkontext für die Wissenssuche​

Der Website Messenger übermittelt die URL, den Titel und, sofern vorhanden, die Beschreibung der aktuellen Seite als Kontext. Agenten und Tools können diese Seiteninformationen innerhalb der Sitzung nutzen, zum Beispiel um eine Anfrage der passenden Seite zuzuordnen. Auch die Wissenssuche kann damit gezielter nach passenden Inhalten suchen. Die Seiteninformationen sind keine Wissensquelle und gelten nicht als Beleg für die Antwort.

Wichtiger Sicherheitshinweis​

Damit die Integration funktioniert, muss die Domain deiner Webseite in der Server-seitigen Konfiguration unter allowedEmbedOrigins hinterlegt sein. Kontaktiere dein Apptiva Klar Team, um deine Domain freizuschalten.

Konfigurationsattribute​

data-server (erforderlich)​

Die vollständige URL zum Chatbot-Server.

Beispiel:

data-server="https://my-chatbot.klar.apptiva.ch"

Query-Parameter​

Beim data-server können Query-Parameter angegeben werden, um dem Chatbot bei der Integration zusätzliche Informationen mitzuteilen:

data-server="https://my-chatbot.klar.apptiva.ch?systemId=123&userRole=editor"

Hinweis: Die Query-Parameter userId und sessionId sind nicht erlaubt und werden ignoriert.

data-expand-at-start (optional)​

Steuert, ob das Chatfenster beim Laden der Seite automatisch geöffnet werden soll. Die Option berücksichtigt dabei das verwendete Endgerät.

Mögliche Werte:

  • "all" - Das Chatfenster wird auf allen Geräten automatisch geöffnet
  • "desktop" - Das Chatfenster wird nur auf Desktop-Geräten (≥ 768px Bildschirmbreite) automatisch geöffnet
  • "mobile" - Das Chatfenster wird nur auf mobilen Geräten (< 768px Bildschirmbreite) automatisch geöffnet
  • nicht gesetzt (Standard) - Das Chatfenster bleibt geschlossen

Beispiel:

data-expand-at-start="desktop"

Wichtig: Das Chatfenster wird nur automatisch geöffnet, wenn der Benutzer es nicht zuvor explizit geschlossen hat. Der Fensterstatus wird in einem Cookie (apptiva-klar-chat-window-state) für 8 Stunden gespeichert.

data-fab-visible (optional)​

Steuert, ob der FAB (Floating Action Button) angezeigt wird.

Mögliche Werte:

  • "true" (Standard) - Der FAB wird angezeigt
  • "false" - Der FAB wird ausgeblendet

Wenn der FAB ausgeblendet ist, bleibt der Messenger weiterhin vollständig funktionsfähig und kann über die JavaScript API gesteuert werden (z. B. mit openChatWindow()).

Beispiel:

data-fab-visible="false"

Steuert, wie Links im Chatbot geöffnet werden.

Mögliche Werte:

  • "default" (Standard) - Links der gleichen Domain werden im selben Tab geöffnet, Links einer anderen Domain in einem neuen Tab
  • "existing-tab" - Alle Links werden im selben Tab geöffnet
  • "new-tab" - Alle Links werden in einem neuen Tab geöffnet

Beispiel:

data-link-handling="new-tab"

Design-Anpassung​

Das Aussehen des Website-Messengers kann individuell angepasst werden, um perfekt zur Corporate Identity deiner Webseite zu passen. Alle Informationen zu CSS-Anpassungen, Farben, Logos und weiteren Design-Optionen findest du im Kapitel Design-Anpassung.

JavaScript API​

Die detaillierte Beschreibung der verfügbaren Funktionen und Events findest du im Kapitel Website Messenger API.

Vollständiges Integrationsbeispiel​

<!DOCTYPE html>
<html lang="de">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Meine Webseite mit Chatbot</title>
  </head>
  <body>
    <h1>Willkommen auf meiner Webseite</h1>

    <!-- Chatbot Integration -->
    <script
      id="chatbot"
      data-server="https://my-chatbot.klar.apptiva.ch"
      data-expand-at-start="desktop"
      data-link-handling="default"
      defer
      src="https://my-chatbot.klar.apptiva.ch/webclient/embed/bundle.js"
    ></script>

    <!-- Optional: JavaScript API verwenden -->
    <script>
      // Warten bis der Chatbot geladen ist
      window.addEventListener("load", function () {
        // Event-Handler registrieren
        if (typeof chatbot !== "undefined") {
          chatbot.subscribe("ON_CHAT_WINDOW_STATE_CHANGE", function (open) {
            console.log("Chat ist jetzt " + (open ? "offen" : "geschlossen"));
          });
        }
      });

      // Chatbot via Button öffnen
      function openChat() {
        if (typeof chatbot !== "undefined") {
          chatbot.openChatWindow();
        }
      }
    </script>

    <!-- Optional: Custom Button zum Öffnen des Chats -->
    <button onclick="openChat()">Chat mit uns!</button>
  </body>
</html>

Troubleshooting​

Der Chatbot wird nicht angezeigt​

  • Überprüfe, ob die Domain deiner Webseite in allowedEmbedOrigins konfiguriert ist
  • Kontrolliere die Browser-Konsole auf Fehlermeldungen
  • Stelle sicher, dass das Script-Tag das Attribut defer enthält

Das Chatfenster öffnet sich nicht automatisch​

  • Prüfe, ob der Benutzer das Chatfenster zuvor manuell geschlossen hat (Cookie-Speicherung)
  • Überprüfe das Attribut data-expand-at-start
  • Lösche testweise die Cookies der Webseite

JavaScript API funktioniert nicht​

  • Stelle sicher, dass der Chatbot vollständig geladen ist, bevor du API-Funktionen aufrufst
  • Verwende chatbot.isChatbotLoaded() um zu prüfen, ob die API verfügbar ist
  • Überprüfe die Browser-Konsole auf JavaScript-Fehler