Docusaurus에 Asyntai AI 챗봇을 추가하는 방법

Docusaurus 문서 사이트를 위한 단계별 가이드

임베드 코드 받기

플랫폼:

1단계: 임베드 코드 가져오기

먼저 Asyntai 대시보드로 이동하여 "임베드 코드" 섹션까지 아래로 스크롤하십시오. 다음과 같은 형태의 고유 임베드 코드를 복사하십시오:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

참고: 위의 코드는 예시일 뿐입니다. 개인 위젯 ID가 포함된 고유한 임베드 코드를 대시보드에서 복사해야 합니다.

2단계: docusaurus.config.js에 스크립트 추가 (권장)

Docusaurus 사이트의 모든 페이지에 챗봇을 추가하는 가장 좋은 방법은 설정 파일을 통하는 것입니다:

코드 편집기에서 Docusaurus 프로젝트를 여세요
프로젝트 루트에서 docusaurus.config.js 파일을 찾아서 여세요
const config = { } 객체를 찾으세요
Asyntai 위젯으로 scripts 필드를 추가하거나 업데이트하세요:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

docusaurus.config.js 파일을 저장하세요
npm run build 또는 yarn build를 실행하여 사이트를 다시 빌드하세요
로컬에서 실행 중인 경우 개발 서버를 다시 시작하세요

팁: scripts 필드는 JavaScript 소스 배열을 허용합니다. 스크립트 태그가 모든 페이지의 HTML head에 자동으로 삽입됩니다. 이것은 Docusaurus 사이트에 가장 깔끔하고 유지 관리가 쉬운 방법입니다.

대안 방법 1: 문자열 형식 (더 간단한 구문)

더 간단한 방법을 선호하신다면 scripts 배열에서 문자열 형식을 사용할 수 있습니다:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

참고: 문자열 형식을 사용할 때는 위젯 ID를 쿼리 매개변수로 포함하도록 스크립트 URL을 수정하거나, data-asyntai-id 속성을 직접 설정할 수 있는 2단계에 표시된 객체 형식을 사용해야 합니다.

대안 방법 2: 사용자 정의 Head 태그

docusaurus.config.js의 headTags 필드를 사용하여 스크립트를 추가할 수도 있습니다:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

팁: headTags 필드는 <head> 섹션에 삽입되는 정확한 HTML 태그에 대한 더 많은 제어를 제공합니다. 이 방법은 scripts 필드를 사용하는 것과 기능적으로 동일합니다.

대안 방법 3: 사용자 정의 HTML 템플릿 (고급)

HTML 템플릿에 대한 완전한 제어가 필요한 고급 사용자의 경우:

새 디렉토리를 생성하세요: src/theme (존재하지 않는 경우)
파일을 생성하세요: src/theme/Root.js
스크립트를 동적으로 삽입하기 위해 다음 코드를 추가하세요:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

파일을 저장하고 사이트를 다시 빌드하세요

중요: Root.js 컴포넌트는 전체 애플리케이션을 감쌉니다. 이 고급 방법은 사용자 정의 JavaScript 로직이 필요하거나 구성 파일 방식으로 충족할 수 없는 특정 요구 사항이 있는 경우에만 사용해야 합니다.

대안 방법 4: Footer 컴포넌트 스위즐링

스크립트를 포함하도록 푸터를 사용자 정의할 수 있습니다:

스위즐 명령을 실행하세요: npm run swizzle @docusaurus/theme-classic Footer -- --eject
src/theme/Footer/에 Footer 컴포넌트의 사본이 생성됩니다
스크립트 태그를 포함하도록 Footer 컴포넌트를 편집하세요
푸터의 닫는 태그 앞에 스크립트를 추가하세요
저장하고 사이트를 다시 빌드하세요

참고: 스위즐링은 Docusaurus 컴포넌트에 대한 완전한 제어를 제공하지만, 해당 컴포넌트를 직접 유지 관리해야 합니다. Docusaurus 업데이트 시 스위즐된 컴포넌트는 자동으로 업데이트되지 않습니다.

3단계: 빌드 및 배포

코드를 추가한 후 Docusaurus 사이트를 빌드하고 배포하세요:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

팁: 개발 중에는 npm start 또는 yarn start를 실행하여 로컬에서 변경 사항을 미리 확인하세요. 모든 페이지의 오른쪽 하단에 챗봇이 나타나야 합니다.

4단계: 설치 확인

변경 사항을 배포한 후 새 브라우저 탭에서 문서 사이트를 여세요. 오른쪽 하단에 채팅 위젯 버튼이 보여야 합니다. 클릭하여 올바르게 열리고 작동하는지 확인하세요.

위젯이 보이지 않나요? 변경 후 사이트를 다시 빌드했는지 확인하세요. 대시보드에서 YOUR_WIDGET_ID를 실제 위젯 ID로 교체했는지 확인하세요. 브라우저 캐시를 지우거나 시크릿 모드로 확인하세요. 브라우저 콘솔(F12)을 열어 JavaScript 오류가 없는지 확인하세요.