Schnellstart

Widget-Überblick

Die Widget-App wird unter widget.companin.tech gehostet und bietet eine einfache Möglichkeit, einen Customer Support AI Agent in Ihre Website einzubetten. Um loszulegen, müssen Sie einen Agenten und eine OAuth-Anwendung erstellen.

Das Widget ist eine leichte, eigenständige Anwendung, die in einem isolierten iframe auf Ihrer Website ausgeführt wird. Diese Architektur stellt sicher, dass das Widget nicht mit Ihrem vorhandenen CSS oder JavaScript in Konflikt gerät und gleichzeitig hervorragende Leistung und Sicherheit bietet.

1. Erstellen Sie einen Agenten

Zuerst erstellen Sie einen Customer Support AI Agent in Ihrem Dashboard:

Ihr Agent ist das KI-Gehirn hinter dem Widget. Er verarbeitet Benutzeranfragen, hält den Gesprächskontext aufrecht und generiert intelligente Antworten. Jeder Agent kann mit spezifischen Anweisungen, Persönlichkeitsmerkmalen und Wissensdatenbanken angepasst werden, um Ihrem Anwendungsfall zu entsprechen.

1. Gehen Sie zu Ihrem Dashboard und navigieren Sie zur Seite "Datenquellen"
2. Klicken Sie auf die Schaltfläche "Hinzufügen" im Abschnitt Agenten
3. Füllen Sie die Agentendetails aus (Name, Beschreibung, Ton usw.)
4. Speichern Sie den Agenten und notieren Sie sich seine ID

Tipp: Geben Sie Ihrem Agenten klare, spezifische Anweisungen zu seiner Rolle und seinen Einschränkungen. Zum Beispiel: "Sie sind ein hilfreicher Kundenservice-Agent für ein SaaS-Produkt. Sie können Fragen zu Funktionen, Preisen und Kontoverwaltung beantworten. Bei technischen Problemen leiten Sie die Benutzer an, ein Support-Ticket zu erstellen."

2. Erstellen Sie eine OAuth-Anwendung

Erstellen Sie eine OAuth-Anwendung zur Authentifizierung Ihres Widgets:

1. Gehen Sie zur Seite "OAuth" in Ihrem Dashboard
2. Klicken Sie auf "Anwendung erstellen"
3. Füllen Sie den Anwendungsnamen und die Beschreibung aus
4. Kopieren Sie die client_id aus der erstellten Anwendung

3. Betten Sie das Widget über Iframe ein

Der einfachste Weg, das Widget zu integrieren, besteht darin, es direkt mit einem Iframe einzubetten. Diese Methode erfordert keine JavaScript-Initialisierung und funktioniert sofort. Bei mehreren Iframes auf einer Seite sollten Sie jede Einbettung auf ihren eigenen Container und Parameter beschränken.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

Ersetzen Sie YOUR_WIDGET_KEY durch den Installationsschlüssel Ihres Widgets (den wgt_—-Wert — kopieren Sie ihn von der Widget-Seite oder der Installationsseite im Dashboard). Der locale-Parameter kann so eingestellt werden, dass er der Sprache Ihrer Website entspricht.

Erweitert: JavaScript-Initialisierung

Die empfohlene Integrationsmethode ist die Verwendung unseres JavaScript-Widget-Laders, der automatische Größenanpassung, Konfigurationsmanagement und reaktionsschnelles Verhalten bietet.

Skriptintegration

Fügen Sie das folgende Skript-Tag zu Ihrer HTML-Seite hinzu:

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

Skriptattribute

Jedes Attribut hat einen bestimmten Zweck bei der Konfiguration Ihres Widgets:

• data-widget-key: Die Widget-ID Ihres Widgets - Der einzelne Wert, den die meisten Installationen benötigen. Es löst Ihren Client, Agenten und die Konfiguration serverseitig auf, sodass Sie sie nicht separat einfügen müssen.

Die drei untenstehenden Attribute sind eine erweiterte Alternative zu data-widget-key - verwenden Sie sie für Multi-Instanz-Setups, bei denen Sie einen bestimmten Client, Agenten oder eine Konfiguration gezielt ansprechen müssen:

• data-client-id: Ihre OAuth-Client-ID - Dies authentifiziert Ihre Anwendung mit unserer API. Denken Sie daran, dass es das Passwort Ihrer App ist.
• data-agent-id: Die UUID Ihres Agenten - Dies identifiziert, welcher Kundenservice-KI-Agent die Gespräche führt.
• data-config-id: Die UUID Ihrer Widget-Konfiguration - Dies bestimmt, wie Ihr Widget aussieht und sich verhält (Farben, Größe, Position usw.).
• data-instance-id: Einzigartig pro Widget-Instanz-ID - Erforderlich, wenn mehrere Widgets auf derselben Seite eingebettet werden, um Kollisionen zu vermeiden und eine gezielte API-Anforderung pro Instanz zu ermöglichen.
• data-custom-css: Veraltet. Das Setzen dieses Attributs protokolliert eine Konsolenwarnung und hat keine Auswirkungen. Setzen Sie custom_css stattdessen in Ihrer Widget-Konfiguration im Dashboard - es wird aus der Konfiguration geladen und automatisch in das iframe eingefügt.
• data-locale: Sprachcode (z.B. "en", "es", "fr") - Legt die Anzeigesprache des Widgets fest. Der Agent wird weiterhin in jeder Sprache antworten, in der die Benutzer schreiben.
• data-theme: Themenmodus - light, dark oder system (folgt dem Gerät des Besuchers). Wählt, welche Farbpalette (im Dashboard konfiguriert) das Widget anzeigt. Lassen Sie es weg, um Ihr gespeichertes Standarddesign zu verwenden.
• data-dev: Auf "true" setzen für den Entwicklungsmodus (localhost) - Verwenden Sie dies beim Testen lokal. Entfernen oder auf "false" setzen für die Produktion.

Das Widget wird automatisch:

• Die Konfiguration von der Konfigurations-ID abrufen
• Sich selbst gemäß den Widget-Dimensionen in der Konfiguration anpassen
• Die zusammengeklappte Schaltfläche basierend auf den Konfigurationseinstellungen positionieren
• Offen oder geschlossen starten, basierend auf der Einstellung start_open der Konfiguration.

Hinweise

• Das Widget verwaltet automatisch seine eigene Größe basierend auf Ihren Konfigurationseinstellungen
• Die Position des zusammengeklappten Buttons kann über die Widget-Konfiguration angepasst werden
• Das Widget respektiert die start_open Einstellung aus Ihrer Konfiguration
• Alle Stile (Farben, Schriftarten, Abmessungen) werden über die Widget-Konfiguration gesteuert
• Das Widget verwendet die postMessage-Kommunikation für responsives Verhalten
• Der Entwicklungsmodus kann mit data-dev="true" für Tests auf localhost aktiviert werden
• Für den serverseitigen Token-Austausch verwenden Sie /api/v1/auth/widget-token und halten Sie das Client-Geheimnis nur auf Ihrem Server.
• Stellen Sie sicher, dass Ihr Host-Ursprung (zum Beispiel http://localhost:3000) in den OAuth-allowed_origins enthalten ist, wenn Sie das Widget in einem iframe einbetten.