Szybki start

Przegląd widgetu

Aplikacja widgetu jest hostowana pod adresem widget.companin.tech i zapewnia łatwy sposób na osadzenie agenta AI wsparcia klienta na twojej stronie internetowej. Aby rozpocząć, musisz utworzyć agenta i aplikację OAuth.

Widget to lekka, samodzielna aplikacja, która działa w izolowanym iframe na Twojej stronie internetowej. Ta architektura zapewnia, że widget nie będzie kolidować z istniejącym CSS lub JavaScript, zachowując jednocześnie doskonałą wydajność i bezpieczeństwo.

1. Utwórz agenta

Najpierw utwórz agenta AI wsparcia klienta w swoim panelu:

Twój agent to AI mózg stojący za widgetem. Przetwarza wiadomości użytkowników, utrzymuje kontekst rozmowy i generuje inteligentne odpowiedzi. Każdy agent może być dostosowany z konkretnymi instrukcjami, cechami osobowości i bazami wiedzy, aby dopasować się do Twojego przypadku użycia.

1. Przejdź do swojego panelu i przejdź do strony "Źródła danych"
2. Kliknij przycisk "Dodaj" w sekcji Agentów
3. Wypełnij szczegóły agenta (nazwa, opis, ton itp.)
4. Zapisz agenta i zanotuj jego ID

Wskazówka: Daj swojemu agentowi jasne, konkretne instrukcje dotyczące jego roli i ograniczeń. Na przykład: "Jesteś pomocnym agentem wsparcia klienta dla produktu SaaS. Możesz odpowiadać na pytania dotyczące funkcji, cen i zarządzania kontem. W przypadku problemów technicznych skieruj użytkowników do utworzenia zgłoszenia wsparcia."

2. Utwórz aplikację OAuth

Utwórz aplikację OAuth, aby uwierzytelnić swój widget:

1. Przejdź do strony "OAuth" w swoim panelu
2. Kliknij "Utwórz aplikację"
3. Wypełnij nazwę aplikacji i opis
4. Skopiuj client_id z utworzonej aplikacji

3. Osadź widget za pomocą iframe

Najprostszym sposobem na integrację widgetu jest osadzenie go bezpośrednio za pomocą iframe. Ta metoda nie wymaga inicjalizacji JavaScript i działa od razu. W przypadku wielu iframe na jednej stronie, trzymaj każde osadzenie w swoim własnym kontenerze i parametrach.

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

Zastąp YOUR_WIDGET_KEY identyfikatorem Widgetu (znajdziesz go na stronie Instalacji). Parametr locale można ustawić tak, aby pasował do języka Twojej strony.

Zaawansowane: Inicjalizacja JavaScript

Zalecana metoda integracji to użycie naszego loadera widgetów JavaScript, który zapewnia automatyczne dostosowywanie rozmiaru, zarządzanie konfiguracją i responsywne zachowanie.

Integracja skryptu

Dodaj następujący tag skryptu do swojej strony HTML:

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

Atrybuty skryptu

Każdy atrybut ma określony cel w konfigurowaniu Twojego widgetu:

• data-widget-key: Identyfikator widgetu Twojego widgetu - Pojedyncza wartość, której potrzebuje większość instalacji. Rozwiązuje Twojego klienta, agenta i serwer konfiguracyjny po stronie serwera, więc nie musisz ich wklejać osobno.

Trzy atrybuty poniżej są zaawansowaną alternatywą dla data-widget-key - używaj ich w konfiguracjach z wieloma instancjami, gdzie musisz wyraźnie wskazać konkretnego klienta, agenta lub konfigurację:

• data-client-id: Twój identyfikator klienta OAuth - To uwierzytelnia Twoją aplikację z naszym API. Myśl o tym jak o haśle Twojej aplikacji.
• data-agent-id: UUID Twojego agenta - To identyfikuje, który agent AI wsparcia klienta obsługuje rozmowy.
• data-config-id: UUID konfiguracji Twojego widgetu - To określa, jak wygląda i działa Twój widget (kolory, rozmiar, pozycja itp.).
• data-instance-id: Unikalny identyfikator instancji widgetu - Wymagany przy osadzaniu wielu widgetów na tej samej stronie, aby uniknąć kolizji i umożliwić celowanie w API na poziomie instancji.
• data-custom-css: Nieaktualne. Ustawienie tego atrybutu rejestruje ostrzeżenie w konsoli i nie ma wpływu. Ustaw custom_css w konfiguracji widgetu na pulpicie nawigacyjnym - jest ładowane z konfiguracji i automatycznie wstrzykiwane do iframe.
• data-locale: Kod języka (np. "en", "es", "fr") - Ustawia język wyświetlania widgetu. Agent nadal będzie odpowiadał w każdym języku, w którym piszą użytkownicy.
• data-dev: Ustaw na "true" dla trybu dewelopera (localhost) - Użyj tego podczas testowania lokalnie. Usuń lub ustaw na "false" dla produkcji.

Widget automatycznie:

• Pobiera konfigurację z identyfikatora konfiguracji
• Dostosowuje się do wymiarów widgetu w konfiguracji
• Pozycjonuje złożony przycisk na podstawie ustawień konfiguracji
• Zaczyna otwarty lub zamknięty w zależności od ustawienia start_open w konfiguracji

Notatki

• Widget automatycznie zarządza swoim rozmiarem na podstawie ustawień konfiguracji
• Pozycja złożonego przycisku może być dostosowana przez konfigurację widgetu
• Widget respektuje ustawienie start_open z Twojej konfiguracji
• Wszystkie style (kolory, czcionki, wymiary) są kontrolowane przez konfigurację widgetu
• Widget używa komunikacji postMessage dla responsywnego zachowania
• Tryb dewelopera można włączyć za pomocą data-dev="true" do testowania lokalnego
• Dla wymiany tokenów po stronie serwera użyj /api/v1/auth/widget-token i przechowuj tajny klucz klienta tylko na swoim serwerze.
• Upewnij się, że pochodzenie hosta (na przykład http://localhost:3000) jest uwzględnione w dozwolonych pochodzeniach OAuth podczas osadzania widgetu w iframe.