React 및 Next.js

오리진 및 범위 준비하기#

에이전트 임베드를 활성화한 뒤 정확한 로컬/미리보기/운영 오리진을 허용합니다. 모든 클라이언트 탐색에서 실행 버튼을 유지할지(루트 레이아웃) 일부 경로에만 둘지(중첩 레이아웃/컴포넌트) 결정하세요.

Next.js App Router#

실행 버튼을 소유한 레이아웃이 렌더링하는 컴포넌트에서 next/script를 사용합니다. 슬러그는 공개 가능하며 API 키나 비밀 환경 변수를 사용하지 마세요.

import Script from "next/script";

export function AgentEmbed() {
  return (
    <Script
      id="maf-agent"
      src="https://makeagent.fast/embed.js?v=20260728-widget-v2"
      strategy="afterInteractive"
      data-agent="YOUR_SITE_SLUG"
      data-position="right"
      data-label="문의하기"
    />
  );
}

사이트 전체 에이전트는 app/layout.tsx에서 <AgentEmbed />를 한 번 렌더링하고 경로 그룹에는 중첩 레이아웃을 사용합니다. 모든 페이지 컴포넌트에서 별도 복사본을 렌더링하지 마세요. afterInteractive는 서버 DOM 접근을 피하고 초기 HTML 파싱을 차단하지 않습니다.

Next.js Pages Router에서는 사이트 전체 동작을 위해 같은 컴포넌트를 pages/_app.tsx에서 한 번 렌더링합니다. 특정 페이지를 나갈 때 에이전트도 제거해야 할 때만 개별 페이지에서 렌더링하세요. 외부 스크립트는 이미 React 트리 밖에 DOM을 만들었으므로 그 경우 아래 명시적 effect/정리 패턴을 사용합니다.

Next.js 없는 React#

effect에서 스크립트를 생성합니다. 안정적인 스크립트 ID는 개발 Strict Mode에서 중복 삽입을 방지합니다. 컴포넌트가 경로 범위라면 정리에서 스크립트와 로더가 만든 루트를 모두 제거해야 합니다.

import { useEffect } from "react";

const slug = "YOUR_SITE_SLUG";

export function AgentEmbed() {
  useEffect(() => {
    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.async = true;
    document.body.appendChild(script);

    return () => {
      script.remove();
      document.getElementById(`maf-embed-root-${slug}`)?.remove();
    };
  }, []);

  return null;
}

사이트 전체 실행 버튼은 라우터 위에 마운트하고 경로 기반 언마운트를 피하세요. 루트를 유지하면 탐색 중 iframe/대화가 보존됩니다.

환경 설정#

빌드 시 공개 변수에는 비밀이 아닌 슬러그를 둘 수 있습니다. 렌더링 전에 검증하고 실제 MAF API 키/제공자 자격 증명은 서버에만 보관하세요. 슬러그가 없으면 로더는 경고하고 실행 버튼을 만들지 않습니다.

하나의 React 빌드가 여러 고객 테넌트를 제공한다면 이미 실행된 스크립트의 data-agent를 바꾸지 마세요. 현재 테넌트에 안정적인 슬러그 하나를 주고 인증된 테넌트 전환 시 이전 슬러그 루트를 제거한 뒤 새 스크립트를 마운트합니다. 신뢰할 수 없는 쿼리 매개변수가 교차 테넌트 슬러그를 선택하게 하지 마세요.

하이드레이션 및 탐색 확인하기#

1. 공개 경로를 직접 로드하고 실행 버튼 하나를 확인합니다.
2. 클라이언트 탐색으로 유지해야 할 경로를 이동합니다.
3. 중첩/경로 범위 설치는 밖으로 이동해 스크립트/루트가 모두 사라지는지, 돌아와 새 실행 버튼 하나가 생기는지 확인합니다.
4. Network/CSP를 확인하고 실제 메시지를 테스트합니다.
5. 운영 빌드를 실행합니다. 개발 Strict Mode만으로 최종 동작을 판단하지 마세요.

문제 해결#

현재 npm React/Next 어댑터는 게시되지 않았습니다. 이 예시는 지원되는 Public API와 독립적인 공개 로더를 사용합니다.