Szybki start

Przegląd widgetu

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

Widżet jest lekką, samodzielną aplikacją, która działa w izolowanym iframe na Twojej stronie internetowej. Ta architektura zapewnia, że widżet nie będzie kolidował z Twoim istniejącym CSS lub JavaScript, zachowując jednocześnie doskonałą wydajność i bezpieczeństwo.

1. Utwórz agenta

Najpierw utwórz Agenta Wsparcia Klienta AI w swoim pulpicie:

Twój agent to AI, która stoi za widżetem. 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 pulpitu 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 pulpicie
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'ów 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 kluczem instalacyjnym Twojego widgetu (wartość wgt_… — skopiuj ją z strony Widgetu lub strony Instalacji w pulpicie). Parametr locale można ustawić, aby odpowiadał językowi Twojej witryny.

Zaawansowane: Inicjalizacja JavaScript

Zalecana metoda integracji to użycie naszego loadera widżetu JavaScript, który zapewnia automatyczne dostosowywanie, 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"  data-theme="system"  async></script>

Atrybuty skryptu

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

• data-widget-key: ID widżetu - Jedna wartość, której większość instalacji potrzebuje. Rozwiązuje Twojego klienta, agenta i konfigurację po stronie serwera, więc nie musisz ich wklejać osobno.

Trzy poniższe atrybuty są zaawansowaną alternatywą dla data-widget-key - użyj ich w przypadku konfiguracji wieloinstancyjnych, gdzie musisz celować w konkretnego klienta, agenta lub konfigurację wyraźnie:

• data-client-id: Twój ID klienta OAuth - To uwierzytelnia Twoją aplikację w 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 Twojej konfiguracji widżetu - To określa, jak wygląda i zachowuje się Twój widżet (kolory, rozmiar, pozycja itp.).
• data-instance-id: Unikalne ID instancji widżetu - Wymagane podczas osadzania wielu widżetów na tej samej stronie, aby uniknąć kolizji i umożliwić celowanie w API per-instancji.
• data-custom-css: Nieaktualne. Ustawienie tego atrybutu rejestruje ostrzeżenie w konsoli i nie ma wpływu. Ustaw custom_css w konfiguracji widżetu w panelu zamiast tego — jest ładowane z konfiguracji i automatycznie wstrzykiwane do iframe.
• data-locale: Kod języka (np. "en", "es", "fr") - Ustawia język wyświetlania widżetu. Agent nadal będzie odpowiadał w każdym języku, w którym piszą użytkownicy.
• data-theme: Tryb motywu - light, dark lub system (podążaj za urządzeniem odwiedzającego). Wybiera, która paleta kolorów (skonfigurowana w Twoim panelu) jest wyświetlana przez widżet. Omiń to, aby użyć zapisanej domyślnej.
• data-dev: Ustaw na "true" dla trybu dewelopera (localhost) - Użyj tego podczas testowania lokalnie. Usuń lub ustaw na "false" dla produkcji.

Widżet automatycznie:

• Pobiera konfigurację z ID konfiguracji
• Dostosowuje się do wymiarów widżetu w konfiguracji
• Pozycjonuje złożony przycisk na podstawie ustawień konfiguracji
• Zaczyna otwarty lub zamknięty na podstawie ustawienia start_open w konfiguracji.

Uwagi

• Widget automatycznie zarządza swoim rozmiarem na podstawie ustawień konfiguracyjnych
• Pozycja zminimalizowanego przycisku może być dostosowana za pomocą konfiguracji widgetu
• Widget respektuje ustawienie start_open z twojej konfiguracji
• Wszystkie style (kolory, czcionki, wymiary) są kontrolowane przez konfigurację widgetu
• Widget używa komunikacji postMessage do responsywnego zachowania
• Tryb dewelopera można włączyć za pomocą data-dev="true" do testowania na localhost
• Dla wymiany tokenów po stronie serwera użyj /api/v1/auth/widget-token i trzymaj 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 widżetu w iframe.