React et Next.js

Préparer les origines et le périmètre#

Activez Afficher sur mon site web pour l’agent (page de l’agent → Mettre en ligne → Widget de site web), puis ajoutez les origines exactes de développement local, de préproduction et de production sous Adresses de site web autorisées. Déterminez si le lanceur doit persister lors de chaque navigation côté client (layout racine) ou n’exister que sous certaines routes (layout ou composant imbriqué).

Next.js App Router#

Utilisez next/script dans un composant rendu par le layout qui possède le lanceur. Le slug peut être exposé sans risque ; n’utilisez pas de clé API ni de variable d’environnement secrète.

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"
    />
  );
}

Rendez <AgentEmbed /> une seule fois dans app/layout.tsx pour un agent disponible sur tout le site, ou dans un layout imbriqué pour un groupe de routes. Ne rendez pas une copie distincte depuis chaque composant de page. afterInteractive évite tout accès au DOM côté serveur et ne bloque pas l’analyse du HTML initial.

Avec le Pages Router de Next.js, rendez ce même composant une seule fois depuis pages/_app.tsx pour un comportement sur l’ensemble du site. Le rendre depuis une page individuelle n’est approprié que si le fait de quitter cette page doit retirer l’agent ; dans ce cas, utilisez le modèle explicite effet/nettoyage ci-dessous, car un script externe chargé a déjà créé du DOM en dehors de l’arbre de React.

React sans Next.js#

Créez le script dans un effet. Un identifiant de script stable empêche une double insertion en mode Strict de développement. Si le composant est limité à une route, le nettoyage doit supprimer à la fois le script et la racine créée par le loader.

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;
}

Pour un lanceur disponible sur tout le site, montez ce composant au-dessus du routeur et évitez le démontage lié aux routes. Conserver la racine préserve l’iframe et la conversation d’une navigation à l’autre.

Configuration de l’environnement#

Une variable publique définie au moment du build peut contenir le slug, car il n’est pas secret. Validez-le avant le rendu et conservez les véritables clés API MAF et identifiants de fournisseurs exclusivement côté serveur. Si le slug est manquant, le loader émet un avertissement et s’arrête au lieu de créer un lanceur.

Si votre application sert plusieurs tenants clients à partir d’un même build React, ne modifiez pas data-agent sur un script déjà exécuté. Attribuez un slug stable unique au tenant courant, supprimez la racine de l’ancien slug lors d’un changement de tenant authentifié, puis montez un nouveau script. Ne laissez jamais un paramètre de requête non fiable déterminer un slug d’un autre tenant.

Vérifier l’hydratation et la navigation#

1. Chargez directement une route publique et vérifiez qu’un seul lanceur apparaît.
2. Naviguez côté client entre les routes qui doivent conserver le lanceur.
3. Pour une installation imbriquée ou limitée à une route, quittez la route et vérifiez que le script et la racine disparaissent, puis revenez et vérifiez qu’un seul nouveau lanceur apparaît.
4. Inspectez le réseau et la CSP, puis testez un vrai message.
5. Exécutez le build de production ; le mode Strict en développement ne reflète pas à lui seul le comportement final.

Dépannage#

Aucun adaptateur npm pour React ou Next n’est actuellement publié ; ces exemples utilisent le loader public pris en charge, indépendant de l’API REST.