HTML 및 JavaScript

사이트 준비하기#

에이전트의 임베드 설정을 열어 임베드를 활성화한 뒤 최종 호스트 페이지 오리진을 추가합니다. 개발과 운영은 따로 추가하세요. http://localhost:3000, https://example.com, https://www.example.com은 서로 일치하지 않습니다.

스크립트 설치하기#

실행 버튼을 표시할 모든 페이지의 닫는 </body> 태그 바로 앞에 로더를 붙여 넣습니다. 공개 사이트 슬러그와 선택적 표현 값만 바꾸세요.

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

data-agent는 필수입니다. 슬러그는 공개 값이며 이 태그에 API 키를 넣지 않습니다. 대시보드 스니펫의 ?v=를 유지하세요. 선택 data-label, data-accent(#RGB / #RRGGBB), data-locale(en | ko | uz), data-theme(light | dark)는 임베드 개요에 있습니다. 생략하면 저장된 디자인과 자동 테마를 상속합니다.

전체 사이트 또는 특정 페이지 배치 선택하기#

공유 서버 측 템플릿은 전역 레이아웃/푸터에 스크립트를 넣습니다. 일부 페이지만 필요하면 해당 템플릿에만 포함합니다. 문서당 같은 슬러그를 한 번 로드하세요. 중복 같은 슬러그 태그는 무시되지만 중복을 제거해야 소유권과 제거가 예측 가능합니다.

<script>를 제거하는 HTML 정제기나 리치 텍스트 필드에 스니펫을 붙여 넣지 마세요. 렌더링된 페이지 소스 또는 Elements 패널에 태그가 남는지 확인합니다.

SPA에서 제거 또는 다시 마운트하기#

실행 후 스크립트만 제거해도 이미 생성된 실행 버튼은 사라지지 않습니다. 경로별 클라이언트 앱은 다시 마운트하기 전에 스크립트와 슬러그별 루트를 모두 제거해야 합니다.

const slug = "YOUR_SITE_SLUG";
document.getElementById("maf-agent")?.remove();
document.getElementById(`maf-embed-root-${slug}`)?.remove();

활성 대화가 사라지지 않도록 클라이언트 탐색 동안 사이트 전체 루트 하나를 유지하는 것이 좋습니다. 루트를 제거했다면 새 embed.js 스크립트를 추가해 다시 생성합니다.

브라우저에서 확인하기#

1. 비공개 창에서 배포 페이지를 엽니다.
2. embed.js가 200을 반환하고 CSP/동의에 차단되지 않는지 확인합니다.
3. [data-maf-embed="YOUR_SITE_SLUG"] 루트가 하나인지 확인합니다.
4. 실행 버튼을 열고 /embed/YOUR_SITE_SLUG iframe이 로드되는지 확인합니다.
5. 질문을 보내고 대화에서 스레드를 확인합니다.
6. 음성을 사용하면 모바일 너비와 마이크 권한을 테스트합니다.

문제 해결#

검토되지 않은 로컬 포크로 로더를 프록시/복사하지 마세요. 오리진 검증과 수정이 최신으로 유지되도록 호스팅 스크립트를 사용합니다.