Osadzanie Agenta Dokumentów

Dowiedz się, jak osadzić widget Agenta Dokumentów na swoich stronach dokumentacji.

Przegląd

Agent Dokumentów to specjalizowany widget zasilany AI, zaprojektowany specjalnie dla stron dokumentacji. Zapewnia natychmiastową pomoc twoim użytkownikom, odpowiadając na pytania dotyczące twojej dokumentacji za pomocą interaktywnego dialogu na pełnym ekranie.

Wypróbuj to teraz!

Kliknij przycisk poniżej, aby zobaczyć Agenta Dokumentów w akcji na tej stronie.

Podstawowe ustawienia

Rozpoczęcie pracy z widgetem Agenta Dokumentów 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 widgetu 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 dokumentów, nadaj każdemu skryptowi unikalne 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>

Przykłady

Oto kilka praktycznych przykładów, jak zintegrować Agenta Dokumentów:

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 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 Agenta Dokumentów akceptuje kilka parametrów konfiguracyjnych. Użyj data-instance-id do deterministycznej kontroli per-instance podczas osadzania wielu widgetów na jednej stronie:

Wymagane parametry

data-widget-key: Identyfikator widgetu Twojej dokumentacji — jedyna wartość, której potrzebuje większość instalacji. Rozwiązuje Twój klient, agent i serwer konfiguracyjny po stronie serwera.

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

data-client-id: Twój unikalny identyfikator klienta z pulpitu Companin
data-agent-id: ID agenta, którego chcesz użyć
data-config-id: ID konfiguracji do dostosowania 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)

API JavaScript

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

open()

window.CompaninDocsWidget.open();

Otwiera dialog Agenta Dokumentów w trybie pełnoekranowym.

close()

window.CompaninDocsWidget.close();

Zamyka dialog Agenta Dokumentów i ukrywa widget.

Niestandardowe stylizowanie

Możesz stylizować swoje przyciski wyzwalające w dowolny sposób. Oto przykład unoszącego się 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, unoszący się przycisk)
Użyj jasnego, zorientowanego na działanie tekstu przycisku, takiego jak 'Zapytaj AI' lub 'Potrzebujesz pomocy?'
Upewnij się, że skrypt widgetu ładuje się 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, czy podałeś prawidłowy data-widget-key (lub, w przypadku formy jawnej, client-id, agent-id i config-id) i czy jest on poprawny. Jeśli obecnych jest wiele widżetów, upewnij się, że każdy skrypt ma unikalny data-instance-id.

Wstecz Dalej: Przegląd