Présentation de l'intégration

Fonctionnement de l'intégration#

embed.js ajoute un lanceur fixe au document hôte. Il peut précharger l'iframe masquée depuis https://makeagent.fast afin d'évaluer les déclencheurs de page avant le premier clic ; le visiteur ouvre le chat complet depuis le lanceur ou un déclencheur. Le CSS de l'hôte ne peut pas modifier le style du chat. Les modifications de la page hôte ne s'exécutent que via des gestionnaires d'actions de page enregistrés et approuvés par le propriétaire.

Le loader est public et n'utilise pas de clé API. L'accès est contrôlé par l'interrupteur Afficher sur mon site web de l'agent et par la liste d'autorisation des origines parentes exactes (Adresses de site web autorisées). Le slug du site est un identifiant, pas un secret.

Prérequis#

Avant de copier le code :

1. Créez et testez un agent dans le tableau de bord.
2. Utilisez l'extrait généré pour l'agent ; il n'est pas nécessaire d'activer son Lien de l'agent distinct.
3. Sur la page Agent de l'agent, ouvrez Mettre en ligne → Widget de site web. Si le widget n'est pas encore activé, choisissez Activer l'intégration, puis vérifiez que Afficher sur mon site web est activé.
4. Sous Adresses de site web autorisées, ajoutez chaque origine parente qui affichera le lanceur.
5. Sélectionnez Enregistrer les paramètres d'intégration, puis copiez l'extrait généré.

Une origine contient uniquement le schéma, le nom d'hôte et, éventuellement, le port. Elle ne contient jamais de chemin. Les quatre origines suivantes sont distinctes et doivent être ajoutées séparément lorsque vous les utilisez :

https://example.com
https://www.example.com
https://staging.example.com
http://localhost:3000

Ne saisissez pas https://example.com/pricing, *.example.com ni de caractère générique final. Si la production redirige le domaine nu vers www, autorisez l'origine qui reste dans la barre d'adresse du navigateur après la redirection.

Installer le loader#

Placez un seul script avant la balise de fermeture </body>, ou utilisez le cycle de vie réservé au navigateur recommandé par le guide de votre framework.

La feuille Widget de site web (page Agent → Mettre en ligne) copie la structure suivante (slug du site, position, libellé facultatif et paramètre ?v= de contournement du cache). Conservez async. Gardez le paramètre ?v= de l'extrait afin que les sites hôtes ne conservent pas un loader obsolète.

<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>

Seul data-agent est obligatoire. Attributs facultatifs réellement lus par le loader :

<script
  src="https://makeagent.fast/embed.js?v=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  data-label="Ask us"
  data-accent="#6d5ce7"
  data-locale="en"
  data-theme="light"
  async
></script>

Ne placez jamais de clé API MAF, de clé de fournisseur, de jeton de connecteur, d'identité de visiteur ni de données privées de clients dans un attribut data-*. N'inventez pas d'attributs tels que data-api-key, data-z-index, data-offset ou data-delay. data-maf-bootstrapped est défini par le loader.

Configurer les attributs#

Lus uniquement depuis la balise embed.js. L'iframe n'accepte que les couleurs d'accent hexadécimales.

La racine générée utilise également data-maf-open en interne pour savoir si le chat est ouvert. Ce n'est ni un paramètre de la balise script ni une commande publique pour ouvrir le widget. Consultez Relances pour le comportement des déclencheurs.

Sans data-theme, le loader échantillonne l'arrière-plan de l'hôte, puis se rabat sur la préférence du système d'exploitation du visiteur. Il transmet également la famille de polices de l'hôte au cadre et récupère la dernière apparence du lanceur. Si cette requête d'apparence échoue, le lanceur n'est pas bloqué ; il conserve le style par défaut sûr. Les modifications dans Affichage du tableau de bord actualisent cette récupération sans republier le site.

Comportement à l'exécution#

• Chargez le script une seule fois par document. Répéter le même slug est idempotent et ne produit toujours qu'une seule racine maf-embed-root-YOUR_SITE_SLUG.
• Plusieurs agents différents peuvent coexister sur un même document. Le loader marque chaque script traité avec data-maf-bootstrapped, de sorte qu'un chargement de secours asynchrone initialise chaque balise data-agent distincte une seule fois.
• L'iframe peut se précharger pour les déclencheurs de page. Elle reste masquée jusqu'à l'apparition d'un déclencheur ou jusqu'à ce que le visiteur ouvre le chat ; les sessions ayant déjà utilisé un déclencheur conservent le chemin d'ouverture différée. Le microphone, la lecture automatique et l'écriture dans le presse-papiers restent soumis au modèle d'autorisations des iframes du navigateur.
• Dans une application à routage côté client, montez le loader dans le layout le plus élevé qui doit le gérer, afin que les changements de route ne rechargent pas la conversation.
• Supprimer uniquement l'élément script ne supprime pas un lanceur déjà créé. Pour un démontage propre à une route, supprimez également l'élément maf-embed-root-... correspondant. Rechargez le script après le démontage pour le monter à nouveau.
• Le cadre et le loader échangent des messages d'espace de noms concernant le cycle de vie, l'identité, les déclencheurs et les actions de page. Le loader rejette les messages qui ne proviennent pas de l'origine Make Agent Fast et du slug de site actuel.

Vérifier l'installation#

Testez la page publiée, et pas seulement l'aperçu de l'éditeur d'un créateur de sites :

1. Ouvrez l'URL déployée dans une fenêtre privée et vérifiez que son origine exacte figure dans la liste d'autorisation.
2. Vérifiez que https://makeagent.fast/embed.js?v=20261022-open renvoie 200 dans le panneau Réseau.
3. Vérifiez qu'il existe un seul élément avec data-maf-embed="YOUR_SITE_SLUG".
4. Ouvrez le lanceur et vérifiez que la requête de l'iframe vers /embed/YOUR_SITE_SLUG aboutit.
5. Envoyez une question réaliste et vérifiez qu'elle apparaît dans Conversations.
6. Testez une fenêtre d'affichage mobile étroite et, si elle est activée, l'autorisation du microphone.

Diagnostiquer un lanceur manquant#

Choisir un guide d'installation#

Utilisez HTML et JavaScript pour une balise script classique. Pour React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace ou Ghost, choisissez le guide correspondant dans la barre latérale. Les plateformes qui n'autorisent pas de JavaScript arbitraire, comme de nombreuses surfaces Notion et Linktree, peuvent renvoyer vers le Lien de l'agent : une page de chat publique à l'adresse propre de l'agent, activée à la dernière étape de l'intégration (Testez sur votre téléphone) et dans l'onglet Affichage de la page Agent. Un site web client doté de l'intégration est une autre option.

Pour les agents de code#

Vous installez ceci sur le site d'un client avec Claude Code, Cursor ou Codex ? Copiez skills/embed-agent/SKILL.md depuis le dépôt Make Agent Fast dans .cursor/skills/embed-agent/ ou .claude/skills/embed-agent/. Ce fichier constitue la recette d'installation (attributs, CSP, emplacement). Cette page reste le guide destiné aux humains.