Обзор встраивания

Как работает встраивание#

embed.js добавляет один фиксированный загрузчик в документ сайта. Первый клик посетителя открывает лениво загружаемый iframe с https://makeagent.fast; агент и диалог остаются изолированными от страницы внутри этого фрейма. CSS сайта не может перестилизовать чат, а контент агента не может переписать документ сайта.

Загрузчик публичен и не использует ключ API. Доступ контролируется переключателем Встраивание и точным разрешённым списком родительских origin. Slug сайта — идентификатор, а не секрет.

Предварительные условия#

Прежде чем копировать код:

1. Создайте и проверьте агента в панели управления.
2. Используйте сгенерированный сниппет агента; публиковать его отдельную публичную страницу не обязательно.
3. Откройте страницу Встраивание сайта и включите переключатель Встраивание.
4. Добавьте каждый родительский origin, который будет выводить загрузчик.
5. Сохраните и скопируйте сгенерированный сниппет.

Origin содержит только схему, имя хоста и необязательный порт. Пути в нём нет. Это четыре разных origin — добавляйте их отдельно, если используете:

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

Не вводите https://example.com/pricing, *.example.com или завершающий шаблон. Если продакшен перенаправляет с основного домена на www, разрешайте тот origin, который остаётся в адресной строке после перенаправления.

Установите загрузчик#

Поставьте один скрипт перед закрывающим тегом </body> или используйте браузерный жизненный цикл, рекомендованный гайдом вашего фреймворка.

Страница Встраивание в панели копирует именно эту форму (slug сайта, позиция, необязательная подпись и параметр ?v= против кэша). Сохраните async. Сохраните параметр ?v= из сниппета, чтобы сайты не закрепляли устаревший загрузчик.

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

Обязателен только data-agent. Необязательные атрибуты, которые загрузчик действительно читает:

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

Не помещайте ключ MAF API, ключ провайдера, токен коннектора, идентичность посетителя или приватные данные клиентов в атрибуты data-*. Не выдумывайте атрибуты вроде data-api-key, data-z-index, data-offset или data-delay. data-maf-bootstrapped выставляет сам загрузчик.

Настройте атрибуты#

Читаются только из тега embed.js. Iframe принимает акценты только в hex-формате.

Без data-theme загрузчик пробует фон сайта, затем возвращается к предпочтению ОС посетителя. Он также передаёт шрифт сайта во фрейм и запрашивает актуальный вид загрузчика. Неудавшийся запрос вида не блокирует загрузчик — сохраняется безопасный стиль по умолчанию. Сохранения внешнего вида в панели обновляют этот запрос без повторной публикации сайта.

Поведение во время работы#

• Загружайте скрипт один раз на документ. Повторение того же slug идемпотентно и по-прежнему даёт один корень maf-embed-root-YOUR_SITE_SLUG.
• Разные агенты могут сосуществовать на одном документе. Загрузчик помечает каждый обработанный скрипт как data-maf-bootstrapped, поэтому асинхронный запасной путь инициализирует каждый отдельный тег data-agent ровно один раз.
• Iframe ленив и скрыт, пока посетитель его не откроет. Он запрашивает разрешения на микрофон, автовоспроизведение и запись в буфер только через модель разрешений iframe браузера.
• В приложении с клиентской маршрутизацией монтируйте загрузчик в самый верхний макет, который должен им владеть, чтобы смена маршрутов не перезагружала диалог.
• Удаление только элемента скрипта не убирает уже созданный загрузчик. Для снятия по маршруту удалите также соответствующий элемент maf-embed-root-.... Чтобы смонтировать заново, перезагрузите скрипт после снятия.
• Фрейм и загрузчик обмениваются только сообщениями жизненного цикла в собственном пространстве имён. Загрузчик отклоняет сообщения не с origin Make Agent Fast и не от текущего slug сайта.

Проверьте установку#

Проверяйте публичную страницу, а не только предпросмотр в редакторе конструктора:

1. Откройте развёрнутый URL в приватном окне и убедитесь, что его точный origin разрешён.
2. Убедитесь, что https://makeagent.fast/embed.js?v=20260728-widget-v2 возвращает 200 в панели Network.
3. Убедитесь, что существует ровно один элемент с data-maf-embed="YOUR_SITE_SLUG".
4. Откройте загрузчик и убедитесь, что запрос iframe к /embed/YOUR_SITE_SLUG успешен.
5. Отправьте реальный вопрос и убедитесь, что он появился в разделе Диалоги.
6. Проверьте узкое мобильное окно и, если включено, разрешение на микрофон.

Диагностируйте отсутствующий загрузчик#

Выберите гайд по установке#

Используйте HTML и JavaScript для обычного тега скрипта. Для React, Vue, SvelteKit, Astro, WordPress, Shopify, Webflow, Framer, Wix, Squarespace или Ghost выберите соответствующий гайд в боковой панели. Платформы, не допускающие произвольный JavaScript, — например, многие поверхности Notion и Linktree — могут ссылаться на включённую Публичную страницу агента, доступную на последнем шаге онбординга и в настройках агента. Ещё один вариант — клиентский сайт с встраиванием.

Для кодирующих агентов#

Устанавливаете это на клиентский сайт через Claude Code, Cursor или Codex? Скопируйте skills/embed-agent/SKILL.md из репозитория Make Agent Fast в .cursor/skills/embed-agent/ или .claude/skills/embed-agent/. Этот файл — рецепт установки (атрибуты, CSP, размещение). Эта страница остаётся гайдом для людей.