React und Next.js

Origins und Geltungsbereich vorbereiten#

Aktivieren Sie für den Agenten die Option Auf meiner Website anzeigen (Agent-Seite → Live schalten → Website-Widget) und tragen Sie unter Erlaubte Website-Adressen die exakten Origins für lokale Entwicklung, Vorschau und Produktion ein. Legen Sie fest, ob der Launcher jede clientseitige Navigation überdauern soll (Root-Layout) oder nur unter ausgewählten Routen existieren soll (verschachteltes Layout bzw. verschachtelte Komponente).

Next.js App Router#

Verwenden Sie next/script in einer Komponente, die von dem Layout gerendert wird, das den Launcher verwaltet. Der Slug darf öffentlich sein; verwenden Sie jedoch keinen API-Schlüssel und keine geheime Umgebungsvariable.

import Script from "next/script";

export function AgentEmbed() {
  return (
    <Script
      id="maf-agent"
      src="https://makeagent.fast/embed.js?v=20261022-open"
      strategy="afterInteractive"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="Ask us"
    />
  );
}

Rendern Sie <AgentEmbed /> genau einmal in app/layout.tsx für einen websiteweiten Agenten oder in einem verschachtelten Layout für eine Route Group. Rendern Sie nicht aus jeder Seitenkomponente eine eigene Kopie. afterInteractive vermeidet serverseitigen DOM-Zugriff und blockiert das initiale Parsen des HTML nicht.

Rendern Sie im Next.js Pages Router dieselbe Komponente für ein websiteweites Verhalten einmalig in pages/_app.tsx. Das Rendern in einer einzelnen Seite ist nur dann sinnvoll, wenn der Agent beim Verlassen dieser Seite verschwinden soll. Verwenden Sie in diesem Fall das unten beschriebene explizite Effect-/Cleanup-Muster, da ein geladenes externes Skript bereits DOM-Elemente außerhalb des React-Baums erzeugt hat.

React ohne Next.js#

Erstellen Sie das Skript in einem Effect. Eine stabile Skript-ID verhindert doppeltes Einfügen im Strict Mode während der Entwicklung. Wenn die Komponente routenbezogen ist, muss das Cleanup sowohl das Skript als auch das vom Loader erzeugte Root-Element entfernen.

import { useEffect } from "react";

const slug = "YOUR_SITE_SLUG";

export function AgentEmbed() {
  useEffect(() => {
    if (document.getElementById(`maf-embed-root-${slug}`)) return;

    const script = document.createElement("script");
    script.id = "maf-agent";
    script.src = "https://makeagent.fast/embed.js?v=20261022-open";
    script.dataset.agent = slug;
    script.dataset.position = "right";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  }, []);

  return null;
}

Binden Sie diese Komponente für einen websiteweiten Launcher oberhalb des Routers ein und verzichten Sie auf ein routenabhängiges Unmounten. Wenn das Root-Element erhalten bleibt, bleiben auch das iframe und die Unterhaltung über Navigationen hinweg bestehen.

Umgebungskonfiguration#

Eine öffentliche Variable zur Build-Zeit darf den Slug enthalten, da er nicht geheim ist. Validieren Sie ihn vor dem Rendern und halten Sie echte MAF-API-Schlüssel und Zugangsdaten von Anbietern ausschließlich auf dem Server. Fehlt der Slug, gibt der Loader eine Warnung aus und beendet sich, statt einen Launcher zu erstellen.

Wenn Ihre Anwendung aus einem einzigen React-Build verschiedene Kunden-Mandanten bedient, wechseln Sie data-agent nicht bei einem bereits ausgeführten Skript. Weisen Sie dem aktuellen Mandanten genau einen stabilen Slug zu, entfernen Sie bei einem authentifizierten Mandantenwechsel das Root-Element des alten Slugs und binden Sie anschließend ein neues Skript ein. Lassen Sie niemals einen nicht vertrauenswürdigen Query-Parameter einen mandantenübergreifenden Slug auswählen.

Hydration und Navigation überprüfen#

1. Rufen Sie eine öffentliche Route direkt auf und prüfen Sie, dass genau ein Launcher erscheint.
2. Navigieren Sie clientseitig durch Routen, auf denen der Launcher erhalten bleiben soll.
3. Navigieren Sie bei einer verschachtelten bzw. routenbezogenen Installation aus dem Bereich heraus und prüfen Sie, dass Skript und Root-Element verschwinden. Navigieren Sie dann zurück und prüfen Sie, dass genau ein neuer Launcher erscheint.
4. Prüfen Sie Network und CSP und testen Sie eine echte Nachricht.
5. Führen Sie den Produktions-Build aus; der Strict Mode in der Entwicklung allein bildet nicht das endgültige Verhalten ab.

Fehlerbehebung#

Derzeit wird kein npm-Adapter für React/Next veröffentlicht; diese Beispiele verwenden den unterstützten öffentlichen Loader, der keine REST-API benötigt.