Osadzanie agenta dokumentacji

Przegląd

Agent dokumentacji to specjalizowany widget zasilany AI, zaprojektowany specjalnie dla stron dokumentacji. Oferuje natychmiastową pomoc Twoim użytkownikom, odpowiadając na pytania dotyczące Twojej dokumentacji za pomocą interaktywnego dialogu na pełnym ekranie.

Podstawowa konfiguracja

Rozpoczęcie pracy z widgetem agenta dokumentacji jest proste. Wystarczy wykonać te dwa kroki:

Jeśli strona dokumentów ładuje agenta w iframe, upewnij się, że pochodzenie strony hosta jest uwzględnione w dozwolonych pochodzeniach aplikacji OAuth. Punkt końcowy tokena widżetu weryfikuje to pochodzenie przed wydaniem tokena.

Krok 1: Dodaj skrypt

Dodaj skrypt docs-widget.js do swojej strony HTML z wymaganą konfiguracją. Jeśli ładujesz wiele widgetów dokumentacji, nadaj każdemu skryptowi unikalny 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>

Krok 2: Dodaj przycisk wyzwalający

Utwórz przycisk lub element, który wywołuje metodę open() widgetu:

<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>

Dolny pasek wyszukiwania

Domyślnie widget dokumentacji nie ma widocznego uruchamiacza — otwiera się tylko wtedy, gdy Twoja strona wywołuje API. Zamiast tego daj mu pasek wyszukiwania: kompaktowe pole przypięte do dołu każdej strony, które otwiera pełny panel, gdy odwiedzający na nie kliknie lub zacznie pisać. Wszystko, co już zostało wpisane, jest przenoszone do pola wyszukiwania panelu.

Włącz to w swoim panelu sterowania w sekcji Widget → Treść → Tekst pola wyszukiwania. Tekst jest przechowywany per język, więc każda lokalizacja ma swoje własne sformułowanie, a odwiedzający widzą pasek w swoim własnym języku.

Widget → Kontrola zachowania, gdy się pojawia:

• Opóźnienie — milisekundy przed pojawieniem się paska. 0 pokazuje go natychmiast.
• Automatyczne ukrywanie po — milisekundach, aż pasek sam się ukryje. 0 utrzymuje go, aż odwiedzający go odrzuci.

Pasek chowa się, gdy panel jest otwarty, i wraca, gdy odwiedzający go zamyka, więc zawsze pełni funkcję powrotu. Odrzucenie go za pomocą × wycofuje go tylko dla tego widoku strony; wraca przy następnym załadowaniu strony.

Przykłady

Oto kilka praktycznych przykładów, jak zintegrować agenta dokumentacji:

Przykład 1: Podstawowa integracja HTML

<!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>

Przykład 2: Niestandardowy przycisk z nasłuchiwaczem zdarzeń

Dla większej kontroli możesz dodać nasłuchiwacze zdarzeń do swoich istniejących przycisków:

// 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();  });});

Przykład 3: Integracja React/Next.js

W aplikacji React lub Next.js:

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>  );}

Opcje konfiguracji

Widget Docs Agent akceptuje kilka parametrów konfiguracyjnych. Użyj data-instance-id do deterministycznej kontroli per-instance przy osadzaniu wielu widgetów na jednej stronie:

Wymagane parametry

• data-widget-key: ID widgetu Twoich dokumentów — pojedyncza wartość, której potrzebuje większość instalacji. Rozwiązuje Twojego klienta, agenta i konfigurację po stronie serwera.

Zaawansowana alternatywa dla <code>data-widget-key</code> — przekaż te trzy jawnie tylko dla konfiguracji wieloinstancyjnych:

• data-client-id: Twój unikalny identyfikator klienta z pulpitu nawigacyjnego Companin
• data-agent-id: ID agenta, którego chcesz użyć
• data-config-id: ID konfiguracji do dostosowywania widgetu

Opcjonalne parametry

• data-locale: Kod języka (domyślnie: 'en'). Obsługuje: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Ustaw na 'true' dla trybu dewelopera (łączy się z localhost:3001)

JavaScript API

Po załadowaniu widget udostępnia globalne API do programatycznej kontroli. W przypadku konfiguracji wielowidgetowych preferuj rejestry instancji (CompaninDocsWidgets.get(instanceId)) zamiast używać tylko najnowszego globalnego odniesienia:

open()

window.CompaninDocsWidget.open();

Otwiera okno dialogowe Docs Agent w trybie pełnoekranowym.

close()

window.CompaninDocsWidget.close();

Zamyka okno dialogowe Docs Agent i ukrywa widget.

Niestandardowe stylizowanie

Możesz stylizować swoje przyciski wyzwalające w dowolny sposób. Oto przykład pływającego przycisku pomocy:

.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);}

Najlepsze praktyki

• Umieść przycisk wyzwalający w widocznym, łatwo dostępnym miejscu (np. nagłówek, pływający przycisk)
• Użyj jasnego, zorientowanego na działanie tekstu przycisku, takiego jak 'Zapytaj AI' lub 'Potrzebujesz pomocy?'
• Upewnij się, że skrypt widgetu ładowany jest przed próbą wywołania jego metod API
• Zachowaj swoje dane uwierzytelniające klienta w bezpieczeństwie - nigdy nie ujawniaj ich w kodzie po stronie klienta

Rozwiązywanie problemów

Widget się nie ładuje?

Upewnij się, że skrypt jest załadowany przed wywołaniem API. Możesz sprawdzić, czy widget jest dostępny:

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

Dialog się nie otwiera?

Zweryfikuj, że podałeś prawidłowy data-widget-key (lub, dla jawnej formy, client-id, agent-id i config-id) i że jest poprawny. Jeśli jest wiele widgetów, upewnij się, że każdy skrypt ma unikalny data-instance-id.