Chatbot AI na Next.js (App Router) - BetterCX widget krok po kroku

Chatbot AI na Next.js (App Router) – jak wdrożyć BetterCX krok po kroku

Jeśli Twoja strona działa na Next.js, możesz dodać chatbota AI BetterCX bez budowania własnego systemu czatu od zera. W praktyce sprowadza się to do trzech rzeczy: pobrania klucza publicznego pk_... z panelu BetterCX, dodania domeny do dozwolonych originów i osadzenia widgetu po stronie klienta w aplikacji Next.js.

To ważne, bo w App Routerze Next.js wiele komponentów renderuje się domyślnie po stronie serwera, a komponenty interaktywne powinny być oznaczone jako Client Components przez dyrektywę 'use client'. Dodatkowo ssr: false w next/dynamic nie jest wspierane w Server Components, więc taki widget trzeba umieścić w komponencie klientowym, a nie serwerowym.

Dlaczego warto dodać chatbot AI do strony Next.js

Dla właściciela firmy technologia ma znaczenie tylko wtedy, gdy wspiera sprzedaż i obsługę klienta. Chatbot AI na stronie Next.js może odpowiadać od razu, przechwytywać leady bez dodatkowego formularza i odciążać zespół od prostych pytań, zanim rozmowa trafi do handlowca lub supportu.

To szczególnie ważne na nowoczesnych stronach marketingowych i landing page’ach budowanych w Next.js, gdzie ruch często pochodzi z SEO, kampanii reklamowych i content marketingu. Jeśli użytkownik trafia na stronę z intencją zakupową, szybka odpowiedź i dobrze osadzony widget mogą skrócić drogę od wejścia na stronę do rozmowy, kontaktu i leada.

Czym różni się wdrożenie na Next.js od WordPressa

W WordPressie najprostsza ścieżka to oficjalna wtyczka, która pozwala uruchomić widget bez pracy na kodzie motywu, a sama instalacja przypomina zwykły plugin WordPress. W Next.js sytuacja wygląda inaczej, bo tu nie instalujesz klasycznej wtyczki, tylko osadzasz komponent React w aplikacji i musisz pilnować, żeby nie renderował się po stronie serwera.

To nie oznacza, że wdrożenie jest trudne. Oznacza tylko, że technicznie trzeba zrobić to poprawnie: użyć komponentu klientowego, dynamicznego importu z wyłączonym SSR i zmiennej środowiskowej NEXT_PUBLIC_BCX_PUBLIC_KEY, zamiast wklejać klucz na sztywno w kodzie.

Co przygotować przed wdrożeniem BetterCX w Next.js

Zanim przejdziesz do kodu, przygotuj podstawową konfigurację po stronie BetterCX:

• konto BetterCX,

• projekt dla konkretnej strony,

• publiczny klucz widgetu pk_... z panelu Widget,

• dodaną domenę strony do dozwolonych originów,

• działające HTTPS na stronie.

To jest minimalny scenariusz wdrożenia: klucz + domena + poprawne osadzenie komponentu. Jeśli pominiesz dozwolone originy albo HTTPS, widget może się nie połączyć poprawnie, nawet jeśli sam kod będzie wyglądał poprawnie.

Krok 1: pobierz klucz publiczny pk_... i ustaw dozwolone originy

Najpierw zaloguj się do BetterCX i przejdź do sekcji Widget. To właśnie tam znajdziesz publiczny klucz widgetu, który służy do połączenia Twojej strony z projektem BetterCX.

Następnie dodaj domenę swojej strony do listy dozwolonych originów. Jeśli pracujesz osobno na produkcji i stagingu, dodaj obie domeny osobno, bo w przeciwnym razie przeglądarka może zablokować sesję widgetu lub połączenie z usługą.

Na tym etapie dobrze też upewnić się, że strona działa po HTTPS. W dokumentacji BetterCX brak HTTPS jest wskazany jako jedna z najczęstszych przyczyn błędów połączenia przy wdrożeniach webowych.

Krok 2: zainstaluj paczkę npm BetterCX Widget

To jest element, którego zdecydowanie warto nie pomijać w poradniku. Jeśli wdrażasz BetterCX w Next.js, najpierw instalujesz oficjalną paczkę npm:

Oficjalny pakiet znajdziesz tutaj: bettercx-widget na npm. Dokumentacja npm pokazuje, że rekomendowana ścieżka dla React polega właśnie na instalacji bettercx-widget, a następnie imporcie komponentu z bettercx-widget/react.

To rozwiązanie jest wygodne i uporządkowane, bo nie opierasz się na ręcznym osadzaniu zewnętrznego skryptu w aplikacji React. Zamiast tego korzystasz z utrzymywanego wrappera React, który lepiej pasuje do architektury Next.js.

Krok 3: dodaj zmienną środowiskową w Next.js

W Next.js najlepiej nie wpisywać klucza pk_... bezpośrednio do komponentu. W dokumentacji wdrożeniowej BetterCX zalecane jest użycie zmiennej środowiskowej NEXT_PUBLIC_BCX_PUBLIC_KEY w pliku .env.local lub .env.

Przykład:

NEXT_PUBLIC_BCX_PUBLIC_KEY=pk_TWOJ_KLUCZ

To rozwiązanie jest wygodniejsze organizacyjnie, bo nie commitujesz wartości na sztywno do repozytorium, a przy wdrożeniu produkcyjnym możesz ustawić tę samą zmienną u dostawcy hostingu, np. w Vercel. Po zmianie env trzeba też zrestartować lokalny serwer developerski, bo bez restartu Next.js może nie wczytać nowej zmiennej poprawnie.

Krok 3: utwórz komponent klientowy dla widgetu

W App Routerze Next.js komponenty są domyślnie renderowane po stronie serwera, a dyrektywa 'use client' wyznacza granicę, od której komponent ma być renderowany po stronie klienta. To ważne, bo widget BetterCX jest interaktywny i powinien działać w przeglądarce, a nie na serwerze.

Do tego dochodzi dynamiczny import. Oficjalna dokumentacja Next.js pokazuje, że ssr: false służy do wyłączenia renderowania po stronie serwera dla komponentów, których nie potrzebujesz na serwerze. Jednocześnie dokumentacja App Routera podkreśla, że ssr: false nie może być użyte w Server Components i trzeba przenieść taki kod do Client Component.

Poniżej masz bezpieczny, minimalny wzorzec osadzenia widgetu BetterCX dla Next.js App Router, zgodny z wytycznymi z dokumentu wdrożeniowego:

'use client';

import dynamic from 'next/dynamic';

const BetterCXWidgetReact = dynamic(
  () =>
    import('bettercx-widget/react').then((mod) => ({
      default: mod.BetterCXWidgetReact,
    })),
  { ssr: false, loading: () => null }
);

export function Widget() {
  const publicKey = process.env.NEXT_PUBLIC_BCX_PUBLIC_KEY ?? '';

  if (!publicKey) {
    return null;
  }

  return <BetterCXWidgetReact publicKey={publicKey} />;
}

Ten wzorzec realizuje dokładnie to, czego potrzebujesz w Next.js: komponent jest klientowy dzięki 'use client', a sam widget jest ładowany dynamicznie z wyłączonym SSR.

Krok 4: podepnij widget globalnie w layoucie

Kiedy masz już gotowy komponent Widget, dodaj go do głównego layoutu aplikacji. W dokumentacji BetterCX rekomendacja jest prosta: osadź widget raz, globalnie, tak aby był dostępny w całej aplikacji lub na całej stronie marketingowej.

To ważne z dwóch powodów. Po pierwsze, użytkownik widzi spójny punkt kontaktu na wszystkich podstronach. Po drugie, unikasz sytuacji, w której widget montuje się i znika między trasami, bo został umieszczony zbyt nisko w drzewie komponentów.

Dla zespołu biznesowego można to opisać bardzo prosto: zamiast dodawać chat osobno na każdą podstronę, wstawiasz go raz w głównym layoucie, a BetterCX działa globalnie.

Krok 5: uzupełnij bazę wiedzy, żeby AI odpowiadało sensownie

Samo osadzenie widgetu to dopiero połowa wdrożenia. Dokument wdrożeniowy BetterCX wprost podkreśla, że warto uzupełnić bazę wiedzy, bo wtedy AI odpowiada na podstawie Twoich faktów, a nie w trybie „ogólnej pogawędki”.

Dla strony w Next.js najczęściej warto dodać do bazy wiedzy:

• podstrony ofertowe,

• FAQ,

• opisy usług,

• blog,
• informacje o wdrożeniu, cenniku i procesie współpracy.

To jest moment, w którym chatbot przestaje być samym widżetem, a zaczyna działać jako realne wsparcie sprzedaży i obsługi. Im lepiej opiszesz swoją ofertę i najczęstsze pytania, tym lepsze odpowiedzi dostaną użytkownicy, którzy trafiają na stronę z Google, reklam lub poleceń.

Krok 6: skonfiguruj widget pod konwersję, nie tylko pod wygląd

Po wdrożeniu kodu warto od razu przejść do konfiguracji widgetu, gdzie ustawisz powitanie, kolory i tryb jasny lub ciemny. W dokumentacji BetterCX ta sekcja jest wskazana jako główne miejsce do konfiguracji wyglądu i zachowania widgetu bez dalszego dotykania kodu aplikacji.

Z punktu widzenia konwersji warto dopracować przede wszystkim:

• pierwszą wiadomość powitalną,
• ton komunikacji,
• kolory zgodne z brandingiem,
• link do polityki prywatności,
• widoczność widgetu na kluczowych podstronach.

To są małe zmiany, ale mają duże znaczenie biznesowe. Na landing page’u użytkownik musi od razu rozumieć, po co ma kliknąć w chat i jaką korzyść dostanie: szybką odpowiedź, pomoc w wyborze oferty, kontakt z zespołem albo możliwość umówienia rozmowy.

Krok 7: sprawdzaj rozmowy, leady i strony, które naprawdę pracują

Po wdrożeniu warto patrzeć nie tylko na to, czy widget się wyświetla, ale też na to, co realnie dzieje się dalej. W BetterCX znajdziesz sekcje Chat i Analityka, które pomagają sprawdzić, skąd biorą się rozmowy i gdzie zespół powinien przejmować kontakt od AI.

To ważne z perspektywy SEO i CRO. Jeśli widzisz, że konkretne podstrony generują rozmowy, to właśnie tam warto wzmacniać treść, dopracowywać nagłówki, dodawać mocniejsze CTA i lepiej linkować wewnętrznie. W praktyce chatbot staje się więc nie tylko kanałem kontaktu, ale też źródłem wiedzy o tym, które strony realnie pracują na leady.

Najczęstsze błędy przy wdrożeniu BetterCX na Next.js

Najczęstsze problemy są dość powtarzalne i dobrze opisane zarówno w dokumentacji BetterCX, jak i w dokumentacji Next.js.

Brak widgetu po wdrożeniu

Najczęściej problemem jest brak NEXT_PUBLIC_BCX_PUBLIC_KEY, brak restartu serwera po zmianie env albo brak dozwolonej domeny po stronie BetterCX.

Problemy z hydration lub SSR

Jeśli próbujesz wstawić widget bez dynamic(..., { ssr: false }) albo bez klientowego wrappera, możesz wejść w klasyczne problemy App Routera, bo ssr: false nie jest wspierane w Server Components.

Widget działa lokalnie, ale nie na produkcji

To zwykle oznacza problem z domeną na allowliście, błędny klucz albo brak HTTPS.

Widget znika przy przejściach między trasami

To zazwyczaj znak, że komponent został umieszczony zbyt nisko w drzewie aplikacji, zamiast globalnie w layoucie.

Dlaczego ten wpis jest ważny także dla mniej technicznego właściciela firmy

Nawet jeśli nie piszesz kodu samodzielnie, dobrze rozumieć, co ma zrobić developer lub software house. W przypadku BetterCX dla Next.js cały proces można sprowadzić do prostego briefu:

1. pobierz klucz pk_... z BetterCX,
2. dodaj domenę do originów,
3. ustaw NEXT_PUBLIC_BCX_PUBLIC_KEY,
4. osadź klientowy komponent widgetu z dynamic import i ssr: false,
5. uzupełnij bazę wiedzy i konfigurację widgetu.

To ważne, bo dzięki temu rozmawiasz z developerem o konkretnych krokach, a nie o abstrakcyjnym „wdrożeniu AI na stronie”. Dla biznesu liczy się efekt: chatbot działa, odpowiada sensownie, przechwytuje rozmowy i wspiera konwersję.

Dla kogo wdrożenie BetterCX w Next.js ma największy sens

Ten model wdrożenia najlepiej sprawdzi się, jeśli:

• masz stronę marketingową albo landing page w Next.js,
• zależy Ci na szybkich odpowiedziach dla odwiedzających,
• chcesz zbierać leady bez dokładania kolejnego formularza,
• chcesz poprawić konwersję z ruchu SEO i kampanii,
• planujesz rozwijać stronę bez uzależniania się od ciężkiego, customowego rozwiązania czatowego.

To szczególnie dobry scenariusz dla SaaS‑ów, firm usługowych, startupów i nowoczesnych stron firmowych, gdzie Next.js jest już podstawowym stackiem marketingowym, a chatbot ma być praktycznym narzędziem do sprzedaży i obsługi.

Często zadawane pytania

Czy do wdrożenia BetterCX na Next.js potrzebuję programisty?

W praktyce tak, przynajmniej na poziomie osadzenia komponentu w aplikacji. Sama konfiguracja po stronie BetterCX jest prosta, ale poprawne dodanie widgetu w App Routerze wymaga klientowego komponentu i dynamic import z wyłączonym SSR.

Czy mogę zrobić zwykły import widgetu?

Nie jest to zalecana ścieżka dla App Routera. Widget powinien być ładowany po stronie klienta, a ssr: false trzeba umieścić w komponencie klientowym, bo nie jest wspierane w Server Components.

Czy muszę trzymać klucz publiczny w kodzie?

Nie. Dokumentacja BetterCX rekomenduje użycie zmiennej środowiskowej NEXT_PUBLIC_BCX_PUBLIC_KEY, co jest wygodniejsze i bezpieczniejsze organizacyjnie.

Co najczęściej blokuje wdrożenie?

Najczęściej są to trzy rzeczy: brak allowed origins, brak HTTPS albo brak restartu serwera po dodaniu zmiennej środowiskowej.

Czy BetterCX działa tylko na Next.js?

Nie. Ten sam dokument wdrożeniowy opisuje też wdrożenie dla WordPressa, zwykłego HTML/JS i Reacta. Dla WordPressa BetterCX ma nawet oficjalną wtyczkę dostępną w katalogu WordPress.org.

Powiązane poradniki

Ten sam widget na innych stackach: React (npm), HTML i skrypt, WordPress (wtyczka).