SDK 레퍼런스

SDK 레퍼런스는 위젯의 초기화 옵션, 런타임 API, 이벤트를 정리한 참조 문서입니다. 설치 코드 두 줄만으로 위젯은 동작하므로, 언어를 바꾸거나 특정 기능을 끄거나 사이트 코드에서 위젯 상태를 받아야 할 때 이 문서를 봅니다.

옵션은 전부 선택 사항입니다. 지정하지 않으면 아래 표의 기본값으로 동작합니다.

스크립트 주소#

스크립트를 불러오면 window.VoidxAIAddon이 생기고, init(config)를 호출하면 위젯이 그려집니다. 위젯은 호스트 사이트 스타일에 영향을 주지 않고 영향을 받지도 않습니다.

초기화 옵션#

const voidx = window.VoidxAIAddon.init({
  apiKey: 'YOUR_API_KEY',
  locale: 'en',
  features: { voice: false, productPress: true },
  contact: 'help@example.com',
});

features#

voice: false면 플랜과 무관하게 꺼집니다. 켰는데 음성 버튼이 보이지 않으면 코드가 아니라 계약을 확인합니다.

theme#

hoverTargets#

커서가 어떤 요소 위에 1.5초 머물렀을 때 voidx:hover:detected 이벤트를 낼지 정합니다. ids 정확 일치, classNames 정확 일치, idPatterns, classNamePatterns 순으로 판정합니다.

productPress#

features.productPress를 켰을 때의 세부 동작입니다.

런타임 API#

init()이 돌려주는 인스턴스로 위젯을 제어합니다.

const voidx = window.VoidxAIAddon.init({ apiKey: 'YOUR_API_KEY' });

voidx.show();
voidx.on('voidx:chat:open', () => console.log('opened'));

이벤트#

on()으로 받거나 같은 이름의 window CustomEvent로도 받을 수 있습니다.

React 래퍼 @voidx-ai/react#

npm install @voidx-ai/react

VoidxAddon 컴포넌트가 스크립트를 불러와 init()을 대신 호출하고, 언마운트될 때 destroy()까지 처리합니다. React 18 이상이 필요합니다.

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

function OpenChatButton() {
  const voidx = useVoidx();
  return <button onClick={() => voidx?.show()}>상담하기</button>;
}

래퍼의 features 타입에는 productPress 키가 없습니다. TypeScript에서 이 기능을 켜려면 객체를 단언해 전달합니다.

import type { VoidxFeatures } from '@voidx-ai/react';

const features = { chat: true, productPress: true } as VoidxFeatures;
<VoidxAddon apiKey={key} features={features} />;

apiKey나 disabled가 바뀔 때만 위젯을 다시 초기화합니다. 콜백은 처음 초기화 시점의 값을 씁니다.

다음 단계#

• 설치 순서와 버전 고정은 위젯 설치를 참고하세요.
• 상품 판정 규칙은 설치 전 사이트 준비를 참고하세요.
• 화면에서 기능과 언어를 바꾸는 방법은 위젯 설정을 참고하세요.