Przejdź do głównej treści

:::note Stan wersji Funkcje opisane jako dostępne w aktualnym kodzie źródłowym sprawdzono w lokalnym hostowanym loaderze v16; nie oznacza to, że są dostępne w loaderze używanym w Twoim środowisku. Przed poleganiem na nich sprawdź jego wersję. Opublikowane npm SDK 0.1.4 udostępnia remove(); aby zakończyć teardown, usuń wszystkie uchwyty mount utworzone dla tej samej konfiguracji. Teardown zadziała tylko wtedy, gdy loader obsługuje wysyłany przez SDK sygnał usunięcia. :::

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 sprawdź reprezentatywne odpowiedzi w Przetestuj chatbota, zanim poświęcisz czas na wygląd. Pełną kolejność znajdziesz w sekcji Pierwsze kroki.

Skonfiguruj hostowany widżet​

  1. Otwórz panel i wybierz projekt.
  2. Przejdź do Personalizacja → Wygląd, aby edytować wygląd, oznaczenie ChattyBox i ustawienia Język.
  3. Sprawdź stan automatycznego zapisu. W razie błędu popraw dane albo ponów zapis, zanim przetestujesz widżet na stronie.

Kod instalacyjny i klucze publiczne znajdziesz w sekcji Instalacja. Przed instalacją:

  1. Otwórz Instalacja → Klucze i domeny, aby sprawdzić ustawienia originów lub utworzyć publiczny klucz przeglądarkowy. Klucz jest przeznaczony do użycia po stronie klienta i nie jest tajny.
  2. W Instalacja → Instalacja na stronie wybierz odpowiedni klucz i skopiuj wygenerowany fragment. Klucz utworzony bez ograniczeń akceptuje żądania z różnych originów; klucz przygotowany dla konkretnej witryny może już mieć ograniczenie do jej originu. Sprawdź ustawienia klucza przed użyciem go na stagingu lub localhost.
  3. Opcjonalnie włącz ograniczenie do dokładnych originów jako dodatkową warstwę ochrony. Ograniczenie originów nie uwierzytelnia odwiedzających.
  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​

Edytor panelu pozwala zmieniać obsługiwane kolory, położenie, ikonę i tekst widżetu bez edycji kodu witryny. Sprawdź wynik w hostowanym widżecie, ponieważ podgląd i loader nie są identyczne.

Elementy sterujące panelu​

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

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

  3. Tytuł nagłówka - Ustaw tytuł wyświetlany u góry okna czatu.

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

  5. Oznaczenie ChattyBox - Plan Starter i wyższe pozwalają wyłączyć stopkę „Powered by ChattyBox”. W planie Free oznaczenie jest wymagane.

Edytor zawiera także ustawienia Tło widgetu i Kolor tekstu oraz ikonę domyślną, emoji, adres URL obrazu lub przesłany obraz. Przesłana ikona może mieć maksymalnie 512 KiB i musi mieć akceptowany typ MIME: PNG, JPEG, WebP, SVG, GIF lub ICO. Opcja rozmiaru ikony jest dostępna tylko po wybraniu ikony z adresu URL lub przesłanego obrazu. Loader hostowany v16 w aktualnym kodzie źródłowym używa iconSize do ustawienia rozmiaru przycisku uruchamiającego i ikony. Przed poleganiem na tej funkcji sprawdź wersję loadera używaną w swoim środowisku.

notatka

Sprawdź stan automatycznego zapisu wyglądu, popraw ewentualne błędy lub ponów zapis, a następnie odśwież zainstalowaną stronę. Podgląd panelu jest makietą, a nie samym hostowanym widżetem. W projektach z blokadą konfiguracji pola wyglądu i języka są zarządzane przez config-as-code; projekty z odpowiednim planem nadal mogą osobno zapisywać oznaczenie marki.

Domyślne wartości konfiguracji​

Poniższe wartości są zwracane przez poprawne publiczne żądanie konfiguracji widżetu, gdy nie zapisano ustawień niestandardowych:

PoleWartość domyślna
enabledtrue, chyba że widżet został wyłączony dla projektu
themeColor#3b82f6
chatBgColor#0f172a
textColor#f8fafc
positionbottom-right; obsługiwane są wszystkie cztery rogi
iconType, iconSizedefault, medium; loader hostowany v16 w aktualnym kodzie źródłowym używa rozmiaru do skalowania przycisku i ikony
iconEmoji, iconUrlemoji dymku, null
headerTitleChat with us (domyślna wartość API)
welcomeMessageHi! 👋 How can I help you today? (domyślna wartość API)
showBrandingtrue; w planie Free wartość jest wymuszana na true
localeMode, defaultLocale, allowLocaleOverrideauto, en, true (wartości domyślne)

W aktualnym kodzie źródłowym nieudane lub niepoprawne pobranie konfiguracji pozostawia widżet jako niedostępny — nie pojawia się interfejs zastępczy. To coś innego niż nieudane pobranie tłumaczeń: jeśli konfiguracja została pobrana poprawnie, ale katalog tłumaczeń jest niedostępny, widżet nadal się wyświetla, używając wbudowanych etykiet angielskich. Poprawna konfiguracja z enabled: false również uniemożliwia wyświetlenie widżetu; API czatu odrzuca wtedy żądania kodem HTTP 403, także z SDK. Przed poleganiem na zachowaniu z aktualnego kodu źródłowego sprawdź wersję loadera używaną w swoim środowisku.

Loader hostowany v16 w aktualnym kodzie źródłowym pobiera konfigurację z nagłówkiem Authorization: Bearer i ponawia żądanie raz z kluczem w parametrze URL tylko po HTTP 400. Opublikowane SDK 0.1.4 stosuje ten sam ograniczony fallback dla konfiguracji, jeśli strona udostępnia window.ChattyboxSDK. Loader v16 osobno ponawia kwalifikujące się błędy początkowych żądań GET konfiguracji i tłumaczeń. Wiadomości czatu używają własnego transportu loadera. Przy montowaniu SDK opublikowane SDK 0.1.4 współdzieli tylko identyczne opcje i odrzuca zmianę klucza, endpointu, URL-a skryptu, locale lub ustawienia debugowania, dopóki nie zostaną usunięte wszystkie pasujące uchwyty. Przed poleganiem na zachowaniu z aktualnego kodu źródłowego sprawdź wersję loadera używaną w swoim środowisku.

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.

W sekcji Personalizacja → Wygląd zarządzasz kolorami, pozycją, ikoną, tytułem nagłówka, wiadomością powitalną, językiem i oznaczeniem ChattyBox. Sekcja Instalacja → Klucze i domeny służy do zarządzania kluczami publicznymi i originami.

Klucz publiczny nie jest tajny ani nie uwierzytelnia odwiedzających. Ograniczenie originów jest opcjonalną dodatkową ochroną, a nie mechanizmem uwierzytelniania. Jeśli je włączysz, utrzymuj listę dokładnych originów w zgodzie z domenami, na których działa widżet; sprawdź też, czy wybrany klucz nie ma już ograniczenia przygotowanego dla konkretnej witryny.

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 widżetu, jeśli projekt zezwala na nadpisanie skryptem; aktualny kod źródłowy loadera obserwuje również późniejsze zmiany tego atrybutu.
  • data-color i data-position nadpisują zapisany kolor akcentu i pozycję po poprawnym pobraniu konfiguracji. Preferuj ustawienia panelu; atrybuty te mogą przesłonić późniejsze zmiany w panelu.
  • data-debug="true" włącza diagnostykę w konsoli; domyślnie jest wyłączona.

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

Przy nowej wiadomości widżet w aktualnym kodzie źródłowym próbuje wysłać origin i ścieżkę bieżącej strony HTTP(S) na potrzeby analityki Popularne wyzwalacze. Nie sprawdza, czy strona jest publiczna. Niepoprawny lub zbyt długi kontekst jest pomijany, a ponowienia zachowują kontekst pierwotnego żądania. Usuwane są query stringi, fragmenty i dane uwierzytelniające, ale ścieżka może zawierać wrażliwe identyfikatory. Widżet uwzględnia też ustawienie prefers-reduced-motion, udostępnia pole wiadomości z etykietą i komunikaty na żywo, a cytaty pokazuje w dostępnym z klawiatury rozwijanym panelu Źródła.

Kontekst strony pochodzi z bieżącego adresu HTTP(S), a nie ze sprawdzenia, czy strona jest publiczna. Nie ładuj widżetu na wrażliwych trasach tylko dlatego, że parametry zapytania są usuwane. Loader może również wysyłać do /widget-error raporty o błędach inicjalizacji, konfiguracji, tłumaczeń i czatu — przez beacon lub fetch — z ograniczonymi co do długości szczegółami błędu, locale, wersją oraz originem i ścieżką strony. Raportowanie nie wymaga włączenia trybu debugowania.

Chat zwraca kompletną odpowiedź JSON, a nie tokeny w strumieniu. Hostowany loader v16 w aktualnym kodzie źródłowym tworzy osobny klucz idempotencji dla każdej logicznej wiadomości i używa ponownie tego samego klucza przy ponowieniach transportu. Serwer może wtedy zwrócić zapisaną odpowiedź bez ponownego wykonania żądania. Loader wykonuje maksymalnie 10 automatycznych prób transportu w przypadku błędów sieci, przerwanego odczytu poprawnej odpowiedzi, HTTP 429, HTTP 5xx oraz odpowiedzi 409 z czytelnym nagłówkiem Retry-After. Nie planuje kolejnej próby, jeśli opóźnienie przekroczyłoby budżet 30 sekund; nie jest to twardy limit czasu trwającego żądania. CORS w przeglądarce może ukryć nagłówek Retry-After. Headless sendMessage() nie zapewnia takich automatycznych ponowień; ponawianie początkowych żądań GET loadera oraz fallback konfiguracji SDK 0.1.4 po HTTP 400 to odrębne, ograniczone mechanizmy. Stan rozmowy istnieje tylko w pamięci danej instancji widżetu i znika po przeładowaniu lub ponownej inicjalizacji; wiadomości zapisane na serwerze mogą pozostać. Źródła są deduplikowane, a na ekranie wyświetlane są maksymalnie trzy; odpowiedź zastępcza może nie zawierać źródeł. Przed poleganiem na tym zachowaniu sprawdź wersję loadera używaną w swoim środowisku.

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

Ukrywanie widżetu na określonych stronach​

Aby wizualnie ukryć widżet, stosuj poniższy CSS tylko na wybranych stronach (zastosowany globalnie ukryje widżet wszędzie):

.chattybox-widget {
display: none;
}

Ukrycie za pomocą CSS nie zatrzymuje inicjalizacji, żądań API ani raportowania błędów i nie jest mechanizmem zgody ani ochrony prywatności. Loader sam nie podejmuje decyzji dotyczących zgody: dodawaj skrypt dopiero po uzyskaniu wymaganej zgody i nie dodawaj go ponownie po jej wycofaniu ani na wykluczonych trasach. Przy nawigacji po stronie klienta lub wycofaniu zgody użyj window.ChattyBox.destroy() tylko wtedy, gdy loader używany w danym środowisku obsługuje teardown; samo usunięcie tagu <script> nie wystarczy. Uchwyty mount SDK 0.1.4 są zliczane: usuń wszystkie pasujące uchwyty, aby wywołać końcowy teardown. Teardown usuwa własne UI i style oraz anuluje oczekujące operacje, ale nie cofnie żądań, które serwer już przetworzył. Ponownie inicjalizuj widżet tylko wtedy, gdy zgoda została udzielona, a bieżąca trasa na to pozwala.

Sterowanie widżetem z poziomu przeglądarki​

W aktualnym kodzie źródłowym v16 window.ChattyBox jest dostępne już podczas uruchamiania i ma status loading; w tym czasie można też wywołać destroy(). Po poprawnym zakończeniu inicjalizacji sprawdź window.ChattyBox?.status === 'ready' przed wywołaniem open(), close(), toggle() lub sendMessage(text). Samo załadowanie skryptu nie oznacza, że konfiguracja i tłumaczenia zostały już pobrane. destroy() usuwa widżet i style, przerywa pracę instancji i usuwa globalny obiekt; nie cofnie żądania już przetworzonego przez serwer. close() zamyka tylko panel czatu — przycisk uruchamiający pozostaje widoczny. sendMessage(text) zwraca obietnicę zakończenia operacji interfejsu, a nie obietnicę odpowiedzi; wysłanie kolejnej wiadomości podczas oczekującego żądania jest ignorowane. Ten globalny obiekt różni się od konstruktorów SDK w window.ChattyboxSDK. Przed poleganiem na tych funkcjach sprawdź wersję loadera używaną w swoim środowisku.

Motyw jasny i ciemny sterowany przez witrynę (aktualny kod źródłowy)​

Przepływ config-as-code w aktualnym kodzie źródłowym obsługuje opcjonalne palety widget.theme.light i widget.theme.dark. Każda przyjmuje sześciocyfrowe kolory szesnastkowe primaryColor, backgroundColor i textColor; pominięte kolory dziedziczą wartości z bazowego widget.theme. Dotychczasowe konfiguracje z jednym motywem nadal działają bez zmian. Wymaga to CLI i backendu z aktualnego kodu źródłowego oraz hostowanego loadera v16; opublikowana wersja CLI/config 0.3.1 nie akceptuje tych pól.

Ustaw data-theme="light" lub data-theme="dark" w tagu skryptu loadera przed jego uruchomieniem, aby wybrać motyw początkowy. Następnie połącz przełącznik witryny z API przeglądarki:

window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.

Widżet aktualizuje istniejące style bez resetowania wiadomości, źródeł, tekstu roboczego ani oczekującego żądania. Wybór motywu nie zmienia dostępności widżetu ani oznaczenia ChattyBox. Witryna odpowiada za zapamiętanie preferencji i zachowanie względem motywu systemowego; widżet jedynie wybiera skonfigurowaną paletę.

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​

Opisane poniżej zachowanie dotyczy aktualnego kodu źródłowego: widżet obserwuje zmiany w <html lang> i data-locale skryptu loadera, a etykiety aktualizuje w miejscu bez resetowania rozmowy, wpisanego tekstu ani oczekującego ponowienia. Sama nawigacja nie wybiera języka; w razie potrzeby aktualizuj jeden z tych atrybutów. Zmiany ustawień w panelu nadal wymagają ponownej inicjalizacji. Nie zakładaj, że loader używany w Twoim środowisku ma tę obsługę.

Oficjalnie obsługiwane języki​

Widżet ma katalogi tłumaczeń dla 14 języków. Wszystkie aktualne katalogi używają układu od lewej do prawej. Katalogi UI nie tłumaczą tekstu skonfigurowanego przez projekt ani odpowiedzi wygenerowanych przez AI.

JęzykKod
Angielskien
Francuskifr
Niemieckide
Hiszpańskies
Włoskiit
Niderlandzkinl
Portugalskipt
Polskipl
Szwedzkisv
Indonezyjskiid
Estońskiet
Fińskifi
Walijskicy
Czeskics

:::note Język UI a odpowiedź Aktualny kod źródłowy hostowanego loadera wysyła ustalone locale UI wraz z żądaniami czatu. Backend wykrywa język pytania i próbuje dopasować do niego wyszukiwanie oraz generowanie. Rozpoznany sygnał języka pytania ma pierwszeństwo przed locale UI przy wyborze języka produktowych komunikatów fallback; jeśli wykrywanie jest niejednoznaczne albo opiera się wyłącznie na heurystyce angielskiego tekstu ASCII, locale UI może określić ich język. Nie tłumaczy to tekstu fallbacku skonfigurowanego przez projekt ani nie zmienia odpowiedzi wygenerowanej przez AI. Jakość odpowiedzi i dostępne języki zależą od zindeksowanych treści i skonfigurowanego modelu; katalogi UI nie gwarantują jakości odpowiedzi. :::

Jak działa wykrywanie języka​

Widżet korzysta z kaskadowego systemu wykrywania:

  1. Dozwolone nadpisanie przez skrypt - Obsługiwane data-locale ma pierwszeństwo, jeśli allowLocaleOverride nie ma wartości false — również w trybie stałym.
  2. Tryb stały - Jeśli nie ma obsługiwanego i dozwolonego nadpisania, używany jest defaultLocale, a język strony i przeglądarki jest pomijany.
  3. Tryb automatyczny - Kolejno sprawdzane są <html lang>, navigator.language, każda wartość z navigator.languages, starsze userLanguage, a następnie defaultLocale; wybierany jest pierwszy obsługiwany język.
  4. Normalizacja - Wielkość liter nie ma znaczenia, a rozpoznawane locale regionalne, takie jak fr-CA, są sprowadzane do obsługiwanego języka bazowego. Nieobsługiwane wartości są pomijane; jeśli żadna wartość nie jest obsługiwana, używany jest angielski. Domyślnie: tryb automatyczny, angielski i dozwolone nadpisanie przez skrypt.

Niestandardowe tytuły nagłówka i wiadomości powitalne są wyświetlane bez zmian, a nie tłumaczone automatycznie. Domyślne tytuły i wiadomości powitalne w aktualnym kodzie źródłowym korzystają z lokalizowanych etykiet. Jeśli pobranie tłumaczeń nie powiedzie się po poprawnym pobraniu konfiguracji, widżet nadal działa, używając wbudowanych etykiet angielskich.

Ręczne zastępowanie języka​

Aby zażądać konkretnego języka niezależnie od ustawień przeglądarki, włącz Zezwalaj na nadpisanie przez skrypt i dodaj obsługiwany 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:

  • Wykryj automatycznie - Najpierw używa języka strony, potem języków przeglądarki
  • Stały - Używa skonfigurowanego języka domyślnego, chyba że dozwolone data-locale go nadpisze
  • Zezwalaj na nadpisanie przez skrypt - Włącza lub wyłącza zastępowanie za pomocą atrybutu data-locale

Ustawienia znajdziesz w panelu → Personalizacja → Wygląd → Język. Sprawdź stan automatycznego zapisu języka; w razie błędu popraw dane albo ponów zapis przed testowaniem.

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
  • Sprawdź tryb projektu i możliwość nadpisania - Tryb stały lub wyłączone nadpisania mogą celowo ignorować język przeglądarki albo data-locale
  • 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 i żądania - Katalogi istnieją tylko dla 14 wymienionych wyżej kodów; brakujące klucze używają wbudowanych tekstów zastępczych

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