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

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

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=20261022-open"
  data-agent="YOUR_SITE_SLUG"
  data-position="right"
  async
></script>

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

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

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

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

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

Созданный корневой элемент использует data-maf-open для внутреннего учёта открытого чата. Это не настройка тега скрипта и не публичная команда открытия виджета. См. Последующие уведомления.

Без 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=20261022-open возвращает 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, размещение). Эта страница остаётся гайдом для людей.