Chatbot w React: jak dodać chatbota AI do aplikacji React (Vite, CRA, SPA)

Zanim dotkniesz kodu, potrzebujesz dwóch rzeczy:

• Konto Nexoply i klucz Twojego chatbota. Zarejestruj się za darmo (plan Darmowy obejmuje 50 rozmów miesięcznie, bez karty), a potem otwórz stronę Chatbot w panelu. Znajdujący się tam kod instalacyjny zawiera już Twój klucz. Klucz jest publiczny: nie jest tajny i nie daje dostępu do konta, więc może bez problemu trafić do kodu po stronie klienta.
• Informacje o firmie, na podstawie których odpowiada asystent: usługi i ceny, FAQ, zasady, godziny otwarcia i obszary działania. Najszybciej jest podać adres strony i pozwolić Nexoply zaimportować publiczne podstrony, także te zbudowane w JavaScripcie, więc strona w React również się nada. Nic nie zostanie dodane, dopóki tego nie zatwierdzisz.

Utwórz plik src/components/Chatbot.tsx. Komponent sam niczego nie renderuje: dodaje skrypt Nexoply do strony jeden raz, a przycisk i okno czatu rysuje widżet.

// src/components/Chatbot.tsx
import { useEffect } from "react";

type ChatbotProps = { chatbotKey: string };

export function Chatbot({ chatbotKey }: ChatbotProps) {
  useEffect(() => {
    // Brak klucza albo skrypt jest już na stronie: nie ma nic do zrobienia.
    if (!chatbotKey || document.querySelector("script[data-chatbot]")) return;
    const s = document.createElement("script");
    s.src = "https://nexoply.com/widget.js";
    s.async = true;
    s.dataset.chatbot = chatbotKey;
    document.body.appendChild(s);
  }, [chatbotKey]);

  return null;
}

Wyrenderuj go raz, w komponencie, który pozostaje zamontowany przez całą wizytę (zwykle App). W Vite wpisz VITE_NEXOPLY_KEY=YOUR-KEY do pliku .env:

// src/App.tsx
import { Chatbot } from "./components/Chatbot";

export default function App() {
  return (
    <>
      {/* Twój layout i trasy */}
      <Chatbot chatbotKey={import.meta.env.VITE_NEXOPLY_KEY} />
    </>
  );
}

Komponent działa bez zmian w projekcie TypeScript z Vite lub Create React App. W czystym JavaScripcie nazwij plik Chatbot.jsx i usuń typ ChatbotProps. Create React App nie ma import.meta.env: przekaż zamiast tego process.env.REACT_APP_NEXOPLY_KEY. Ponieważ to zwykły komponent, możesz też renderować go warunkowo, na przykład {hasConsent && <Chatbot chatbotKey={key} />}, aby ładować czat dopiero po zaakceptowaniu przez odwiedzającego banera cookie.

• Dlaczego nie ma funkcji czyszczącej. Widżet nie ma API do usunięcia go po załadowaniu i działa poza Twoim drzewem React, więc odmontowanie komponentu nie musi niczego cofać.
• Dlaczego StrictMode nie przeszkadza. W trybie deweloperskim React StrictMode uruchamia efekty dwukrotnie. Sprawdzenie querySelector pomija drugie uruchomienie, a nawet gdyby skrypt został dodany dwa razy, widżet montuje się tylko raz na klucz chatbota. Z tego samego powodu bezpieczny jest hot reload.
• Zachowaj atrybut. Widżet odczytuje ustawienia z własnego tagu script, więc tag musi mieć atrybut data-chatbot i src zawierający widget.js. Ustawienie s.dataset.chatbot tworzy ten atrybut.

Jeśli nie musisz sterować ładowaniem z poziomu kodu, pomiń komponent. Każda aplikacja SPA w React ma szkielet HTML: w Vite to index.html w katalogu głównym projektu, w Create React App to public/index.html. Wklej kod tuż przed zamykającym znacznikiem </body>:

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>

  <!-- Chatbot AI Nexoply -->
  <script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>
</body>

Zastąp YOUR-KEY kluczem ze strony Chatbot. Skrypt ładuje się asynchronicznie, więc nigdy nie blokuje renderowania Twojej aplikacji. Dodaj do tagu data-open="true", jeśli chcesz, aby okno czatu otwierało się po załadowaniu strony. To cała instalacja: zbuduj aplikację, wdróż ją, a przycisk pojawi się na każdej trasie.

Wyszukiwanie hasła „chatbot React” zwraca dwa rodzaje narzędzi, które rozwiązują różne problemy:

• Biblioteka UI do chatbota daje Ci komponenty React dla samego czatu: listę wiadomości, pole tekstowe, dymki, czasem zaprogramowane kroki rozmowy. Wszystko za interfejsem budujesz sam: stałe scenariusze albo backend, który wywołuje model AI z Twoim własnym kluczem API, a do tego treści, na podstawie których odpowiada, przechowywanie rozmów i ochronę przed nadużyciami. Sprawdza się, gdy czat jest częścią Twojego produktu, na przykład asystent pracujący na danych Twoich użytkowników.
• Hostowany chatbot AI, taki jak Nexoply, dostarcza interfejs, AI i backend razem. Odpowiada na pytania odwiedzających tylko na podstawie dodanych lub zaimportowanych przez Ciebie informacji o firmie (usługi i ceny, FAQ, zasady, godziny otwarcia) i mówi, gdy czegoś nie wie. Nie ma klucza AI ani kodu serwerowego; rozmowy, pytania bez odpowiedzi i ochrona przed spamem są obsługiwane w panelu. Sprawdza się na stronie dla klientów, która ma odpowiadać na pytania o firmę.

Jeśli chcesz mieć pełną kontrolę nad interfejsem i modelem, zacznij od biblioteki. Jeśli celem jest odpowiadanie na pytania odwiedzających bez budowania i utrzymywania backendu, hostowany widżet wymaga mniej pracy. Zobacz, jak Nexoply odpowiada na podstawie informacji o Twojej firmie.

• Pozostaje poza Twoim drzewem React. Widżet montuje się w document.body, poza elementem #root, więc ponowne renderowania i zmiany tras nigdy go nie usuwają ani nie zmieniają jego stylów.
• Shadow DOM w obie strony. Twój CSS (Tailwind, moduły CSS, globalne resety) nie przenika do czatu, a jego CSS nie przenika do Twojej aplikacji.
• Zmiany tras po prostu działają. Z React Router lub dowolnym routerem opartym na historii odwiedzający zachowują rozmowę podczas nawigacji, a reguły stron (np. zakładka boczna tylko na /pricing) są sprawdzane ponownie przy zmianie adresu URL. Bez dodatkowego kodu.
• Bez plików cookie. Widżet przechowuje anonimowy identyfikator odwiedzającego w localStorage, a bieżącą rozmowę w sessionStorage.

Chcesz mieć przycisk „Napisz do nas” w sekcji hero albo na stronie z cennikiem? Wyślij zdarzenie nexoply:open-chat na obiekcie window:

export function ChatButton() {
  return (
    <button onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}>
      Napisz do nas
    </button>
  );
}

Nie wymaga to żadnego importu: widżet nasłuchuje tego zdarzenia na window. Jeśli wolisz pokazywać tylko własny przycisk, ustaw w panelu przycisk czatu na „Bez przycisku” za pomocą reguły strony.

Przed wdrożeniem sprawdź te trzy ustawienia:

• Dozwolone strony. Jeśli wypełniono pole Zezwalaj tylko na tych stronach (panel → Chatbot), dodaj swój host deweloperski z portem, np. localhost:5173 dla Vite lub localhost:3000 dla Create React App, albo zostaw listę pustą na czas testów.
• Content-Security-Policy. Jeśli Twoja aplikacja wysyła nagłówek lub meta tag CSP, zezwól na https://nexoply.com w script-src, connect-src i img-src.
• Sprawdź całość od początku do końca. Uruchom aplikację, kliknij przycisk czatu, zadaj prawdziwe pytanie i znajdź je w sekcji Rozmowy w panelu.

Jeśli przycisk nadal się nie pojawia:

• Pusty klucz. Bez klucza komponent niczego nie ładuje. Wypisz w konsoli import.meta.env.VITE_NEXOPLY_KEY: Vite udostępnia tylko zmienne zaczynające się od VITE_, a po edycji .env trzeba zrestartować serwer deweloperski.
• Zablokowane żądanie. Sprawdź w konsoli przeglądarki i na karcie Network, czy nie ma błędów CSP lub zablokowanego pliku widget.js.
• Chatbot wyłączony. Sprawdź, czy przełącznik Chatbot włączony jest włączony.
• Blokery reklam. Rzadko zdarza się, że rozszerzenie przeglądarki blokuje widżety czatu. Spróbuj w oknie prywatnym bez rozszerzeń.

Gdy skrypt jest już na miejscu, nie musisz więcej zmieniać kodu: zmiany wprowadzone w panelu pojawiają się na stronie w ciągu około minuty. W sekcji Chatbot → Personalizacja możesz dopasować przycisk czatu (ikona lub własny obrazek albo SVG, etykieta tekstowa, kształt, rozmiar, kolory, położenie) albo zamiast niego użyć zakładki bocznej przy krawędzi ekranu. Ustaw inny wygląd na telefonach i użyj reguł stron, aby zmienić go na wybranych trasach (np. /pricing lub /services/*). Okno czatu przyjmuje Twoje czcionki, kolory i logo, a ekran startowy może oferować przyciski takie jak Rezerwacja, Telefon czy WhatsApp.

Korzystasz z innego frameworka? Zobacz, jak dodać chatbota do Next.js za pomocą next/script, albo poradnik chatbota dla Vue i Nuxt; dla strony firmowej na WordPressie zajrzyj do poradnika WordPress. Pełny obraz znajdziesz w opisie, jak asystent poznaje Twoją firmę, a plany możesz porównać wraz z limitami rozmów.