Make Agent Fast 문서

임베드 개요

안전하고 프레임워크에 독립적인 로더로 기존 웹사이트에 플로팅 에이전트를 추가합니다.

이 페이지 한눈에

안전하고 프레임워크에 독립적인 로더로 기존 웹사이트에 플로팅 에이전트를 추가합니다.

임베드 설치 경로사이트 로더가 호스팅 에이전트 런타임과 통신합니다

HTML React Vue SvelteKit Astro WordPress Shopify Webflow Framer Wix Squarespace Ghost Notion Tilda 아임웹 카페24 CSP

임베드 작동 방식#

embed.js는 호스트 문서에 고정 실행 버튼 하나를 추가합니다. 방문자가 처음 클릭하면 https://makeagent.fast의 iframe이 지연 로드되고, 에이전트와 대화는 호스트 페이지와 분리된 프레임 안에 유지됩니다. 호스트 CSS는 채팅 UI를 바꿀 수 없고 에이전트 콘텐츠는 호스트 문서를 수정할 수 없습니다.

로더는 공개 파일이며 API 키를 사용하지 않습니다. 접근은 임베드 활성화 스위치와 정확한 상위 오리진 허용 목록으로 제어됩니다. 사이트 슬러그는 식별자이지 비밀 값이 아닙니다.

사전 준비#

코드를 복사하기 전에 다음을 완료하세요.

대시보드에서 에이전트를 만들고 테스트합니다.
에이전트의 실제 설치 코드를 사용합니다. 별도의 공개 페이지를 게시할 필요는 없습니다.
사이트의 임베드 페이지를 열고 임베드 활성화를 켭니다.
실행 버튼을 표시할 모든 상위 오리진을 추가합니다.
저장한 다음 생성된 스니펫을 복사합니다.

오리진은 스킴, 호스트 이름, 선택적 포트만 포함하며 경로는 포함하지 않습니다. 다음 네 오리진은 서로 다르므로 실제로 사용한다면 각각 추가해야 합니다.

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

https://example.com/pricing, *.example.com, 뒤쪽 와일드카드는 입력하지 마세요. 운영 도메인이 기본 도메인에서 www로 리디렉션되면 리디렉션 후 브라우저 주소창에 남는 오리진을 허용합니다.

로더 설치하기#

닫는 </body> 태그 바로 앞에 스크립트 하나를 넣거나 프레임워크 가이드에서 권장하는 브라우저 전용 생명주기를 사용하세요.

대시보드 임베드 페이지는 이 형태를 복사합니다(사이트 슬러그, 위치, 선택 레이블, ?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="문의하기"
  data-accent="#6d5ce7"
  data-locale="ko"
  data-theme="light"
  async
></script>

MAF API 키, 제공자 키, 커넥터 토큰, 방문자 식별 정보, 비공개 고객 데이터를 data-* 속성에 넣지 마세요. data-api-key, data-z-index, data-offset, data-delay 같은 속성을 만들지 마세요. data-maf-bootstrapped는 로더가 설정합니다.

속성 설정하기#

embed.js 태그만 읽습니다. iframe은 16진 액센트만 받습니다.

속성	허용 값	기본값	효과
`data-agent`	에이전트 사이트 슬러그	필수	사이트와 에이전트 선택. 없으면 콘솔 경고, 런처 없음
`data-position`	`bottom-left`, `bottom-right`, `top-left`, `top-right` (`left` / `right`는 여전히 아래쪽 모서리)	`right` (오른쪽 아래)	그 외 값은 오른쪽 아래로 처리
`data-label`	일반 텍스트	아이콘만 표시	보이는 텍스트와 접근 가능한 이름. `"`, `<`를 이스케이프. 대시보드 UI는 40자 제한
`data-accent`	`#RGB` 또는 `#RRGGBB`	저장된 사이트 디자인	런처 호스트 덮어쓰기. iframe에서 16진이 아니면 무시
`data-locale`	`en`, `ko`, `uz`	사이트 기본 언어	위젯 크롬 언어. 에이전트 음성이 아님. `ru` 아님
`data-theme`	`light` 또는 `dark`	호스트 배경, 그다음 OS	다른 값은 무시

data-theme가 없으면 로더가 호스트 배경을 확인한 뒤 방문자의 OS 설정을 사용합니다. 호스트 글꼴도 프레임에 전달하고 최신 실행 버튼 디자인을 가져옵니다. 디자인 요청이 실패해도 실행 버튼은 차단되지 않고 안전한 기본 스타일을 유지합니다. 대시보드에서 디자인을 저장하면 사이트를 다시 게시하지 않아도 이 요청이 갱신됩니다.

런타임 동작#

문서당 스크립트를 한 번만 로드하세요. 같은 슬러그를 반복해도 중복 방지되어 maf-embed-root-YOUR_SITE_SLUG 루트 하나만 생성됩니다.
한 문서에서 서로 다른 에이전트를 함께 사용할 수 있습니다. 로더는 처리한 각 스크립트에 data-maf-bootstrapped를 표시하므로 비동기 폴백도 서로 다른 data-agent 태그를 각각 정확히 한 번 초기화합니다.
iframe은 방문자가 열기 전까지 지연 로드되고 숨겨집니다. 마이크, 자동 재생, 클립보드 쓰기는 브라우저의 iframe 권한 모델을 통해서만 요청합니다.
클라이언트 라우팅 앱에서는 대화를 유지하도록 실행 버튼이 필요한 가장 상위 레이아웃에 로더를 마운트하세요.
스크립트 요소만 제거해도 이미 생성된 실행 버튼은 사라지지 않습니다. 특정 경로에서 완전히 제거하려면 일치하는 maf-embed-root-... 요소도 제거하세요. 다시 마운트하려면 제거 후 스크립트를 다시 로드합니다.
프레임과 로더는 이름이 지정된 생명주기 메시지만 주고받습니다. 로더는 Make Agent Fast 오리진과 현재 사이트 슬러그가 일치하지 않는 메시지를 거부합니다.

설치 확인하기#

웹사이트 빌더 편집기 미리보기뿐 아니라 공개 페이지에서 테스트하세요.

배포 URL을 비공개 창에서 열고 정확한 오리진이 허용되었는지 확인합니다.
Network 패널에서 https://makeagent.fast/embed.js?v=20260728-widget-v2가 200을 반환하는지 확인합니다.
data-maf-embed="YOUR_SITE_SLUG" 요소가 하나만 있는지 확인합니다.
실행 버튼을 열고 /embed/YOUR_SITE_SLUG iframe 요청이 성공하는지 확인합니다.
실제 질문을 보내고 대화 화면에 표시되는지 확인합니다.
좁은 모바일 화면과, 사용한다면 마이크 권한을 테스트합니다.

실행 버튼이 없을 때 진단하기#

증상	가능한 원인	해결 방법
콘솔에 `missing data-agent` 경고 표시	슬러그 속성이 없거나 다른 스크립트에 있음	`embed.js` 태그에 `data-agent` 추가
`embed.js` 차단	CSP 또는 동의 관리자가 스크립트를 거부함	스크립트 오리진을 허용하거나 필요한 동의 후 로드
실행 버튼은 보이지만 프레임 로드 거부	임베드 꺼짐 또는 상위 오리진 불일치	대시보드의 임베드와 허용 웹사이트를 확인
로컬에서는 되지만 운영에서 실패	개발 오리진만 허용됨	정확한 배포 HTTPS 오리진 추가
서로 다른 에이전트 두 개 표시	문서가 서로 다른 슬러그 두 개를 로드함	의도한 사이트 슬러그만 남김
채팅은 열리지만 음성은 실패	브라우저 또는 Permissions Policy가 마이크 차단	보안 및 CSP 확인

설치 가이드 선택하기#

Notion이나 Linktree처럼 스크립트를 허용하지 않는 플랫폼은 에이전트의 켜진 공개 페이지 링크를 사용하세요. 온보딩 마지막 단계와 에이전트 설정에서 복사할 수 있습니다. 위젯이 설치된 자신의 웹사이트로 연결할 수도 있습니다.

코딩 에이전트용#

Claude Code, Cursor, Codex로 고객 사이트에 임베드할 때는 Make Agent Fast 저장소의 skills/embed-agent/SKILL.md를 .cursor/skills/embed-agent/ 또는 .claude/skills/embed-agent/에 복사하세요. 속성, CSP, 배치 규칙은 그 파일이 기준입니다. 이 페이지는 사람용 가이드입니다.