Keural Kit

Keural Kit은 스크립트 하나로 Keural 화면을 내 페이지에 넣습니다. 화면은 Shadow DOM 안에 그려지므로 내 페이지의 CSS와 섞이지 않습니다. Kit은 Keural 웹 배포 때 함께 갱신됩니다. 배포 후에도 이전 화면이 보이면 브라우저·CDN 캐시를 비우고 window.KeuralKit.__build로 빌드 시각을 확인합니다.

불러오기링크 복사

Kit은 사용하는 Keural 환경의 웹 주소에서 불러옵니다. keural.ai는 https://keural.ai, 온프레미스·전용 환경은 그 환경의 Keural 웹 주소입니다. 스크립트보다 먼저 Kit이 호출할 서버 주소를 window.__KEURAL_ENV__에 설정합니다. 세 주소는 같은 환경의 주소여야 하며, 도입 시 담당자에게 받습니다.

<script>
  window.__KEURAL_ENV__ = {
    NEXT_PUBLIC_API_BASE_URL: '<KEURAL_API_URL>',
    NEXT_PUBLIC_FAST_API_BASE_URL: '<KEURAL_AGENT_URL>',
    NEXT_PUBLIC_MODE: 'prd',
  };
</script>
<script src="<KEURAL_WEB_URL>/plugin/kit/keural.js" async></script>

같은 Kit을 두 번째 도메인에서도 쓰려면 NEXT_PUBLIC_ADDITIONAL_FRONTEND_URL, NEXT_PUBLIC_ADDITIONAL_API_BASE_URL, NEXT_PUBLIC_ADDITIONAL_FAST_API_BASE_URL 세 값을 모두 설정합니다. 하나라도 빠지면 오류가 납니다. 값은 경로 없는 https:// 주소입니다.

스크립트가 로드되면 window.KeuralKit이 생성됩니다. React 같은 SPA에서는 스크립트가 한 번만 로드되도록 로더를 씁니다.

export function loadKeuralKit(src = '<KEURAL_WEB_URL>/plugin/kit/keural.js') {
  if (window.KeuralKit) return Promise.resolve(window.KeuralKit);
  return new Promise((resolve, reject) => {
    const s = document.createElement('script');
    s.src = src;
    s.async = true;
    s.onload = () => resolve(window.KeuralKit);
    s.onerror = () => {
      s.remove();
      reject(new Error('Keural Kit failed to load'));
    };
    document.head.appendChild(s);
  });
}

채팅 넣기링크 복사

const el = document.getElementById('keural-chat')!;

window.KeuralKit.mountChat(el, {
  userInfo: { userId: user.id, name: user.name },
  colorMode: 'light',
  initialData: { message: '이번 분기 매출 요약해 줘', room_name: '분기 보고' },
  onSessionCreated: (roomId) => router.push(`/c/${roomId}`),
  onError: () => router.push('/'),
});

// 화면을 떠날 때
window.KeuralKit.unmount(el);

• 기존 대화를 열려면 sessionId에 대화 ID를 넣습니다.
• initialData는 새 대화를 열 때만 넣습니다. 기존 대화를 열 때 넣으면 같은 메시지가 다시 전송됩니다.
• userInfo.userId가 없으면 비로그인으로 처리됩니다. 로그인 정보가 준비된 뒤 마운트합니다.

메서드링크 복사

mount*·update* 메서드는 colorMode와 userInfo를 함께 받고, unmount(el)은 요소만 받습니다. update*는 같은 요소를 새 옵션으로 다시 그립니다. 창을 열고 닫을 때는 open 값을 바꿔 update*를 호출합니다. 같은 요소에 mount*를 다시 호출하면 기존 화면을 재사용합니다.

mountChat 옵션링크 복사

initialData링크 복사

화면 언어링크 복사

Kit 화면은 한국어로 표시됩니다.

설정과 로그인링크 복사

• 사용자 설정은 Keural 웹이나 앱에서 바꾸며, Kit 화면은 그 설정을 따릅니다.
• 로그인은 내 서비스가 처리하고, Kit에는 로그인된 사용자 정보만 넘깁니다.