임베드 개요

임베드 작동 방식#

embed.js는 호스트 문서에 고정 실행 버튼 하나를 추가합니다. 첫 클릭 전 페이지 규칙을 판단하기 위해 https://makeagent.fast의 숨겨진 iframe을 미리 로드할 수 있습니다. 방문자는 실행 버튼이나 안내 메시지에서 전체 채팅을 엽니다. 호스트 CSS는 채팅 UI를 바꿀 수 없습니다. 호스트 페이지 변경은 등록되고 소유자가 허용한 페이지 작업 핸들러를 통해서만 실행됩니다.

로더는 공개 파일이며 API 키를 사용하지 않습니다. 접근은 에이전트의 내 웹사이트에 보이기 스위치와 정확한 상위 오리진 허용 목록(허용할 웹사이트 주소)으로 제어됩니다. 사이트 슬러그는 식별자이지 비밀 값이 아닙니다.

사전 준비#

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

1. 대시보드에서 에이전트를 만들고 테스트합니다.
2. 에이전트의 실제 설치 코드를 사용합니다. 별도의 에이전트 링크를 켤 필요는 없습니다.
3. 에이전트의 에이전트 페이지에서 고객에게 열기 → 웹사이트 위젯을 엽니다. 위젯이 아직 꺼져 있으면 임베드 켜기를 선택한 다음 내 웹사이트에 보이기가 켜져 있는지 확인합니다.
4. 허용할 웹사이트 주소에 실행 버튼을 표시할 모든 상위 오리진을 추가합니다.
5. 임베드 설정 저장을 선택한 다음 생성된 스니펫을 복사합니다.

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

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=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="문의하기"
  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-maf-open은 채팅 열림 상태를 나타내는 내부 속성입니다. 스크립트 태그 설정이나 위젯을 여는 공개 명령이 아닙니다. 규칙 동작은 후속 알림을 참고하세요.

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

런타임 동작#

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

설치 확인하기#

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

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

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

설치 가이드 선택하기#

Notion이나 Linktree처럼 스크립트를 허용하지 않는 플랫폼은 에이전트의 에이전트 링크를 사용하세요. 에이전트 고유 주소에 있는 공개 채팅 페이지 하나로, 온보딩 마지막 단계(휴대폰으로 테스트)와 에이전트 페이지의 표시 탭에서 켭니다. 위젯이 설치된 자신의 웹사이트로 연결할 수도 있습니다.

코딩 에이전트용#

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