Vue 및 Nuxt

임베드 준비하기#

에이전트 임베드를 활성화한 뒤 로컬, 미리보기, 운영 배포의 정확한 오리진을 추가합니다. 에이전트가 전체 앱에 속하는지 일부 경로 컴포넌트에만 속하는지 결정하세요.

Nuxt 전체 사이트 플러그인#

서버 렌더링 중 DOM 코드가 실행되지 않도록 .client.ts 플러그인을 만듭니다. Nuxt가 브라우저에서 한 번 로드하므로 클라이언트 탐색 동안 실행 버튼과 대화가 안정적으로 유지됩니다.

// plugins/make-agent-fast.client.ts
const slug = "YOUR_SITE_SLUG";

export default defineNuxtPlugin(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;

  const script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20260728-widget-v2";
  script.dataset.agent = slug;
  script.dataset.position = "right";
  script.dataset.label = "문의하기";
  script.async = true;
  document.body.appendChild(script);
});

runtimeConfig.public에 비밀 값을 넣지 마세요. 공개 사이트 슬러그와 시각 설정만 브라우저에 둡니다. 실제 MAF API/제공자 키는 비공개 서버 런타임 설정에 보관합니다.

전체 사이트 플러그인에는 의도적으로 언마운트 정리가 없습니다. Nuxt 앱 생명주기 전체에 속하기 때문입니다. 개발 중 HMR에서는 완전 새로고침 전까지 이전 루트가 남을 수 있지만 루트 가드가 두 번째 실행 버튼을 막습니다. 한 탭에서 플러그인을 계속 편집한 결과가 아니라 깨끗한 운영 빌드로 최종 동작을 확인하세요.

경로 범위 Vue 컴포넌트#

일부 경로에서는 onMounted에서 마운트하고 onBeforeUnmount에서 스크립트와 생성 루트를 모두 제거합니다.

<script setup lang="ts">
import { onBeforeUnmount, onMounted } from "vue";

const slug = "YOUR_SITE_SLUG";
let script: HTMLScriptElement | null = null;

onMounted(() => {
  if (document.getElementById(`maf-embed-root-${slug}`)) return;
  script = document.createElement("script");
  script.id = "maf-agent";
  script.src = "https://makeagent.fast/embed.js?v=20260728-widget-v2";
  script.dataset.agent = slug;
  script.async = true;
  document.body.appendChild(script);
});

onBeforeUnmount(() => {
  script?.remove();
  document.getElementById(`maf-embed-root-${slug}`)?.remove();
});
</script>

소유 컴포넌트 하나를 사용하세요. 다른 슬러그의 여러 컴포넌트는 의도적으로 여러 에이전트를 만들며 대부분 원하지 않는 동작입니다.

Vue 앱이 전체 페이지 로드 없이 인증 테넌트를 전환한다면 명시적 제거/재마운트로 처리합니다. 이전 슬러그 루트를 제거하고 신뢰할 수 있는 앱 상태에서 새 테넌트의 공개 슬러그를 검증한 뒤 새 스크립트를 추가하세요. 로더 실행 후 script.dataset.agent를 바꿔도 기존 iframe 대상은 바뀌지 않습니다.

호스트 보안 헤더는 Nuxt/Vue 출력에도 적용됩니다. CSP에 로더/프레임 오리진을 추가하고 음성을 사용할 때만 마이크를 허용하세요. 클라이언트 전용 플러그인은 응답 수준 브라우저 정책을 우회할 수 없습니다.

SSR 및 라우팅 확인하기#

1. 운영 Nuxt/Vue 빌드를 실행하고 document is not defined 오류가 없는지 확인합니다.
2. 임베드 경로를 직접 로드하고 루트 하나를 확인합니다.
3. 클라이언트 탐색으로 전체 사이트/경로 범위 동작을 확인합니다.
4. embed.js, iframe, CSP, 정확한 오리진을 점검합니다.
5. 메시지를 보내고 모바일/마이크 동작을 테스트합니다.

문제 해결#

현재 npm Vue/Nuxt 어댑터는 게시되지 않았습니다. 이 가이드는 지원 호스팅 로더를 직접 사용합니다.