:::note Stan wersji Opublikowane npm SDK 0.1.4 z hostowanym widget.js v15 obsługuje teardown przez remove() lub window.ChattyBox.destroy(): usuwa UI/style i anuluje oczekującą inicjalizację, ponowienia oraz czaty. Chat v15 wykonuje najwyżej 10 prób w budżecie planowania 30 s, a nie w sztywnym timeoutcie żądania. Headless sendMessage() nie ponawia automatycznie. :::

Dostosowywanie hostowanego widżetu

Dostosuj gotowy interfejs ładowany przez https://chattybox.ai/widget.js. Oficjalne przykłady instalacji dla frameworków i platform znajdziesz w Przewodnikach instalacji.

Zanim zaczniesz dostosowywać

Utwórz projekt, zindeksuj jego treść i zweryfikuj reprezentatywne odpowiedzi w Test Chat, zanim poświęcisz czas na prezentację. Pełną kolejność znajdziesz w sekcji Pierwsze kroki.

Skonfiguruj hostowany widżet

1. Otwórz panel i wybierz projekt.
2. Przejdź do zakładki Embed.
3. Wyświetl podgląd i zapisz wygląd widżetu oraz zachowanie językowe.

Zakładka Embed steruje prezentacją i generuje kod instalacyjny, ale publicznymi kluczami zarządza się osobno. Gdy będziesz gotowy do instalacji:

1. Otwórz Public Keys i utwórz klucz przeglądarkowy.
2. W razie potrzeby opcjonalnie ogranicz jego dokładne originy do witryny docelowej.
3. Wróć do Embed, wybierz klucz i skopiuj wygenerowany fragment.
4. Postępuj zgodnie z Przewodnikami instalacji dla swojej platformy.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

wskazówka

Zmiany zapisane w panelu są pobierane przy następnej inicjalizacji; otwarta strona wymaga odświeżenia.

---

Dostosowywanie wyglądu

ChattyBox zawiera w pełni zintegrowany edytor wizualny. Możesz dopasować wygląd i charakter widżetu do swojej marki bez dotykania kodu.

Elementy sterujące panelu

1. Accent Color - Wybierz główny kolor marki. Wpływa on na przycisk uruchamiający, najważniejsze wyróżnienia i wiadomości użytkownika.

2. Position - Wybierz miejsce wyświetlania widżetu na ekranie.

3. Header Title - Ustaw tytuł wyświetlany u góry okna czatu.

4. Welcome Message - Dostosuj pierwszą wiadomość wyświetlaną odwiedzającym po otwarciu czatu.

notatka

Zapisz zmiany i odśwież zainstalowaną stronę. Podgląd panelu nie jest hostowanym widżetem.

Opcje zaawansowane

Ustawienia panelu a atrybuty skryptu

Większością zachowania widżetu należy zarządzać z panelu, aby proste zmiany nie wymagały ponownego wdrażania witryny.

Panel służy do ustawiania kolorów, położenia, ikony, tytułu nagłówka, wiadomości powitalnej, domyślnych języków, zarządzania kluczami publicznymi, skanowania i analityki.

Jeśli projekt korzysta z ograniczeń originów klucza publicznego, utrzymuj je w zgodzie z domenami, na których zainstalowano widżet.

Atrybutów skryptu używaj tylko dla wartości potrzebnych widżetowi podczas ładowania strony:

• data-api-key identyfikuje publiczny klucz widżetu.
• data-api-url wskazuje widżetowi, dokąd wysyłać żądania. W produkcji jest to stabilny adres https://...convex.site/chat z panelu.
• data-locale żąda języka UI przy inicjalizacji tylko, gdy projekt zezwala na nadpisanie skryptem.

Jeśli widżet nie pojawia się po instalacji, zobacz sekcję Rozwiązywanie problemów.

Widżet wysyła kontekst aktualnej strony HTTP(S) bez query/fragmentu na potrzeby Popular Triggers. CSS display:none nie zatrzymuje inicjalizacji ani żądań; do niewczytywania wyklucz skrypt. Nie ma API destroy, a remove() SDK usuwa jedynie skrypt.

Przykłady dla konkretnych platform znajdziesz w przewodnikach Docusaurus, MkDocs, VitePress, WordPress lub GitBook.

Ukrywanie widżetu na określonych stronach

Jeśli chcesz ukryć widżet na wybranych stronach, możesz zrobić to za pomocą CSS:

.chattybox-widget {
  display: none;
}

Niestandardowe integracje

Potrzebujesz bardziej dopasowanej konfiguracji niż hostowany widżet? Zbuduj własny interfejs za pomocą JavaScript SDK lub napisz na support@chattybox.ai, aby uzyskać pomoc dotyczącą architektury.

Obsługa wielu języków

Widżet rozstrzyga język UI tylko przy inicjalizacji, zgodnie z trybem projektu Fixed albo Auto; nie śledzi zmian tras SPA.

Oficjalnie obsługiwane języki

Widżet ma katalogi tłumaczeń dla 14 języków. Katalog nie oznacza, że każdy widoczny lub dostępny tekst jest przetłumaczony, ani nie gwarantuje jakości odpowiedzi.

Język	Kod
Angielski	en
Francuski	fr
Niemiecki	de
Hiszpański	es
Włoski	it
Niderlandzki	nl
Portugalski	pt
Polski	pl
Szwedzki	sv
Indonezyjski	id
Estoński	et
Fiński	fi
Walijski	cy
Czeski	cs

:::note Język UI a odpowiedź Katalog UI nie jest parametrem języka czatu ani gwarancją jakości odpowiedzi. Zależy ona od pytania, modelu i zindeksowanych treści. :::

Jak działa wykrywanie języka

Widżet korzysta z kaskadowego systemu wykrywania:

1. Niepuste data-locale wygrywa tylko przy włączonym Allow Script Override.
2. W trybie Fixed używany jest defaultLocale.
3. W Auto: <html lang>, potem język przeglądarki, potem domyślny język.
4. Nieobsługiwana wartość przechodzi od razu na angielski; regionalne obsługiwane wartości są redukowane do kodu bazowego.

Ręczne zastępowanie języka

Aby poprosić o konkretny język niezależnie od ustawień przeglądarki, włącz Allow Script Override i dodaj atrybut data-locale przed uruchomieniem loadera:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-locale="de"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

:::tip Przykład użycia Jest to szczególnie przydatne w wielojęzycznej witrynie, w której każda wersja językowa ma własny adres URL (np. /de/, /fr/). Ustaw data-locale zgodnie z językiem każdej strony i sprawdź wyrenderowany interfejs. :::

Ustawienia języka w panelu

Panel aplikacji pozwala skonfigurować preferencje językowe widżetu dla każdego projektu:

• Auto-detect - Najpierw używa języka strony, potem przeglądarki
• Fixed Language - Używa języka domyślnego, chyba że dozwolone data-locale go nadpisze
• Allow Script Override - Włącza lub wyłącza zastępowanie za pomocą atrybutu data-locale

Ustawienia znajdziesz w panelu → Project → zakładka Embed → sekcja Widget Language.

Dopasowanie języka treści

Aby zapewnić najlepsze doświadczenie wielojęzyczne, zindeksuj publiczne treści w językach odwiedzających i testuj cytowania — wykrywanie oraz dopasowanie nie są gwarantowane.

1. Przeskanuj wszystkie wersje językowe dokumentacji za pomocą pliku sitemap.xml.
2. Skaner próbuje wykryć język strony; sprawdź treść i cytowania.
3. Wyszukiwanie próbuje preferować język pytania, ale może użyć innych zindeksowanych treści.

Konfiguracja w panelu aplikacji: podczas konfigurowania skanowania użyj adresu URL sitemap.xml (np. https://yourdocs.com/sitemap.xml), aby wykryć wersje językowe, a następnie sprawdź zindeksowane strony. Mapy witryn nie omijają limitów indeksowania ani wykluczeń.

Rozwiązywanie problemów

Widżet nadal wyświetla język angielski

• Twarde odświeżenie jako diagnostyka - Odśwież stronę za pomocą Ctrl+F5 lub Cmd+Shift+R, a następnie sprawdź żądania widżetu i tłumaczeń w panelu sieciowym przeglądarki
• Sprawdź data-locale - Upewnij się, że atrybut jest prawidłowo ustawiony na obsługiwany kod języka
• Zweryfikuj język przeglądarki - Sprawdź, czy preferowany język przeglądarki jest ustawiony prawidłowo
• Sprawdź język strony HTML - Upewnij się, że strona zawiera <html lang="de"> (lub odpowiedni kod)

Źródła są w niewłaściwym języku

• Przeskanuj treść ponownie - Sprawdź, czy żądane wersje językowe są zindeksowane
• Użyj sitemap.xml - Potwierdź, że żądane adresy URL zostały rzeczywiście zindeksowane; limity indeksowania i wykluczenia mogą je pominąć
• Sprawdź język zapytania - AI próbuje dopasować język odpowiedzi do języka zapytania

Brakujące tłumaczenia

• Sprawdź obsługiwane języki - Tylko 14 wymienionych wyżej kodów ma katalogi; brakujące etykiety mogą użyć angielskiego tekstu zastępczego

Najlepsze praktyki

1. Ustaw <html lang> na stronach - Pomaga to w dostępności i wykrywaniu widżetu
2. Testuj z data-locale podczas tworzenia - Sprawdź, czy każdy język renderuje się poprawnie
3. Skanuj wszystkie wersje językowe - Użyj sitemap.xml do wykrywania i sprawdź zindeksowane strony
4. Przeglądaj rzeczywiste pytania - Sprawdzaj rozmowy i luki w treściach specyficzne dla języka; panel nie udostępnia obecnie raportu rozkładu locale widżetu