Astro
공유 Astro 레이아웃 또는 선택한 정적/아일랜드 페이지에 임베드 에이전트를 추가합니다.
공유 Astro 레이아웃 또는 선택한 정적/아일랜드 페이지에 임베드 에이전트를 추가합니다.
배포 오리진 준비하기#
Make Agent Fast 임베드를 활성화한 뒤 정확한 Astro 개발, 미리보기, 운영 오리진을 허용합니다. 빌드 호스트나 저장소 URL이 아니라 브라우저의 최종 스킴/호스트/포트가 중요합니다.
공유 레이아웃에 추가하기#
실행 버튼을 소유할 Astro 레이아웃의 </body> 바로 앞에 표준 외부 로더를 둡니다.
---
// src/layouts/BaseLayout.astro
---
<html lang="ko">
<body>
<slot />
<script
is:inline
src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
data-agent="YOUR_SITE_SLUG"
data-position="right"
data-label="문의하기"
async
></script>
</body>
</html>is:inline은 Astro에 외부 스크립트 태그와 data-* 속성을 번들/변환하지 않고 유지하라고 알려 줍니다. 로더는 공개이며 프레임워크와 독립적입니다. 서버 모듈로 가져오지 마세요.
선택한 페이지로 제한하기#
중첩 레이아웃을 사용하거나 선택한 .astro 페이지에만 태그를 포함합니다. 기본 레이아웃과 페이지에 같은 태그를 모두 넣지 마세요. 로더는 같은 슬러그 중복 루트를 무시하지만 중복 HTML은 탐색과 정리를 이해하기 어렵게 합니다.
Astro 클라이언트 View Transitions를 사용하면 직접 페이지 로드와 앱 내 탐색을 모두 테스트합니다. 사이트 전체 에이전트는 지속 공유 레이아웃이 좋습니다. 경로별 동작은 경로를 나갈 때 스크립트와 maf-embed-root-YOUR_SITE_SLUG를 모두 제거하고 나중에 새 스크립트를 삽입하세요.
CSP 및 동의 설정하기#
정적 호스팅 헤더도 브라우저를 제어합니다. script-src, frame-src, 관련 연결 정책에서 https://makeagent.fast를 허용하세요. 동의 관리자가 스크립트를 차단하면 CSP를 약화하거나 동의를 우회하지 말고 필요한 동의 후 태그를 로드합니다.
빌드 출력 확인하기#
- Astro 운영 빌드를 실행하고 생성 HTML에
data-agent태그가 유지되는지 확인합니다. - 비공개 창에서 배포 페이지를 엽니다.
- 임베드 루트 하나와 로더/iframe 요청 성공을 확인합니다.
- Astro 경로를 이동하며 의도한 유지 동작을 확인합니다.
- 실제 메시지를 보내고 모바일/마이크를 테스트합니다.
문제 해결#
| 증상 | 해결 방법 |
|---|---|
| 빌드 HTML에서 속성이 없거나 변경됨 | 외부 스크립트에 is:inline 추가 |
| 스크립트 태그 두 개 출력 | 소유 레이아웃/페이지 하나에만 설치 |
| 클라이언트 탐색이 직접 로드와 다름 | View Transitions 테스트 및 지속 공유 레이아웃 선택 |
| 개발은 되지만 정적 호스트 실패 | 정확한 운영 오리진과 호스팅 CSP 헤더 추가 |
| 음성 실패 | HTTPS, 브라우저 권한, Permissions Policy 설정 |
현재 npm Astro 어댑터는 게시되지 않았습니다. 여기에 표시된 호스팅 로더를 사용하세요.