Docs Assistant Einbettung

Erfahren Sie, wie Sie das Docs Assistant Widget auf Ihren Dokumentationsseiten einbetten.

Übersicht

Der Docs Assistant 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 mit einem Vollbild-Interaktionsdialog beantwortet.

Jetzt ausprobieren!

Klicken Sie auf die Schaltfläche unten, um den Docs Assistant auf dieser Seite in Aktion zu sehen.

Grundlegende Einrichtung

Die ersten Schritte mit dem Docs Assistant Widget sind einfach. Folgen Sie einfach diesen zwei Schritten:

Wenn Ihre Dokumentenseite den Assistenten in einem Iframe lädt, stellen Sie sicher, dass der Ursprung der Hostseite in den „allowed_origins“ Ihrer OAuth-Anwendung enthalten ist. Der Widget-Token-Endpunkt validiert diesen Ursprung, bevor er ein Token ausgibt.

Schritt 1: Skript hinzufügen

Fügen Sie das Skript docs-widget.js 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-client-id="YOUR_CLIENT_ID" data-assistant-id="YOUR_ASSISTANT_ID" data-config-id="YOUR_CONFIG_ID" data-instance-id="docs-help" data-locale="en"></script>

Schritt 2: Auslöse-Schaltfläche hinzufügen

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

<button id="help-btn" type="button">Ask Documentation Assistant</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>

Beispiele

Hier sind einige praktische Beispiele für die Integration des Docs Assistant:

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-client-id="your-client-id"    data-assistant-id="your-assistant-id"    data-config-id="your-config-id"    data-locale="en">  </script></body></html>

Beispiel 2: Benutzerdefinierte Schaltfläche mit Event Listener

Für mehr Kontrolle können Sie Event 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('Assistant 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 openDocsAssistant = () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  };  return (    <div>      <h1>API Documentation</h1>      <button        onClick={openDocsAssistant}        className="help-button"      >        Ask Customer Support AI Assistant      </button>    </div>  );}

Konfigurationsoptionen

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

Erforderliche Parameter

data-client-id: Ihre eindeutige Client-Kennung aus dem Companin Dashboard
data-assistant-id: Die ID des Assistenten, den Sie verwenden möchten
data-config-id: Konfigurations-ID für Widget-Anpassung

Optionale Parameter

data-locale: Sprachcode (Standard: 'en'). Unterstützt: en, de, es, fr, it, nb, nl, pt, sv
data-dev: Auf 'true' setzen für Entwicklungsmodus (verbindet zu localhost:3001)

JavaScript-API

Nach dem Laden stellt das Widget eine globale API für die programmgesteuerte Steuerung bereit. Bei Multi-Widget-Setups sollten Sie Instanz-Registries (CompaninDocsWidgets.get(instanceId)) bevorzugen, statt nur die zuletzt initialisierte globale Referenz zu verwenden:

open()

window.CompaninDocsWidget.open();

Öffnet den Docs Assistant Dialog im Vollbildmodus.

close()

window.CompaninDocsWidget.close();

Schließt den Docs Assistant Dialog und versteckt das Widget.

Benutzerdefinierte Styling

Sie können Ihre Auslöse-Schaltflächen beliebig stylen. Hier ist ein Beispiel für eine schwebende Hilfe-Schaltflä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);}

Bewährte Praktiken

Platzieren Sie die Auslöse-Schaltfläche an einem prominenten, leicht zugänglichen Ort (z.B. Header, schwebende Schaltfläche)
Verwenden Sie klare, aktionsorientierte Schaltflächentexte wie 'KI fragen' oder 'Brauchen Sie Hilfe?'
Stellen Sie sicher, dass das Widget-Skript geladen ist, bevor Sie versuchen, seine API-Methoden aufzurufen
Halten Sie Ihre Client-Anmeldedaten sicher - exponieren Sie sie niemals in clientseitigem Code

Fehlerbehebung

Widget lädt nicht?

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?

Stellen Sie sicher, dass alle erforderlichen Parameter (client-id, assistant-id, config-id) korrekt angegeben sind. Wenn mehrere Widgets vorhanden sind, muss jedes Skript eine eindeutige data-instance-id haben.

← Zurück Weiter: Übersicht →