Next.js-Chatbot: einen KI-Chatbot mit next/script einbauen (App Router und Pages Router)

• Ein Nexoply-Konto. Registrieren Sie sich kostenlos: Der kostenlose Tarif umfasst 50 Unterhaltungen pro Monat, ohne Kreditkarte.
• Die Informationen des Unternehmens in Nexoply: Leistungen und Preise, FAQs, Richtlinien, Öffnungszeiten und Einsatzgebiete. Am schnellsten geben Sie die Adresse der Website ein und lassen Nexoply die öffentlichen Seiten importieren (auch Seiten, die mit JavaScript gerendert werden); Sie prüfen die Vorschläge, und nichts wird übernommen, bevor Sie es freigeben.
• Ihren Chatbot-Schlüssel. Öffnen Sie im Dashboard Chatbot (klicken Sie auf Chatbot erstellen, falls noch nicht geschehen). Der Installationscode dort enthält den Schlüssel im Attribut data-chatbot.

Bei einer reinen HTML-Website würden Sie den Installationscode einfach vor </body> einfügen:

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

In Next.js bearbeiten Sie HTML nicht direkt, deshalb fügen Sie dasselbe Script stattdessen mit der eingebauten Komponente next/script hinzu. Der Schlüssel ist öffentlich: Er sagt dem Widget nur, zu welchem Unternehmen es gehört.

Das Root-Layout umschließt jede Seite, ein Script dort bringt den Chat also auf die gesamte Website. Importieren Sie Script aus next/script und setzen Sie es innerhalb von <body> nach {children}:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Nexoply-Chat-Widget: lädt im Browser nach der Hydration */}
        <Script
          src="https://nexoply.com/widget.js"
          data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Legen Sie den Schlüssel dann in einer Umgebungsvariablen ab. Durch das Präfix NEXT_PUBLIC_ nimmt Next.js ihn in das Browser-Bundle auf, was hier in Ordnung ist, weil der Schlüssel kein Geheimnis ist:

# .env.local (wird nicht in git eingecheckt)
NEXT_PUBLIC_NEXOPLY_KEY=YOUR-KEY

Im Pages Router umschließt pages/_app.tsx jede Seite, dasselbe <Script> kommt also dorthin, neben <Component {...pageProps} />. Verwenden Sie dieselbe Variable aus .env.local:

// pages/_app.tsx
import type { AppProps } from "next/app";
import Script from "next/script";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://nexoply.com/widget.js"
        data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
        strategy="afterInteractive"
      />
    </>
  );
}

Wenn Ihr Projekt beide Router nutzt, fügen Sie das Script sowohl in app/layout.tsx als auch in pages/_app.tsx ein. Doppeltes Laden schadet nicht: Das Widget wird pro Chatbot-Schlüssel nur einmal gemountet.

Sie bevorzugen eine <Chatbot />-Komponente wie in der Anleitung zur React-Chatbot-Komponente? Verschieben Sie das Script in eine eigene Datei. next/script funktioniert in Server Components, solange Sie keine Event-Handler wie onLoad übergeben, diese Datei braucht also kein "use client":

// components/Chatbot.tsx
import Script from "next/script";

export function Chatbot() {
  return (
    <Script
      src="https://nexoply.com/widget.js"
      data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
      strategy="afterInteractive"
    />
  );
}

Rendern Sie <Chatbot /> dann innerhalb von <body> in app/layout.tsx nach {children} oder neben <Component {...pageProps} /> in pages/_app.tsx. Rendern Sie die Komponente im Layout, nicht auf einer einzelnen Seite, damit sie auf jeder Route geladen wird.

strategy="afterInteractive" lädt das Widget direkt, nachdem die Seite interaktiv geworden ist, der Chat-Button erscheint also schnell. strategy="lazyOnload" wartet, bis der Browser im Leerlauf ist und alles andere geladen hat; wählen Sie diese Option, wenn der erste Ladevorgang so leicht wie möglich sein soll und es Sie nicht stört, dass der Button einen Moment später erscheint. Beide halten das Script aus dem kritischen Rendering-Pfad heraus. Details finden Sie in der Dokumentation zu next/script.

• Clientseitige Navigation. Das Widget hält die Unterhaltung offen, während Besucher mit <Link> oder dem Router zwischen Seiten wechseln, und prüft Ihre Seitenregeln bei einer URL-Änderung neu, ohne zusätzlichen Code.
• Sicher bei SSR und Hydration. Es läuft nur im Browser und wird an document.body angehängt, außerhalb des Markups, das React hydriert, und verursacht daher nie Hydration-Mismatches.
• Shadow DOM. Ihr Tailwind- oder globales CSS wirkt nicht in den Chat hinein, und seine Styles wirken nicht in Ihre App hinein. Re-Renders entfernen es nie.
• StrictMode und Fast Refresh. Doppelt ausgeführte Effects in der Entwicklung oder Hot Reloads können keinen zweiten Chat erzeugen: Das Widget wird pro Schlüssel einmal gemountet.
• Speicher. Es setzt keine Cookies; es nutzt localStorage für eine anonyme Besucher-ID und sessionStorage für die aktuelle Unterhaltung.

Mit Next.js lässt sich ein eigener Chatbot gut bauen, und manchmal ist das die richtige Entscheidung. Die beiden Ansätze passen zu unterschiedlichen Aufgaben:

• Selbst bauen mit einer Chat-UI-Bibliothek oder eigenen Komponenten, dazu ein Route Handler oder eine API-Route, die ein KI-Modell mit Ihrem eigenen API-Schlüssel aufruft. Die Inhalte, aus denen er antwortet, die Speicherung der Unterhaltungen und den Schutz vor Missbrauch verantworten Sie ebenfalls selbst. Das passt, wenn der Chat Teil Ihres Produkts ist, etwa ein Assistent, der mit den eigenen Daten Ihrer Nutzer arbeitet.
• Ein gehosteter KI-Chatbot wie Nexoply liefert Oberfläche, KI und Backend zusammen. Er beantwortet die Fragen der Besucher nur mit den Unternehmensinformationen, die Sie hinzufügen oder importieren (Leistungen und Preise, FAQs, Richtlinien, Öffnungszeiten), und sagt es, wenn er etwas nicht weiß. Es gibt keinen KI-Schlüssel, und auf Ihrem Server läuft nichts; Unterhaltungen, unbeantwortete Fragen und Spamschutz verwalten Sie im Dashboard. Das passt zu einer Website für Kunden, die Fragen zum Unternehmen beantworten soll.

Wenn Sie volle Kontrolle über Oberfläche und Modell wollen, bauen Sie selbst. Wenn es darum geht, Fragen von Besuchern zu beantworten, ohne ein Backend zu betreiben, macht das gehostete Widget weniger Arbeit. Lesen Sie, wie Nexoply mit Ihren Unternehmensinformationen antwortet.

Sie möchten einen Button „Chatten Sie mit uns“ im Hero- oder Preisbereich? Lösen Sie das Event nexoply:open-chat auf window aus. Da dafür onClick nötig ist, muss es eine Client Component sein:

"use client";
// components/ChatButton.tsx

export function ChatButton() {
  return (
    <button
      type="button"
      // öffnet das Nexoply-Chatfenster
      onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}
    >
      Chatten Sie mit uns
    </button>
  );
}

Verwenden Sie <ChatButton /> in jeder Seite oder Server Component. Es gibt keine API, um das Widget nach dem Laden zu entfernen: Um den Chat-Button auf einzelnen Seiten auszublenden (zum Beispiel /checkout), fügen Sie unter Chatbot → Anpassen → Chat-Button → Anders auf einzelnen Seiten eine Seitenregel mit „Kein Button“ hinzu.

Starten Sie next dev, öffnen Sie http://localhost:3000, und in der Ecke erscheint ein Chat-Button. Stellen Sie eine echte Frage, etwa „Arbeiten Sie auch am Wochenende?“; innerhalb von Sekunden erscheint die Unterhaltung im Dashboard unter Unterhaltungen. Änderungen im Dashboard erreichen die Website innerhalb von etwa einer Minute, ohne neues Deployment.

Wenn Ihre App einen Content-Security-Policy-Header sendet (zum Beispiel aus Middleware oder next.config), erlauben Sie Nexoply in:

• script-src https://nexoply.com: zum Laden von widget.js.
• connect-src https://nexoply.com: für die Anfragen des Chats.
• img-src https://nexoply.com: für Bilder wie das Logo und das Button-Symbol.

• Kein Button, und data-chatbot ist im Seitenquelltext leer. Die Umgebungsvariable wurde nicht gelesen: Prüfen Sie das Präfix NEXT_PUBLIC_, starten Sie next dev neu und legen Sie die Variable bei Ihrem Hoster an und deployen Sie neu.
• Das Script steht auf einer einzelnen Seite statt im Layout. Setzen Sie es in app/layout.tsx oder pages/_app.tsx, damit es auf jeder Route lädt.
• Der Tag wurde verändert. Er muss das Attribut data-chatbot und ein src mit widget.js behalten.
• Blockiert durch CSP oder erlaubte Websites. Suchen Sie nach Fehlern in der Browser-Konsole und prüfen Sie die beiden Abschnitte oben.
• Chatbot ausgeschaltet. Prüfen Sie, ob der Schalter Chatbot aktiviert eingeschaltet ist.
• Werbeblocker. In seltenen Fällen blockiert eine Erweiterung Chat-Widgets. Versuchen Sie es in einem privaten Fenster ohne Erweiterungen.

Sobald alles funktioniert, passen Sie das Widget unter Chatbot → Anpassen an die Website an: Button-Symbol, Beschriftung, Farben und Position oder ein Seitenreiter am Bildschirmrand (etwa „Hilfe“); ein anderes Aussehen auf Smartphones; und Seitenregeln für ausgewählte Seiten (zum Beispiel ein Seitenreiter nur auf /pricing). Sehen Sie sich alle Anpassungsoptionen an und lesen Sie, wie der Assistent Ihr Unternehmen kennenlernt, vergleichen Sie Tarife und Unterhaltungslimits oder lesen Sie die Anleitung zur React-Chatbot-Komponente und die Anleitung für Vue und Nuxt.