React 챗봇: React 앱에 AI 챗봇 추가하기(Vite, CRA, SPA)

코드를 건드리기 전에 두 가지가 필요해요.

• Nexoply 계정과 챗봇 키. 무료로 가입한 다음(무료 플랜에는 월 대화 50건이 포함되고 카드가 필요 없어요) 대시보드에서 챗봇을 여세요. 그곳의 설치 코드에 키가 이미 들어 있어요. 이 키는 공개용이에요. 비밀이 아니고 계정에 접근할 수 있게 해 주지도 않으므로 클라이언트 코드에 넣어도 괜찮아요.
• 어시스턴트가 답할 때 쓰는 비즈니스 정보: 서비스와 가격, 자주 묻는 질문, 정책, 영업시간, 서비스 지역이에요. 가장 빠른 방법은 웹사이트 주소를 입력해 Nexoply가 공개 페이지를 가져오게 하는 거예요. JavaScript로 만든 페이지도 읽으므로 React 사이트도 문제없어요. 승인하기 전에는 아무것도 추가되지 않아요.

src/components/Chatbot.tsx를 만드세요. 이 컴포넌트는 스스로 아무것도 렌더링하지 않아요. 페이지에 Nexoply 스크립트를 한 번 추가하고, 채팅 버튼과 창은 위젯이 그려요.

// src/components/Chatbot.tsx
import { useEffect } from "react";

type ChatbotProps = { chatbotKey: string };

export function Chatbot({ chatbotKey }: ChatbotProps) {
  useEffect(() => {
    // 키가 없거나 스크립트가 이미 페이지에 있으면 할 일이 없어요.
    if (!chatbotKey || document.querySelector("script[data-chatbot]")) return;
    const s = document.createElement("script");
    s.src = "https://nexoply.com/widget.js";
    s.async = true;
    s.dataset.chatbot = chatbotKey;
    document.body.appendChild(s);
  }, [chatbotKey]);

  return null;
}

방문 내내 마운트된 상태로 유지되는 컴포넌트(보통 App)에서 한 번만 렌더링하세요. Vite에서는 .env 파일에 VITE_NEXOPLY_KEY=YOUR-KEY를 넣으세요.

// src/App.tsx
import { Chatbot } from "./components/Chatbot";

export default function App() {
  return (
    <>
      {/* 레이아웃과 라우트 */}
      <Chatbot chatbotKey={import.meta.env.VITE_NEXOPLY_KEY} />
    </>
  );
}

이 컴포넌트는 Vite나 Create React App의 TypeScript 프로젝트에서 그대로 작동해요. 일반 JavaScript라면 파일 이름을 Chatbot.jsx로 바꾸고 ChatbotProps 타입을 지우세요. Create React App에는 import.meta.env가 없으니 대신 process.env.REACT_APP_NEXOPLY_KEY를 전달하세요. 평범한 컴포넌트이므로 {hasConsent && <Chatbot chatbotKey={key} />}처럼 조건부로 렌더링해서, 방문자가 쿠키 배너에 동의한 뒤에만 채팅을 불러올 수도 있어요.

• 정리 함수가 없는 이유. 위젯은 한 번 로드되면 제거하는 API가 없고 React 트리 밖에 있으므로, 컴포넌트가 언마운트되어도 되돌릴 것이 없어요.
• StrictMode에서도 괜찮은 이유. 개발 환경에서 React StrictMode는 이펙트를 두 번 실행해요. querySelector 확인이 두 번째 실행을 건너뛰고, 스크립트가 두 번 추가되더라도 위젯은 챗봇 키당 한 번만 마운트돼요. 같은 이유로 핫 리로드도 안전해요.
• 속성을 유지하세요. 위젯은 자기 스크립트 태그에서 설정을 읽으므로, 태그에 data-chatbot 속성과 widget.js가 포함된 src가 있어야 해요. s.dataset.chatbot을 설정하면 이 속성이 만들어져요.

코드에서 로딩을 제어할 필요가 없다면 컴포넌트는 건너뛰세요. 모든 React SPA에는 HTML 셸이 있어요. Vite에서는 프로젝트 루트의 index.html이고, Create React App에서는 public/index.html이에요. 닫는 </body> 태그 바로 앞에 코드를 붙여 넣으세요.

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>

  <!-- Nexoply AI 챗봇 -->
  <script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>
</body>

YOUR-KEY를 챗봇 페이지의 키로 바꾸세요. 스크립트는 비동기로 로드되므로 앱 렌더링을 막지 않아요. 페이지가 로드될 때 채팅 창이 열리게 하려면 태그에 data-open="true"를 추가하세요. 설치는 이게 전부예요. 다시 빌드해서 배포하면 모든 라우트에 버튼이 나타나요.

React 챗봇을 검색하면 두 종류의 도구가 나오는데, 해결하는 문제가 서로 달라요.

• 챗봇 UI 라이브러리는 채팅 자체를 위한 React 컴포넌트를 제공해요. 메시지 목록, 입력창, 말풍선, 때로는 미리 짜인 대화 단계까지요. UI 뒤의 모든 것은 직접 만들어야 해요. 고정된 시나리오나 내 API 키로 AI 모델을 호출하는 백엔드, 그리고 답변의 근거가 되는 콘텐츠, 대화 저장, 악용 방지까지요. 채팅이 제품의 일부일 때, 예를 들어 사용자 자신의 데이터를 다루는 어시스턴트라면 잘 맞아요.
• 호스팅형 AI 챗봇인 Nexoply는 UI, AI, 백엔드를 함께 제공해요. 추가하거나 가져온 비즈니스 정보(서비스와 가격, 자주 묻는 질문, 정책, 영업시간)로만 방문자의 질문에 답하고, 모르는 내용은 모른다고 말해요. AI 키도 서버 코드도 없고, 대화, 답하지 못한 질문, 스팸 방지는 대시보드에서 관리해요. 비즈니스에 관한 질문에 답해야 하는 고객용 웹사이트에 잘 맞아요.

인터페이스와 모델을 완전히 제어하고 싶다면 라이브러리로 시작하세요. 백엔드를 만들거나 운영하지 않고 방문자의 질문에 답하는 것이 목표라면 호스팅형 위젯이 훨씬 수월해요. Nexoply가 비즈니스 정보로 답하는 방식을 확인해 보세요.

• React 트리 밖에 있어요. 위젯은 #root 요소 밖의 document.body에 마운트되므로, 리렌더링이나 라우트 변경으로 제거되거나 스타일이 바뀌지 않아요.
• 양방향 Shadow DOM. 내 CSS(Tailwind, CSS 모듈, 전역 리셋)가 채팅에 스며들지 않고, 채팅의 CSS도 앱에 스며들지 않아요.
• 라우트 변경도 그대로 작동해요. React Router나 히스토리 기반 라우터에서 방문자는 이동하는 동안 대화를 이어 가고, URL이 바뀌면 페이지 규칙(예: /pricing에서만 사이드 탭 표시)을 다시 확인해요. 추가 코드는 필요 없어요.
• 쿠키 없음. 익명 방문자 ID는 localStorage에, 현재 대화는 sessionStorage에 저장해요.

히어로 섹션이나 가격 페이지에 "채팅으로 문의하기" 버튼을 두고 싶나요? window에서 nexoply:open-chat 이벤트를 발생시키세요.

export function ChatButton() {
  return (
    <button onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}>
      채팅으로 문의하기
    </button>
  );
}

import는 필요 없어요. 위젯이 window에서 이 이벤트를 기다리고 있어요. 직접 만든 버튼만 보여 주고 싶다면 대시보드에서 페이지 규칙으로 메시지 버튼을 "버튼 없음"으로 설정하세요.

배포하기 전에 다음 세 가지 설정을 확인하세요.

• 허용된 웹사이트. 이 웹사이트에서만 허용(대시보드 → 챗봇)을 입력했다면 Vite는 localhost:5173, Create React App은 localhost:3000처럼 개발 호스트를 포트와 함께 추가하거나, 테스트하는 동안 목록을 비워 두세요.
• Content-Security-Policy. 앱이 CSP 헤더나 메타 태그를 보낸다면 script-src, connect-src, img-src에 https://nexoply.com을 허용하세요.
• 처음부터 끝까지 확인하기. 앱을 실행하고 채팅 버튼을 클릭해 실제 질문을 한 다음, 대시보드의 대화에서 그 질문을 찾아보세요.

그래도 버튼이 나타나지 않는다면 다음을 확인하세요.

• 키가 비어 있어요. 키가 없으면 컴포넌트는 아무것도 로드하지 않아요. import.meta.env.VITE_NEXOPLY_KEY를 출력해 보세요. Vite는 VITE_로 시작하는 변수만 노출하고, .env를 수정한 뒤에는 개발 서버를 다시 시작해야 해요.
• 요청이 차단됐어요. 브라우저 콘솔과 Network 탭에서 CSP 오류나 차단된 widget.js가 있는지 살펴보세요.
• 챗봇이 꺼져 있어요. 챗봇 사용 스위치가 켜져 있는지 확인하세요.
• 광고 차단기. 드물게 브라우저 확장 프로그램이 채팅 위젯을 차단해요. 확장 프로그램이 없는 시크릿 창에서 시도해 보세요.

스크립트를 한 번 넣으면 코드를 다시 건드릴 필요가 없어요. 대시보드에서 바꾼 내용은 약 1분 안에 사이트에 반영돼요. 챗봇 → 맞춤 설정에서 메시지 버튼(아이콘이나 직접 올린 이미지·SVG, 텍스트 라벨, 모양, 크기, 색상, 위치)을 꾸미거나, 대신 화면 가장자리의 사이드 탭을 쓸 수 있어요. 휴대폰에서는 다른 디자인을 설정하고, 페이지 규칙으로 선택한 라우트(예: /pricing이나 /services/*)에서 모양을 바꿀 수 있어요. 채팅 창에는 내 글꼴, 색상, 로고가 적용되고, 시작 화면에는 예약, 전화, WhatsApp 같은 버튼을 넣을 수 있어요.

다른 프레임워크를 쓰나요? next/script로 Next.js에 챗봇을 추가하는 방법이나 Vue·Nuxt 챗봇 가이드를 참고하세요. WordPress 마케팅 사이트라면 WordPress 가이드를 보세요. 전체적인 내용은 어시스턴트가 비즈니스를 배우는 방식을 읽거나 플랜과 대화 한도를 비교해 보세요.