Chatbot AI w React - jak wdrożyć BetterCX krok po kroku

Chatbot AI w React - paczka bettercx-widget i klucz publiczny pk_

Jeśli Twoja strona lub aplikacja działa w czystym React, nie musisz budować własnego systemu czatu od zera. BetterCX udostępnia gotowy, produkcyjny widget czatu jako paczkę npm, której możesz użyć w swoim drzewie komponentów tak samo jak każdego innego komponentu React.

W praktyce sprowadza się to do kilku kroków: instalacji paczki bettercx-widget, pobrania klucza publicznego pk_... z panelu BetterCX, dodania domeny do dozwolonych originów i osadzenia komponentu BetterCXWidgetReact w aplikacji. Dzięki temu React staje się wygodną warstwą prezentacji, a cała “inteligencja” – AI, baza wiedzy, leady – dzieje się po stronie platformy BetterCX.

Dlaczego warto dodać chatbot AI do aplikacji React

Z punktu widzenia biznesu React jest tylko technologią – liczy się to, czy strona lub aplikacja faktycznie generuje rozmowy, leady i sprzedaż. Chatbot AI w React może:

• odpowiadać na pytania klientów w czasie rzeczywistym,
• przechwytywać leady bez konieczności wypełniania formularzy,
• odciążać zespół od powtarzalnych zapytań, zanim sprawa trafi do człowieka,
• zbierać kontekst rozmowy, który później widzi handlowiec lub support.

To szczególnie ważne na nowoczesnych stronach internetowych, landing page’ach i panelach klienta budowanych w React, gdzie ruch pochodzi z SEO, kampanii reklamowych i działań content marketingowych. Jeśli użytkownik trafia na stronę z intencją zakupową, dobrze osadzony widget może skrócić drogę od wejścia na stronę do rozmowy, kontaktu i leada.

Jak React różni się od Next.js czy WordPressa w kontekście wdrożenia

• W WordPressie najprostsza ścieżka to oficjalna wtyczka BetterCX – instalujesz plugin, wklejasz klucz publiczny i jesteś gotowy, bez ruszania motywu.

• W Next.js z App Routerem ważne są granice między Server i Client Components oraz dynamiczny import z ssr: false, tak jak opisano w dedykowanym poradniku dla Next.js.

• W czystym React integracja jest prostsza w czytaniu: instalujesz paczkę npm i wstawiasz BetterCXWidgetReact w drzewo komponentów, przekazując mu klucz publiczny.

Dla właściciela firmy oznacza to, że React daje najwięcej kontroli nad tym, gdzie w layoutcie pojawi się chat: możesz osadzić go tylko na części strony, tylko po zalogowaniu albo globalnie, w zależności od strategii produktu.

Co przygotować po stronie BetterCX zanim dotkniesz kodu

Zanim dodasz cokolwiek do kodu React, przygotuj podstawową konfigurację w panelu BetterCX:

• Konto BetterCX i projekt dla konkretnej strony lub aplikacji.
• Publiczny klucz widgetu pk_... z sekcji Widget.
• Domena frontendu na liście allowed origins – to nie formalność, tylko realny mechanizm bezpieczeństwa, który ogranicza, skąd widget może się łączyć.
• Działające HTTPS na froncie (wymagane przez współczesnych dostawców widgetów i przeglądarki).
• Przynajmniej podstawowe treści w bazie wiedzy – im konkretniej opiszesz ofertę, tym mniej „zgadywania” po stronie AI.

To jest minimalny scenariusz: klucz + domena + HTTPS + sensowna baza wiedzy. Jeśli pominiesz allowed origins albo HTTPS, widget może nie połączyć się poprawnie, nawet jeśli kod React będzie wyglądał dobrze.

Krok 1: zainstaluj paczkę npm bettercx-widget

Pierwszy krok po stronie kodu to instalacja paczki. Oficjalny pakiet BetterCX Widget jest dostępny na npm i według dokumentacji instalujesz go standardowo przez:

npm install bettercx-widget

Oficjalny listing: bettercx-widget na npm.

Paczka udostępnia produkcyjny, lekki widget czatu, zbudowany jako web component, który w React można wygodnie używać przez wrapper bettercx-widget/react.

W praktyce oznacza to, że nie musisz ręcznie wklejać <script> do index.html – korzystasz z komponentu React, który jest naturalną częścią drzewa JSX, co jest spójne z rekomendacjami innych dostawców widgetów dla React.

Krok 2: przechowuj klucz publiczny w zmiennej środowiskowej

Klucza pk_... nie warto wpisywać bezpośrednio w kodzie. Lepiej trzymać go w zmiennej środowiskowej bundlera (np. Vite, CRA, Next, Remix) – tak robi się też z innymi tokenami widgetów i API.

Przykład dla Vite:

VITE_BCX_PUBLIC_KEY=pk_TWOJ_KLUCZ

W Create React App możesz użyć np. REACT_APP_BCX_PUBLIC_KEY=..., a w innych bundlerach – odpowiedniego prefiksu dla zmiennych publicznych. Po zmianie env pamiętaj o restarcie dev servera, żeby bundler wciągnął nową wartość.

Dla mniej technicznego właściciela firmy taką zasadę łatwo streścić: klucz widgetu trzymamy w konfiguracji środowiska, a nie na sztywno w kodzie – dzięki temu łatwiej go zmienić i nie wycieka w repozytorium.

Krok 3: dodaj komponent BetterCXWidgetReact do drzewa aplikacji

Po zainstalowaniu paczki i ustawieniu zmiennej środowiskowej możesz dodać widget do aplikacji. Minimalny przykład z dokumentacji React usuwa zbędny szum i pokazuje dokładnie to, czego potrzebujesz w codziennej aplikacji:

import { BetterCXWidgetReact } from 'bettercx-widget/react';

export function App() {
  return (
    <BetterCXWidgetReact
      publicKey={process.env.VITE_BCX_PUBLIC_KEY!}
    />
  );
}

To jest wersja „hello world” – jeden komponent, jeden klucz publiczny. W realnym projekcie często:

• użyjesz innej nazwy zmiennej środowiskowej (np. REACT_APP_BCX_PUBLIC_KEY),

• osadzisz widget w komponencie layoutu, który otacza wszystkie widoki,

• dodasz warunek, żeby widget włączał się tylko na produkcji albo tylko w określonych sekcjach aplikacji.

Najważniejsze jest to, że widget jest normalnym komponentem React – możesz nim zarządzać tak jak resztą UI, bez wstrzykiwania ręcznych <script> do HTML.

Gdzie najlepiej osadzić widget w aplikacji React

Z poziomu UX i biznesu najlepiej potraktować widget jako globalny punkt kontaktu. W praktyce najczęściej robisz tak:

• w aplikacjach jednowidokowych (landing page) – wstawiasz BetterCXWidgetReact bezpośrednio w komponencie głównym (App),

• w większych aplikacjach (SaaS, panel klienta) – osadzasz widget w komponencie layoutu (np. MainLayout), który otacza router i wszystkie widoki.

Dzięki takiemu podejściu:

• użytkownik ma chat zawsze „pod ręką” – niezależnie od tego, która jest aktualnie ścieżka,
• widget nie unmountuje się przy każdej zmianie routingu (co mogłoby zrywać sesję rozmowy),
• zespół ma jeden, spójny punkt styku z klientem, a nie kilka oddzielnych integracji.

Jeśli z jakiegoś powodu chcesz pokazywać chat tylko w wybranych miejscach (np. tylko w części marketingowej, a nie w panelu), możesz zawinąć BetterCXWidgetReact w warunek np. po location.pathname albo stanie użytkownika (zalogowany/niezalogowany).

Panel BetterCX - co musisz mieć zanim pokażesz widget klientom

Z punktu widzenia biznesu sam kod React to tylko „ramka” – kluczowe jest to, jak skonfigurujesz projekt w BetterCX.

Przed uruchomieniem widgetu na produkcji upewnij się, że masz:

• Klucz publiczny z sekcji Widget – zaczyna się od pk_.
• Domenę frontu na liście allowed origins – to realny mechanizm bezpieczeństwa, który pilnuje, żeby widget łączył się tylko z dozwolonych domen.
• Treści w bazie wiedzy – im konkretniej opiszesz ofertę, proces współpracy i FAQ, tym mniej „zgadywania” po stronie AI.
• Podstawowe scenariusze sprzedażowo–obsługowe – jakie pytania zadać, kiedy przekazać rozmowę człowiekowi, jakie dane zebrać, zanim lead trafi do zespołu.

Dzięki temu od pierwszego dnia widget nie jest tylko ładnym dymkiem z AI – realnie odpowiada na pytania klientów i dowozi dane, z którymi może pracować handlowiec albo support.

Wygląd i zachowanie widgetu – konfiguracja bez nowego builda

Jedną z przewag rozwiązania SaaS jest to, że po osadzeniu komponentu w kodzie większość zmian możesz robić bez kolejnego builda frontu. Dokładnie tak działa BetterCX.

Kolory, powitanie i tryb jasny/ciemny ustawisz w konfiguracji widgetu, a nie w kodzie React. To znaczy, że:

• marketing może testować różne teksty powitalne bez proszenia developera o nowe wdrożenie,
• branding możesz zmienić w jednym miejscu, jeśli odświeżasz identyfikację wizualną,
• zachowanie widgetu (np. wiadomości wyzwalające na konkretnych podstronach) konfigurujesz z poziomu panelu.

Dokumentacja paczki BetterCX Widget podkreśla, że widget wspiera różne motywy (light, dark, auto) i tryby osadzenia, co pozwala dopasować go do istniejącego design systemu aplikacji.

Kiedy wybrać React zamiast samego skryptu HTML

W wielu przypadkach prosty skrypt HTML/JS wystarczy – zwłaszcza na prostych stronach typu landing page. React ma jednak kilka wyraźnych przewag:

• Masz design system i chcesz kontrolować dokładne miejsce montowania komponentu w layoutcie aplikacji.

• Budujesz produkt SaaS i chcesz, by chat był widoczny także po zalogowaniu, nie tylko na stronie marketingowej.

• Chcesz trzymać klucz w zmiennych środowiskowych bundlera i mieć spójny deployment w różnych środowiskach.

• Potrzebujesz w przyszłości głębszych integracji (np. warunkowego wyświetlania widgetu w zależności od stanu użytkownika).

Innymi słowy – jeśli chat ma być częścią produktu, a nie tylko pływającym dymkiem na landing page’u, React + bettercx-widget to bardziej przyszłościowa ścieżka niż sam <script> w HTML.

Najczęstsze błędy przy wdrożeniu BetterCX w React

Brak widgetu po uruchomieniu aplikacji

Najczęściej: brak zdefiniowanej publicznej zmiennej środowiskowej lub literówka w nazwie (np. VITE_BCX_PUBLIC_KEY), brak restarta dev servera po zmianie .env, albo brak dopasowanej domeny na liście allowed origins po stronie BetterCX.

Widget działa lokalnie, ale nie na produkcji

Tu zwykle winne są różnice między domeną lokalną a produkcyjną (inna domena niż na allowliście), albo klucz nadpisany różnymi wartościami w różnych środowiskach.

Widget montuje się na zbyt wielu widokach lub znika między trasami

Jeśli wstawisz go w komponent, który często unmountuje się przy zmianie trasy, możesz mieć efekt „migającego” widgetu lub zrywania rozmowy. Najbezpieczniej umieścić go wysoko – w głównym layoucie aplikacji – i ewentualnie sterować widocznością warunkowo.

AI odpowiada zbyt ogólnie

To nie jest problem kodu React ani widgetu, tylko bazy wiedzy. Jeśli nie wgrasz konkretnych treści (FAQ, ofert, cennika), model będzie siłą rzeczy mówił ogólnikowo. Rozwiązanie: dopracować Knowledge Bases i dopiero potem oceniać jakość odpowiedzi.

Często zadawane pytania

Czy do wdrożenia BetterCX w React potrzebuję programisty?

Tak, przynajmniej na etapie wstawienia komponentu do aplikacji i konfiguracji zmiennych środowiskowych. Sama konfiguracja po stronie BetterCX jest prosta, ale integracja z bundlerem i drzewem komponentów wymaga kogoś, kto ogarnia React.

Czy mogę po prostu wkleić <script> do index.html?

Technicznie tak, ale nie jest to najlepsza praktyka dla React. Pakiet bettercx-widget zapewnia wrapper React, który lepiej pasuje do architektury komponentowej i jest bardziej elastyczny przy sterowaniu miejscem montowania widgetu.

Czy muszę trzymać klucz publiczny w kodzie?

Nie. Najlepiej trzymać go w zmiennych środowiskowych bundlera (np. VITE_BCX_PUBLIC_KEY, REACT_APP_BCX_PUBLIC_KEY), co jest standardem przy integracji z zewnętrznymi widgetami i API.

Co najczęściej blokuje wdrożenie?

Najczęściej są to trzy rzeczy: brak allowed origins po stronie BetterCX, brak HTTPS albo błędnie ustawione zmienne środowiskowe (inna nazwa, brak restarta dev servera, inne wartości między lokalnym a produkcją).

Czy BetterCX działa tylko w React?

Nie. Ten sam widget można osadzić także w Next.js (App Router), na zwykłej stronie HTML/JS oraz na WordPressie (przez oficjalną wtyczkę). React jest po prostu jednym z wygodnych wariantów integracji.

Powiązane poradniki

Next.js (App Router), HTML i skrypt, WordPress (wtyczka).