Einbettung des Docs-Agenten

Überblick

Der Docs-Agent ist ein spezialisiertes, KI-gestütztes Widget, das speziell für Dokumentationsseiten entwickelt wurde. Es bietet Ihren Benutzern sofortige Hilfe, indem es Fragen zu Ihrer Dokumentation über einen interaktiven Dialog im Vollbild beantwortet.

Grundlegende Einrichtung

Der Einstieg in das Docs-Agenten-Widget ist einfach. Befolgen Sie einfach diese zwei Schritte:

Wenn Ihre Dokumentseite den Agenten in einem iframe lädt, stellen Sie sicher, dass die Ursprungsseite der Hostseite in den allowed_origins Ihrer OAuth-Anwendung enthalten ist. Der Token-Endpunkt des Widgets validiert diesen Ursprung, bevor ein Token ausgegeben wird.

Schritt 1: Fügen Sie das Skript hinzu

Fügen Sie das docs-widget.js-Skript mit der erforderlichen Konfiguration zu Ihrer HTML-Seite hinzu. Wenn Sie mehrere Docs-Widgets laden, geben Sie jedem Skript eine eindeutige data-instance-id:

<script  src="https://widget.companin.tech/docs-widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="docs-help"  data-locale="en"  async></script>

Schritt 2: Fügen Sie eine Trigger-Schaltfläche hinzu

Erstellen Sie eine Schaltfläche oder ein Element, das die open()-Methode des Widgets aufruft:

<button id="help-btn" type="button">Ask Documentation Agent</button><script>  const handleOpen = (event) => {    console.log('Docs widget opened', event?.context);  };  // Generic event API (returns unsubscribe function)  const unsubscribeOpen = window.CompaninDocsWidget?.on?.('open', handleOpen);  document.getElementById('help-btn')?.addEventListener('click', () => {    window.CompaninDocsWidget?.open();  });  // Cleanup on page unload or SPA route change  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeOpen === 'function') unsubscribeOpen();  });</script>

Unterste Suchleiste

Out of the box hat das Dokumenten-Widget keinen sichtbaren Launcher – es öffnet sich nur, wenn Ihre Seite die API aufruft. Geben Sie stattdessen eine Suchleiste hinzu: ein kompaktes Feld, das am unteren Rand jeder Seite angeheftet ist und das das vollständige Panel öffnet, wenn ein Besucher darauf klickt oder mit dem Tippen beginnt. Alles, was bereits eingegeben wurde, wird in das Suchfeld des Panels übernommen.

Aktivieren Sie es in Ihrem Dashboard unter Widget → Inhalt → Textfeld für die Suche. Der Text wird pro Sprache gespeichert, sodass jede Locale ihre eigene Formulierung erhält und die Besucher die Leiste in ihrer eigenen Sprache sehen.

Widget → Verhaltenskontrollen, wann es angezeigt wird:

• Verzögerung — Millisekunden, bevor die Leiste erscheint. 0 zeigt sie sofort an.
• Automatisch ausblenden nach — Millisekunden, bis die Leiste sich selbst ausblendet. 0 hält sie, bis der Besucher sie schließt.

Die Leiste versteckt sich, während das Panel geöffnet ist, und erscheint wieder, wenn der Besucher es schließt, sodass es immer auch als Rückweg dient. Das Schließen mit dem × entfernt sie nur für diese Seitenansicht; sie erscheint beim nächsten Seitenladen wieder.

Beispiele

Hier sind einige praktische Beispiele, wie Sie den Docs-Agenten integrieren können:

Beispiel 1: Grundlegende HTML-Integration

<!DOCTYPE html><html lang="en"><head>  <meta charset="UTF-8">  <meta name="viewport" content="width=device-width, initial-scale=1.0">  <title>My Documentation</title></head><body>  <header>    <h1>Product Documentation</h1>    <button onclick="window.CompaninDocsWidget.open()">      Need Help?    </button>  </header>  <main>    <!-- Your documentation content -->  </main>  <script    src="https://widget.companin.tech/docs-widget.js"    data-widget-key="your-widget-key"    data-locale="en">  </script></body></html>

Beispiel 2: Benutzerdefinierte Schaltfläche mit Ereignis-Listener

Für mehr Kontrolle können Sie Ereignis-Listener zu Ihren vorhandenen Schaltflächen hinzufügen:

// Wait for the widget to loadwindow.addEventListener('load', () => {  const unsubscribeResponse = window.CompaninDocsWidget?.on?.('response', (event) => {    console.log('Agent response:', event?.data);  });  document.getElementById('help-btn').addEventListener('click', () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  });  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeResponse === 'function') unsubscribeResponse();  });});

Beispiel 3: React/Next.js-Integration

In einer React- oder Next.js-Anwendung:

import React from 'react';export default function Documentation() {  const openDocsAgent = () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  };  return (    <div>      <h1>API Documentation</h1>      <button        onClick={openDocsAgent}        className="help-button"      >        Ask Customer Support AI Agent      </button>    </div>  );}

Konfigurationsoptionen

Das Docs Agent-Widget akzeptiert mehrere Konfigurationsparameter. Verwenden Sie data-instance-id für deterministische pro-Instanz-Kontrolle, wenn Sie mehrere Widgets auf einer Seite einbetten:

Erforderliche Parameter

• data-widget-key: Die Widget-ID Ihres Docs-Widgets — der einzige Wert, den die meisten Installationen benötigen. Sie löst Ihren Client, Agenten und die Konfiguration serverseitig auf.

Erweiterte Alternative zu <code>data-widget-key</code> — übergeben Sie diese drei explizit nur für Multi-Instanz-Setups:

• data-client-id: Ihre eindeutige Client-ID aus dem Companin-Dashboard
• data-agent-id: Die ID des Agenten, den Sie verwenden möchten
• data-config-id: Konfigurations-ID zur Anpassung des Widgets

Optionale Parameter

• data-locale: Sprache-Code (Standard: 'en'). Unterstützt: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Setzen Sie auf 'true' für den Entwicklungsmodus (verbindet mit localhost:3001)

JavaScript-API

Sobald das Widget geladen ist, stellt es eine globale API für die programmgesteuerte Steuerung zur Verfügung. Bei Multi-Widget-Setups sollten Sie Instanz-Registrierungen (CompaninDocsWidgets.get(instanceId)) bevorzugen, anstatt nur die neueste globale Referenz zu verwenden:

open()

window.CompaninDocsWidget.open();

Öffnet den Docs Agent-Dialog im Vollbildmodus.

close()

window.CompaninDocsWidget.close();

Schließt den Docs Agent-Dialog und blendet das Widget aus.

Benutzerdefinierte Gestaltung

Sie können Ihre Auslöser-Schaltflächen nach Belieben gestalten. Hier ist ein Beispiel für eine schwebende Hilfeschaltfläche:

.my-help-button {  position: fixed;  bottom: 20px;  right: 20px;  padding: 12px 24px;  background: #2563eb;  color: white;  border: none;  border-radius: 8px;  font-weight: 600;  cursor: pointer;  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);  transition: all 0.2s;}.my-help-button:hover {  background: #1d4ed8;  transform: translateY(-2px);  box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);}

Best Practices

• Platzieren Sie die Auslöser-Schaltfläche an einem auffälligen, leicht zugänglichen Ort (z. B. Kopfzeile, schwebende Schaltfläche)
• Verwenden Sie klare, handlungsorientierte Schaltflächentexte wie 'Fragen Sie AI' oder 'Brauchen Sie Hilfe?'
• Stellen Sie sicher, dass das Widget-Skript geladen wird, bevor Sie versuchen, seine API-Methoden aufzurufen
• Halten Sie Ihre Client-Anmeldeinformationen sicher - geben Sie sie niemals im Client-seitigen Code preis

Fehlerbehebung

Widget wird nicht geladen?

Stellen Sie sicher, dass das Skript geladen ist, bevor Sie die API aufrufen. Sie können überprüfen, ob das Widget verfügbar ist:

window.addEventListener('load', () => {  console.log('Widget loaded:', !!window.CompaninDocsWidget);});

Dialog öffnet sich nicht?

Überprüfen Sie, ob Sie einen gültigen data-widget-key (oder für das explizite Formular die client-id, agent-id und config-id) angegeben haben und dass dieser korrekt ist. Wenn mehrere Widgets vorhanden sind, stellen Sie sicher, dass jedes Skript eine eindeutige data-instance-id hat.