:::note Stan wersji Opublikowane npm SDK i hostowany skrypt widget.js są wersjonowane osobno; opublikowane SDK ma wersję 0.1.4, a bieżące źródło hostowanego widżetu to v16. remove() wymaga loadera obsługującego teardown — sprawdź wersję wdrożoną, szczególnie przy self-hostingu. SDK 0.1.4 nie ma reaktywnego API zmiany locale; bieżący hostowany v16 może odświeżać etykiety po zmianie rozpoznanego locale, zgodnie z polityką projektu. Headless sendMessage() nie ponawia automatycznie. Historyczny hostowany v15 może zaplanować maksymalnie 10 prób czatu w 30-sekundowym oknie ponawiania; to nie jest twardy limit czasu dla żądania już trwającego. :::

Integracja z asystentem programowania AI

Zalecaną integracją w kodzie aplikacji jest pakiet npm @openstaticfish/chattybox. Umożliwia skonfigurowanie publicznego klucza i adresu URL API w kodzie, załadowanie utrzymywanego pływającego widżetu z trwałego układu aplikacji w przeglądarce albo użycie klienta headless do stworzenia własnego UI.

Samodzielny skrypt widget.js opisano na końcu jako awaryjną opcję bez budowania dla witryn, które nie mogą instalować pakietów npm.

Zanim zaczniesz

Skonfiguruj chatbota, zanim poprosisz asystenta o edycję aplikacji:

• Zweryfikuj reprezentatywne odpowiedzi i cytowania w Przetestuj chatbota.
• W Instalacja → Klucze i domeny sprawdź lub utwórz publiczny klucz przeglądarkowy i jego ograniczenia originów. Klucz przygotowany dla witryny może już być ograniczony; ograniczenia są opcjonalnym dodatkowym zabezpieczeniem, a nie uwierzytelnianiem odwiedzających.
• W Instalacja → Instalacja na stronie wybierz odpowiedni klucz i skopiuj wygenerowany snippet. Użyj jego data-api-url, jeśli występuje; w przeciwnym razie przed integracją uzyskaj prawidłowy widgetowy endpoint HTTP z konfiguracji wdrożenia.
• Zdecyduj, czy aplikacja powinna mieć pływający widżet zachowywany podczas nawigacji, czy potrzebujesz własnego interfejsu montowanego i czyszczonego w zakresie wybranych tras.

To publiczne dane uwierzytelniające używane w przeglądarce, ale nadal unikaj commitowania wartości zależnych od środowiska. Nigdy nie przekazuj tokenu wdrażania konfiguracji, danych administratora ani niezwiązanego pliku środowiskowego.

Zalecane: Zamontuj utrzymywany interfejs z npm

To domyślny prompt dla React, Next.js, Vite i innych pakietowych aplikacji przeglądarkowych.

Polecenie

Zintegruj pakiet npm ChattyBox

Zintegruj ChattyBox z tą aplikacją, używając pakietu npm @openstaticfish/chattybox.

Publiczna konfiguracja przeglądarki:
- Klucz API: [PASTE PUBLIC WIDGET KEY]
- Adres URL API: [PASTE WIDGET API URL]

Klucz widżetu jest publiczny i może znaleźć się w kodzie przeglądarki; nie jest sekretem ani mechanizmem uwierzytelniania odwiedzających. Ograniczenia originów są opcjonalnym dodatkowym zabezpieczeniem, a nie uwierzytelnianiem. Klucz przygotowany dla witryny może już mieć ograniczenie: sprawdź jego konfigurację i, jeśli jest ograniczony, dopuść wszystkie wymagane originy produkcyjne, podglądowe, stagingowe i localhost (dokładny schemat, host i port). Nigdy nie proś o token wdrożeniowy konfiguracji, dane administratora ani inne sekrety i nie umieszczaj ich w kodzie przeglądarki.

Sprawdzaj bieżącą konfigurację w sekcjach dashboardu **Przetestuj chatbota**, **Instalacja → Klucze i domeny** i **Instalacja → Instalacja na stronie**; upewnij się, że klucz, ustawienia originów i wygenerowany snippet dotyczą właściwego chatbota.

Najpierw przeanalizuj framework, model routingu, menedżer pakietów, konwencje zmiennych środowiskowych i trwały layout aplikacji. Przed edycją powiedz mi, które pliki planujesz zmienić. Zapytaj mnie, jeśli nie jest jasne, na których trasach ChattyBox ma się pojawić.

Wymagania:
1. Zainstaluj @openstaticfish/chattybox za pomocą menedżera pakietów używanego już przez to repozytorium.
2. Przechowuj publiczny klucz API i adres URL API zgodnie z konwencją zmiennych środowiskowych dostępnych w przeglądarce dla tego frameworka. Dodaj nazwy zastępcze do przykładowego pliku środowiskowego, ale nie commituj prawdziwych wartości.
3. Zaimportuj Chattybox z @openstaticfish/chattybox i utwórz jednego klienta z apiKey i baseUrl.
4. Wywołuj client.mountWidget() wyłącznie w kodzie przeglądarkowym, gdy istnieje `document.body`, z trwałego shella aplikacji. Widżet jest dodawany pod `document.body`, a nie wewnątrz komponentu.
5. Zachowaj loader podczas dozwolonej nawigacji SPA. SDK `0.1.4` zlicza odwołania tylko dla identycznych opcji montowania; przy zamierzonym teardownie wywołaj `remove()` na każdym zwróconym uchwycie. W hostowanym `widget.js` v15 ostatni uchwyt usuwa należący do widżetu interfejs i style oraz anuluje oczekującą inicjalizację, ponowienia i trwające żądanie czatu; `window.ChattyBox.destroy()` to odpowiednik po stronie hostowanego widżetu. Sprawdź, czy wdrożony loader obsługuje teardown. Nie uruchamiaj widżetu przed wymaganym uzyskaniem zgody ani na poufnych/prywatnych trasach; wykonaj teardown przy wykluczeniu trasy SPA lub cofnięciu zgody. Samo ukrycie UI lub usunięcie znacznika skryptu nie wystarcza. Teardown nie cofnie żądania już przetworzonego przez serwer.
6. Nie wstrzykuj ręcznie widget.js, nie twórz proxy backendowego ani drugiego loadera. SDK odrzuca zmieniony klucz, URL API, URL skryptu, locale lub opcję debugowania, dopóki nie zostaną usunięte wszystkie wcześniejsze uchwyty; nie zachowuje po cichu starych opcji.
7. Zachowaj istniejącą nawigację, granice renderowania, lokalizację, analitykę, zgody i style. Opcja locale SDK podlega polityce nadpisywania skryptowego projektu; SDK `0.1.4` nie ma reaktywnego API zmiany locale ani promise’a gotowości. Bieżące źródło hostowanego `widget.js` v16 może odświeżyć etykiety należące do produktu, gdy zmieni się rozpoznany locale; sprawdź wersję wdrożonego loadera przed poleganiem na tej odrębnej funkcji. Hostowany v15 może zaplanować maksymalnie 10 prób czatu w 30-sekundowym oknie ponawiania, ale nie jest to twardy limit czasu dla żądania już trwającego; headless sendMessage() nie ponawia automatycznie. SDK `0.1.4` waliduje baseUrl i opakowuje błędy odczytu treści odpowiedzi.
8. Wprowadź najmniejszą ukierunkowaną zmianę i nie wdrażaj jej.
9. Uruchom build, lint, sprawdzanie typów i odpowiednie testy repozytorium.
10. Podaj zmienione pliki, zmienne środowiskowe, które muszę ustawić, miejsce montowania interfejsu i sposób przetestowania go w wdrożonej witrynie.

Poniższy kod to przykładowa funkcja cyklu życia w przeglądarce, a nie wywołanie na najwyższym poziomie podczas renderowania po stronie serwera. Wywołaj ją dopiero po pojawieniu się document.body i zachowaj uchwyt do zamierzonego teardownu:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowserLifecycle() {
  if (typeof window === 'undefined' || typeof document === 'undefined' || !document.body) return null;
  return client.mountWidget();
}

// Wywołaj z dozwolonego cyklu życia w przeglądarce i zachowaj zwrócony uchwyt.

Zbuduj niestandardowy interfejs

Wybierz tę opcję, gdy aplikacja ma samodzielnie zarządzać listą wiadomości, polem wprowadzania, stanami ładowania, błędami, cytowaniami i rozmieszczeniem zamiast montować utrzymywany interfejs.

Polecenie

Zbuduj headless interfejs ChattyBox

Zbuduj niestandardowy interfejs chatbota, używając pakietu npm @openstaticfish/chattybox i jego klienta headless.

Publiczna konfiguracja przeglądarki:
- Klucz API: [PASTE PUBLIC WIDGET KEY]
- Adres URL API: [PASTE WIDGET API URL]

Klucz widżetu jest publiczny; ograniczenia originów są opcjonalnym dodatkowym zabezpieczeniem, a nie uwierzytelnianiem odwiedzających. Klucz przygotowany dla witryny może już być ograniczony — sprawdź ustawienia w **Instalacja → Klucze i domeny**. Wygenerowany snippet i adres URL API znajdziesz w **Instalacja → Instalacja na stronie**.

Najpierw przeanalizuj framework aplikacji, system komponentów, wzorce zarządzania stanem, style, konwencje dostępności i konfigurację testów. Przed edycją zaproponuj granice komponentów i pliki.

Wymagania:
1. Zainstaluj @openstaticfish/chattybox za pomocą istniejącego menedżera pakietów repozytorium.
2. Skonfiguruj jednego klienta Chattybox z apiKey i baseUrl za pomocą zmiennych środowiskowych dostępnych w przeglądarce; nie commituj prawdziwych wartości.
3. Użyj sendMessage() i przechowuj conversationId w stanie ograniczonym do odwiedzającego/sesji; resetuj go przy zmianie użytkownika lub sesji i nigdy nie współdziel go między niezwiązanymi odwiedzającymi. Przy tym samym ID model otrzymuje do 12 ostatnich zapisanych wiadomości, każdą przyciętą do 2 000 znaków — nie cały kontekst ani trwałą pamięć modelu. Publiczny klucz, ograniczenia originów i conversationId nie uwierzytelniają odwiedzających ani nie chronią prywatnych rozmów. Nie przesyłaj danych wrażliwych: wiadomości mogą być zapisane i widoczne dla właścicieli projektu; wyczyszczenie stanu lokalnego nie usuwa rekordów serwera.
4. Renderuj odpowiedzi bezpiecznie jako tekst lub oczyszczony Markdown. Źródła HTTP(S) renderuj jako dostępne linki i zachowaj ich kolejność. Nigdy nie wstawiaj niezaufanego surowego HTML ani niebezpiecznych schematów linków.
5. Zaimplementuj stany oczekiwania, pusty, błędu i ponowienia. Odpowiedzi fallback mogą mieć puste sources; nie istnieje ogólne pole wasAnswered. Jeśli backend zwróci providerError, bezpiecznie sprawdź opcjonalne pole i pokaż ogólny błąd dostawcy zamiast traktować go jak zwykłą odpowiedź; nie ponawiaj bezrefleksyjnie zakończonego żądania z kluczem idempotencji. Opublikowane SDK 0.1.4 może nie typować pól odpowiedzi dostępnych w bieżącym źródle — obsłuż ich brak. Obsłuż zarówno ChattyboxError, jak i nieopakowane błędy sieciowe; code jest opcjonalne.
6. Odrzucaj puste wiadomości oraz takie, których przycięta długość przekracza 2 000 znaków; zapobiegaj podwójnemu wysłaniu i zadbaj o klawiaturę oraz czytniki ekranu. Headless sendMessage() nie ponawia automatycznie: użyj jednego unikalnego idempotencyKey dla każdej logicznej wiadomości i przy ponowieniu użyj dokładnie tych samych danych wejściowych. Nie ponawiaj bezrefleksyjnie każdego 409. SDK 0.1.4 ponawia getWidgetConfig() tylko raz po HTTP 400; hostowany v15 osobno ponawia początkowe żądania GET.
7. Montuj interfejs tylko na trasach lub w layoucie, które wskażę.
8. Korzystaj z istniejących komponentów i stylów zamiast dodawać nowy system projektowy.
9. Nie ładuj widget.js ani nie wywołuj mountWidget().
10. Uruchom build, lint, sprawdzanie typów i odpowiednie testy, a następnie podaj zmienione pliki i plan weryfikacji.

Uwagi dotyczące frameworków

W razie potrzeby dodaj asystentowi jedno zdanie:

• Next.js App Router: „Użyj małego Client Componentu w trwałym layoucie i wywołuj mountWidget() w efekcie działającym wyłącznie w przeglądarce, nie podczas renderowania.”
• React SPA: „Montuj z trwałego shella aplikacji. Jeśli komponent zarządza ostatnim uchwytem SDK 0.1.4, zwracaj remove() w celu zamierzonego teardownu; w przeciwnym razie zachowaj współdzielony loader podczas zmian tras.”
• Docusaurus: „Inicjalizuj w kodzie przeglądarkowym z src/theme/Root i zachowaj loader podczas dozwolonej nawigacji dokumentacji. Zanim oprzesz się na zmianie języka po stronie klienta, sprawdź wersję wdrożonego hostowanego loadera i jego obsługę locale; zmiany konfiguracji dashboardu nadal wymagają ponownej inicjalizacji.”
• Vue, Nuxt, Svelte lub inny framework: „Użyj cyklu życia montowania po stronie klienta właściwego dla frameworka oraz odpowiadającego mu cyklu czyszczenia.”

Przejrzyj istniejącą integrację SDK

Polecenie

Przejrzyj moją integrację ChattyBox SDK

Przejrzyj tę integrację ChattyBox bez wdrażania i zmieniania niezwiązanego kodu.

Sprawdź, czy:
1. @openstaticfish/chattybox jest zainstalowany i zaimportowany zamiast powielania jego działania.
2. Jeden klient Chattybox otrzymuje właściwy publiczny klucz API i adres URL API.
3. Zmienne środowiskowe przeglądarki są zgodne z zasadami nazewnictwa publicznych zmiennych tego frameworka i nie ujawniają prywatnych danych uwierzytelniających.
4. Hostowany widżet używa trwałego shella i wywołuje remove() wyłącznie przy zamierzonym teardownie UI, wykluczeniu trasy po nawigacji SPA lub cofnięciu zgody. Niestandardowy interfejs ma prawidłowe czyszczenie komponentu.
5. Nawigacja po stronie klienta i ponowne montowanie podczas developmentu nie tworzą zduplikowanych instancji.
6. Istniejące granice renderowania, lokalizacja, analityka, zgody, dostępność i layout pozostają nienaruszone. Ograniczenia originów są opcjonalne, a nie uwierzytelniające; klucz przygotowany dla witryny może już być ograniczony. Dla ograniczonego klucza wymagany jest dozwolony origin żądania; Node fetch nie dodaje automatycznie nagłówków przeglądarkowych. Sprawdź, czy poufne trasy są wykluczone i czy cofnięcie zgody aktywnie wykonuje teardown, zamiast tylko ukrywać widżet.
7. Implementacja ma odpowiednie testy i nie zawiera niezwiązanego refaktoringu.

Zwróć ustalenia według ważności, podając ścieżki plików i odwołania do wierszy. Zaproponuj tylko najmniejsze bezpieczne poprawki i podaj dokładne polecenia weryfikacji.

Brak npm lub etapu budowania?

Skorzystaj z instrukcji instalacji widget.js tylko wtedy, gdy witryna nie może używać pakietu npm — na przykład w zwykłym HTML-u, polu własnego kodu CMS lub Google Tag Managerze.

Polecenie

Zainstaluj awaryjny skrypt widżetu

Zainstaluj hostowany widżet ChattyBox w tej witrynie, używając dokładnego skryptu wygenerowanego w widoku „Instalacja na stronie” w moim ChattyBoxie:

[PASTE COMPLETE WIDGET SCRIPT]

Najpierw przeanalizuj witrynę i wskaż najbezpieczniejsze miejsce wstawienia na stronach publicznych. Załaduj niezmieniony skrypt dokładnie raz i dopiero po uzyskaniu wymaganej zgody; wyklucz trasy prywatne, administracyjne i płatności. Przy zmianie trasy SPA lub cofnięciu zgody wykonaj teardown już zainicjalizowanego widżetu przed wejściem w stan wykluczenia i inicjalizuj go ponownie tylko wtedy, gdy jest to dozwolone. Sprawdź, czy wdrożony loader obsługuje teardown; samo ukrycie UI lub usunięcie znacznika skryptu nie wystarcza, a teardown nie cofnie żądań już przetworzonych. Zachowaj CSP, nie ujawniaj prywatnych danych uwierzytelniających ani tokenu wdrożeniowego, nie wdrażaj zmiany i podaj zmienione miejsce oraz plan testów w przeglądarce.

Przetestuj wynik

1. Przejrzyj diff i potwierdź, że nie commitowano prawdziwych danych uwierzytelniających.
2. Uruchom zwykły build, lint, sprawdzanie typów i testy projektu.
3. Wdróż zmianę w ramach standardowego procesu przeglądu.
4. Zweryfikuj zamierzone trasy w prywatnym oknie przeglądarki, w tym nawigację po stronie klienta.
5. Zadaj obsługiwane pytanie, przejdź do cytowania i przetestuj zachowanie odpowiedzi awaryjnych.
6. Sprawdź układ mobilny, obsługę klawiatury i konsolę przeglądarki.

Kontynuuj w dokumentacji SDK i liście kontrolnej przed uruchomieniem.