위젯 설치

위젯 설치는 콘솔에서 발급한 삽입 코드를 웹사이트에 넣는 작업입니다. 워드프레스, 정적 페이지, 직접 개발한 사이트 모두 같은 방식이며, HTML을 한 줄 추가할 수 있으면 됩니다. 카페24 쇼핑몰과 쇼피파이 상점은 앱 설치 시 스크립트가 자동으로 들어가므로 이 문서의 대상이 아닙니다.

처음 설치할 때 10분 정도 걸립니다. 상품 카드와 지식 수집까지 정상 동작하려면 사이트 쪽 조건이 맞아야 하며, 그 조건은 설치 전 사이트 준비에 정리되어 있습니다.

사전 준비

관리자 계정과 멤버십 : 위젯 키 발급과 삽입 코드 열람은 관리자에게만 허용됨
사이트 캐스팅 완료 : 회원가입과 초기 세팅의 캐스팅 단계
사이트 코드 편집 권한 : 공통 레이아웃 또는 푸터에 <script> 태그를 넣을 수 있어야 함
운영 배포 방법 확인 : 코드를 반영한 뒤 실제 도메인에서 확인할 수 있어야 함

위젯 키와 삽입 코드

관리자 계정으로 로그인한 뒤 사이드바 "에이전트 연결"(/casting)을 엽니다. 캐스팅해 보관한 결과가 있으면 "다음 할 일" 카드의 "이 주소로 연결"을 누르고, 확인 창에서 "연결"을 누르면 설치에 필요한 것이 한 번에 준비됩니다. 보관한 결과가 없으면 "사이트 캐스팅하기"로 공개 캐스팅 페이지에서 먼저 캐스팅합니다.

연결하면 세 가지가 차례로 진행됩니다.

위젯 키 발급: 캐스팅한 주소의 도메인으로 키를 만듭니다. 이미 발급된 키가 있으면 그 키를 그대로 사용합니다.
사이트 분석: 페이지를 다시 읽어 업종과 다루는 내용을 파악합니다. 하루 분석 한도(10회)에서 1회를 씁니다.
페르소나 적용: 분석 결과에 맞는 페르소나를 에이전트에 적용합니다.

분석이 실패해도 키는 정상적으로 발급되므로 설치를 이어갈 수 있습니다.

연결이 끝나면 같은 화면의 "설치 안내"에 코드가 나옵니다. "스크립트 태그"와 "React · Next.js" 두 탭 중 사이트 환경에 맞는 쪽을 고르면 키가 채워진 코드가 표시됩니다. 같은 코드는 사이드바 "위젯 설정"(/widget)의 "임베드 코드"에서도 다시 복사할 수 있습니다.

키 값은 관리자에게만 표시됩니다. 설치를 개발 담당자가 맡는 경우에는 관리자가 코드를 복사해 전달합니다. 키와 도메인의 관계는 위젯 키와 도메인에서 설명합니다.

스크립트 태그 삽입

"스크립트 태그" 탭의 코드를 복사해 사이트의 </body> 바로 위에 붙여넣습니다. 워드프레스는 테마의 푸터 영역, 정적 사이트는 공통 레이아웃 파일이 그 위치입니다.

HTML
<script src="https://addon-cdn.voidx.ai/latest/voidx-ai-addon.standalone.js"></script>
<script>
  window.VoidxAIAddon.init({ apiKey: 'YOUR_API_KEY' });
</script>

YOUR_API_KEY 자리에 들어가는 값이 위젯 키입니다. 화면에서 복사한 코드에는 실제 값이 채워져 있습니다.

<head> 안에 넣으면 동작하지 않습니다. 위젯이 그려질 문서 본문이 아직 없는 시점에 실행되기 때문입니다.

React나 Next.js로 만든 사이트는 이 단계 대신 아래 컴포넌트 방식을 사용합니다.

React · Next.js 컴포넌트 삽입

스크립트 태그 대신 컴포넌트로 붙이는 방식입니다. 먼저 패키지를 설치합니다.

Bash

npm install @voidx-ai/react

키는 소스에 직접 쓰지 않고 환경변수에 넣습니다. 이 방식에서는 키가 브라우저로 내려가는 번들에 포함되므로, 소스에 적으면 저장소에 그대로 남습니다.

Bash

NEXT_PUBLIC_VOIDX_API_KEY=YOUR_API_KEY

루트 레이아웃에 컴포넌트를 배치합니다.

TSX
import { VoidxAddon } from '@voidx-ai/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <VoidxAddon apiKey={process.env.NEXT_PUBLIC_VOIDX_API_KEY!} />
        {children}
      </body>
    </html>
  );
}

컴포넌트는 스크립트를 한 번만 불러오고, 언마운트될 때 위젯을 정리합니다. 언어 변경이나 기능 끄기 같은 세부 옵션은 SDK 레퍼런스에 있습니다.

운영 사이트의 버전 고정

위 코드의 /latest/는 새 버전이 나올 때마다 바뀌는 주소입니다. 시연이나 테스트에는 적합하지만, 운영 중인 사이트에서는 예고 없이 동작이 바뀔 수 있습니다.

주소	성격	용도
`/latest/`	배포마다 갱신	데모, 테스트
`/v{버전}/`	발행 후 불변	운영 사이트

운영 사이트에서는 버전을 고정하고, 새 버전을 확인한 뒤에 올리는 방식을 권장합니다.

HTML
<script src="https://addon-cdn.voidx.ai/v{버전}/voidx-ai-addon.standalone.js"></script>

React 컴포넌트를 쓰는 경우에는 scriptUrl 속성에 같은 주소를 넘깁니다.

세팅 확인

코드를 반영한 페이지를 브라우저에서 엽니다.

항목	확인 방법
위젯 표시	화면 구석에 캐릭터가 나타나고, 3~7초 안에 캐릭터 위로 첫 인사 말풍선이 뜨는지 확인
대화	캐릭터를 눌러 대화창을 열고 질문을 보내 답변이 오는지 확인
상품 카드	상품 상세 페이지에서 그 상품에 대해 물었을 때 답변 아래에 상품 카드가 붙는지 확인. 카드가 붙지 않으면 사이트 마크업이 상품으로 인식되지 않는 경우가 대부분이며, 설치 전 사이트 준비의 상품 인식 절을 확인

위젯이 보이지 않을 때 가장 흔한 원인은 세 가지입니다.

확인할 것	자주 나는 실수
접속한 주소	위젯 키는 발급받은 도메인에서만 동작. `localhost`나 다른 도메인에서 열어보는 경우
코드 위치	`</body>` 바로 위가 아닌 `<head>` 안에 넣은 경우
키 값	키를 재발급한 뒤 사이트에 이전 키가 남아 있는 경우

셋 다 해당하지 않으면 위젯 미표시의 조치 방법을 순서대로 확인합니다.

다음 단계

초기화 옵션, 런타임 API, 이벤트는 SDK 레퍼런스를 참고하세요.
위젯 기능과 언어 설정, 삽입 코드 재발급은 위젯 설정을 참고하세요.
방문자에게 보이는 화면 요소와 동작은 대화 화면을 참고하세요.

사전 준비#

위젯 키와 삽입 코드#

스크립트 태그 삽입#

React · Next.js 컴포넌트 삽입#

운영 사이트의 버전 고정#

세팅 확인#

다음 단계#

다음 단계

사전 준비

위젯 키와 삽입 코드

스크립트 태그 삽입

React · Next.js 컴포넌트 삽입

운영 사이트의 버전 고정

세팅 확인

다음 단계