Übersicht zur Einbettung

So funktioniert die Einbettung#

embed.js fügt dem Host-Dokument einen fest positionierten Launcher hinzu. Das Skript kann das ausgeblendete iframe von https://makeagent.fast vorab laden, um Seiten-Trigger vor dem ersten Klick auszuwerten. Den vollständigen Chat öffnet der Besucher über den Launcher oder einen Trigger. Das CSS der Host-Seite kann den Chat nicht umgestalten. Änderungen an der Host-Seite erfolgen ausschließlich über registrierte, vom Owner freigegebene Page-Action-Handler.

Der Loader ist öffentlich und verwendet keinen API-Key. Der Zugriff wird über den Schalter Auf meiner Website anzeigen des Agents und die exakte Allowlist der übergeordneten Origins (Erlaubte Website-Adressen) gesteuert. Der Site-Slug ist eine Kennung, kein Geheimnis.

Voraussetzungen#

Bevor Sie den Code kopieren:

1. Erstellen und testen Sie einen Agent im Dashboard.
2. Verwenden Sie das generierte Snippet des Agents; der separate Agent-Link muss dafür nicht aktiviert sein.
3. Öffnen Sie auf der Seite Agent Ihres Agents Live schalten → Website-Widget. Falls das Widget noch nicht aktiviert ist, wählen Sie Einbettung aktivieren. Prüfen Sie anschließend, ob Auf meiner Website anzeigen eingeschaltet ist.
4. Fügen Sie unter Erlaubte Website-Adressen jede übergeordnete Origin hinzu, die den Launcher darstellen soll.
5. Wählen Sie Einbettungseinstellungen speichern und kopieren Sie dann das generierte Snippet.

Eine Origin besteht nur aus Schema, Hostname und optional einem Port. Sie enthält nie einen Pfad. Die folgenden vier Origins sind jeweils eigenständig und müssen bei Bedarf einzeln hinzugefügt werden:

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

Geben Sie nicht https://example.com/pricing, *.example.com oder einen Wildcard am Ende ein. Wenn Ihre Produktionsseite von der Domain ohne Subdomain auf www weiterleitet, tragen Sie die Origin ein, die nach der Weiterleitung in der Adressleiste des Browsers erhalten bleibt.

Loader installieren#

Platzieren Sie ein einzelnes Skript vor dem schließenden </body>-Tag oder verwenden Sie den reinen Browser-Lebenszyklus, den Ihre Framework-Anleitung empfiehlt.

Das Fenster Website-Widget (Seite Agent → Live schalten) kopiert folgende Form (Site-Slug, Position, optionales Label und den Cache-Buster ?v=). Behalten Sie async bei. Behalten Sie auch den ?v=-Query aus dem Snippet bei, damit Hosts keinen veralteten Loader festschreiben.

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

Nur data-agent ist erforderlich. Optionale Attribute, die der Loader tatsächlich liest:

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

Legen Sie keinen MAF-API-Key, Provider-Key, Connector-Token, keine Besucheridentität und keine privaten Kundendaten in einem data-*-Attribut ab. Erfinden Sie keine Attribute wie data-api-key, data-z-index, data-offset oder data-delay. data-maf-bootstrapped wird vom Loader gesetzt.

Attribute konfigurieren#

Gelesen werden die Attribute ausschließlich vom embed.js-Tag. Das iframe akzeptiert nur Hex-Akzentfarben.

Das generierte Root-Element verwendet intern außerdem data-maf-open, um nachzuverfolgen, ob der Chat geöffnet ist. Es ist weder eine Einstellung des Script-Tags noch ein öffentlicher Befehl zum Öffnen des Widgets. Informationen zum Trigger-Verhalten finden Sie unter Follow-ups.

Ohne data-theme liest der Loader den Hintergrund des Hosts aus und greift dann auf die Betriebssystemeinstellung des Besuchers zurück. Außerdem übergibt er die Schriftfamilie des Hosts an den Frame und ruft das aktuelle Erscheinungsbild des Launchers ab. Schlägt die Abfrage des Erscheinungsbilds fehl, blockiert das den Launcher nicht; er behält den sicheren Standardstil. Änderungen unter Darstellung im Dashboard aktualisieren diesen Abruf, ohne dass die Site neu veröffentlicht werden muss.

Laufzeitverhalten#

• Laden Sie das Skript nur einmal pro Dokument. Eine Wiederholung desselben Slugs ist idempotent und erzeugt weiterhin nur ein Root-Element maf-embed-root-YOUR_SITE_SLUG.
• Mehrere verschiedene Agents können in einem Dokument nebeneinander existieren. Der Loader markiert jedes verarbeitete Skript mit data-maf-bootstrapped, sodass ein asynchroner Fallback jedes eindeutige data-agent-Tag genau einmal initialisiert.
• Das iframe kann für Seiten-Trigger vorab geladen werden. Es bleibt ausgeblendet, bis ein Trigger erscheint oder der Besucher den Chat öffnet; Sitzungen, die bereits einen Trigger genutzt haben, behalten den Lazy-Open-Pfad. Mikrofon, Autoplay und Schreibzugriff auf die Zwischenablage unterliegen weiterhin dem iframe-Berechtigungsmodell des Browsers.
• Binden Sie den Loader in einer clientseitig gerouteten App im höchsten Layout ein, das ihn besitzen soll, damit Routenwechsel die Unterhaltung nicht neu laden.
• Das bloße Entfernen des Script-Elements entfernt einen bereits erzeugten Launcher nicht. Entfernen Sie für einen routenspezifischen Abbau zusätzlich das passende maf-embed-root-...-Element. Laden Sie das Skript nach dem Abbau erneut, um es wieder einzubinden.
• Frame und Loader tauschen Nachrichten mit Namespace zu Lebenszyklus, Identität, Triggern und Page-Actions aus. Der Loader weist Nachrichten zurück, die nicht von der Make-Agent-Fast-Origin und dem aktuellen Site-Slug stammen.

Installation überprüfen#

Testen Sie die veröffentlichte Seite, nicht nur die Editor-Vorschau eines Website-Builders:

1. Öffnen Sie die bereitgestellte URL in einem privaten Fenster und bestätigen Sie, dass ihre exakte Origin in der Allowlist steht.
2. Bestätigen Sie im Network-Panel, dass https://makeagent.fast/embed.js?v=20261022-open den Status 200 zurückgibt.
3. Bestätigen Sie, dass genau ein Element mit data-maf-embed="YOUR_SITE_SLUG" existiert.
4. Öffnen Sie den Launcher und bestätigen Sie, dass die iframe-Anfrage an /embed/YOUR_SITE_SLUG erfolgreich ist.
5. Senden Sie eine realistische Frage und bestätigen Sie, dass sie unter Unterhaltungen erscheint.
6. Testen Sie einen schmalen mobilen Viewport und, falls aktiviert, die Mikrofonberechtigung.

Fehlenden Launcher diagnostizieren#

Installationsanleitung auswählen#

Verwenden Sie HTML und JavaScript für ein normales Script-Tag. Für React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace oder Ghost wählen Sie die passende Anleitung in der Seitenleiste. Plattformen, die kein beliebiges JavaScript erlauben, wie viele Notion- und Linktree-Oberflächen, können auf den Agent-Link des Agents verweisen – eine öffentliche Chatseite unter der eigenen Adresse des Agents, die im letzten Onboarding-Schritt (Auf dem Smartphone testen) und auf dem Tab Darstellung der Agent-Seite aktiviert wird. Eine andere Möglichkeit ist eine Kunden-Website mit der Einbettung.

Für Coding-Agents#

Installieren Sie dies mit Claude Code, Cursor oder Codex auf der Website eines Kunden? Kopieren Sie skills/embed-agent/SKILL.md aus dem Make-Agent-Fast-Repository nach .cursor/skills/embed-agent/ oder .claude/skills/embed-agent/. Diese Datei ist das Installationsrezept (Attribute, CSP, Platzierung). Diese Seite bleibt die Anleitung für Menschen.