Chat 참조

product: 'chat'은 Kaleidr Chat 패널을 웹페이지에 마운트합니다. 패널은 iframe이 아니라 페이지 문서 안에서 실행됩니다. 전달한 지도 객체 또는 지정한 Kaleidr Viewer/Tile 요소에 연결하거나, 지도 없이 채팅 전용 패널로 실행할 수 있습니다.

이 페이지는 기능 참조 문서입니다. 첫 페이지를 만들려면 Mapbox, MapLibre, Google Maps, Leaflet 가이드부터 시작하세요.

요구 사항

항목	내용
요금제	Free 이상
인증 정보	게시 가능한 키(kld_pk_live_…) 또는 Control Tower를 켠 Studio 게시 지도의 ID
범위	ai. 모든 새 키에 기본으로 포함됩니다.
허용 출처	키에 허용 출처 목록이 있으면 페이지의 출처가 포함되어야 합니다.
로더	https://cdn.kaleidr.com/embed/v1/kaleidr.js
지도 라이브러리	선택 사항입니다. 지원 지도를 참조하세요.

최소 마운트

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,              // your live map object
  contained: true,  // dock inside #chat
});

Kaleidr.mount(target, options)는 CSS 선택자나 요소를 target으로 받습니다. 핸들을 동기적으로 반환하며 마운트에 실패해도 예외를 던지지 않습니다. Chat 번들 로드와 키 교환은 백그라운드에서 진행되고, 둘 중 하나가 실패하면 콘솔에 오류 하나가 기록되며 아무것도 표시되지 않습니다. 옵션 객체 없이 마운트하는 경우만 예외입니다. Kaleidr.mount('#chat')은 TypeError를 발생시킵니다.

마운트 옵션

모든 옵션은 마운트 시 한 번만 읽습니다. 값을 바꾸려면 destroy()를 호출한 뒤 다시 마운트하세요. 테마만 예외이며 setTheme으로 변경할 수 있습니다.

옵션	유형	기본값	필수	Chat에서의 동작
product	'chat'	없음	예	Chat 제품을 선택합니다.
publishableKey	문자열	없음	shareId가 없으면 필수	kld_pk_… 키입니다. SDK가 패널의 첫 요청 전에 이 키를 세션 토큰으로 교환합니다. kld_sk_… 서버 키는 브라우저에서 거부되며 콘솔 오류만 기록하고 요청은 보내지 않습니다.
shareId	문자열	없음	publishableKey가 없으면 필수	Kaleidr AI 타일에서 Control Tower를 켠 Studio 게시 지도의 ID입니다. 키가 없을 때만 사용하며 질문 비용은 지도 소유자에게 청구됩니다. 게시된 지도 자체의 뷰어에 이미 이 패널이 표시됩니다. 게시된 지도의 Kaleidr AI를 참조하세요.
map	실행 중인 지도 객체	없음	아니요	도우미가 핀을 놓고 화면을 이동시키는 지도입니다. 객체를 통해 라이브러리를 식별합니다. 채팅 전용 패널에서는 생략하세요.
mapTarget	CSS 선택자	없음	아니요	같은 페이지에서 패널이 제어할 Viewer 또는 Tile <kaleidr-map> 요소입니다. map을 지정하면 무시됩니다.
contained	불리언	false	아니요	true는 패널을 마운트 대상 안에 배치합니다. 대상에는 위치와 크기가 지정되어야 합니다. false는 document.body에 추가하여 뷰포트 왼쪽 위에 고정 창으로 표시합니다.
lang	문자열	페이지의 <html lang>이 올바른 언어 태그이면 그 값, 아니면 영어	아니요	en, ko, pt-BR 같은 BCP 47 태그로 지정하는 답변 언어입니다. 언어를 참조하세요.
title	문자열	대화에서 가져온 제목	아니요	채팅 창 헤더에 표시할 제목입니다. 제목과 자리표시자를 참조하세요.
placeholder	문자열	Ask Kaleidr	아니요	입력창의 자리표시자 텍스트입니다.
theme	객체 또는 객체를 나타내는 JSON 문자열	없음	아니요	적용할 CSS 사용자 지정 속성입니다. 예: { '--highlight-color': '#7c3aed' }. :root에 기록되어 페이지 전체에 영향을 줍니다.
enabled	불리언	없음	아니요	이 마운트에 대한 활성화 제어 값입니다. false이면 마운트가 보류됩니다. kaleidr.js를 참조하세요.
apiBase	URL	https://api.kaleidr.com/inference-api	아니요	세션 교환과 질문을 보내는 API입니다. /inference-api 경로를 포함해야 합니다.
base	URL	https://cdn.kaleidr.com	아니요	Chat 번들을 로드할 출처입니다. 출처만 사용되며 Kaleidr CDN(https://cdn.kaleidr.com), kaleidr.js를 로드한 출처 또는 현재 페이지 출처만 허용됩니다. 기본 주소 재정의를 참조하세요.
apiKey	문자열	없음	아니요	publishableKey의 더 이상 권장되지 않는 별칭입니다.

Chat에서 사용하지 않는 옵션

Chat 마운트에는 center, zoom, pitch, bearing, styleId, viewerBase, tileBase가 전달되어도 무시됩니다. 패널이 초기 카메라를 설정하지 않으므로 지도는 사용자가 정한 뷰를 유지합니다.

존재하지 않는 옵션

특정 지도 라이브러리를 강제로 사용하게 하거나 음성 기능 또는 콜백을 지정하는 옵션은 없습니다. 현재 제공하지 않는 기능을 참조하세요.

언어

lang은 패널이 답변하는 언어를 지정하며 모든 질문에 함께 전송됩니다.

전달한 값	사용 언어
lang: 'ko' 또는 요소의 lang="ko"	지정한 언어 태그를 그대로 사용합니다.
lang 없이 <html lang="fr">가 있는 페이지	올바른 태그라면 페이지 언어를 사용합니다.
lang 없이 <html lang>이 없거나 형식이 잘못된 페이지	영어를 사용합니다.

• 허용 값: en, ko, ja, pt-BR, zh-Hant 같은 BCP 47 언어 태그입니다. 35자를 초과하면 API가 거부하고 모든 질문이 422 lang_too_long으로 실패합니다.
• 페이지 언어는 형식이 올바를 때만 가져옵니다. 문자 23개 뒤에 하이픈으로 구분된 18자리 영숫자 하위 태그를 최대 세 개까지 추가할 수 있습니다. 치환되지 않은 템플릿 자리표시자는 건너뛰고 영어를 사용하므로 잘못된 <html lang> 때문에 Chat이 중단되지는 않습니다.
• 명시적으로 전달한 lang이 항상 우선합니다.
• lang은 제목이나 자리표시자를 번역하지 않습니다. 기본값은 영어입니다. title과 placeholder를 lang과 같은 언어로 지정하세요.

제목과 자리표시자

Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map,
  contained: true,
  lang: 'fr',
  title: 'Demandez à propos d’un lieu',
  placeholder: 'Posez une question',
});

• **placeholder**는 기본 입력 문구인 “Ask Kaleidr”를 대체합니다.
• **title**은 채팅 창 제목입니다. 대화가 시작되면 창과 헤더가 표시되며 이후 모든 대화의 헤더에 지정한 제목이 나타납니다. title이 없으면 방문자의 첫 질문을 줄여서 보여 줍니다. 최소화된 채팅은 title 지정 여부와 관계없이 방문자의 첫 질문에서 가져온 자체 대화 제목을 표시합니다.
• 요소에서는 제목 속성이 **chat-title**이며 title이 아닙니다. HTML의 title은 요소 위에 마우스를 올렸을 때 표시되는 브라우저 툴팁입니다.

사용할 인증 정보

전달한 값	결과
publishableKey	키를 세션으로 교환합니다. 함께 지정된 shareId는 무시합니다.
shareId만 전달	게시 지도를 사용해 세션을 교환합니다.
둘 다 없음	패널은 표시되지만 모든 질문이 실패합니다. 마운트 시 오류를 기록하지 않습니다.

사용할 지도

전달한 값	결과
map	해당 지도 객체입니다. 함께 지정한 mapTarget은 무시합니다.
mapTarget만 전달	선택자와 일치하는 Kaleidr Viewer 또는 Tile 요소입니다. 지도가 필요할 때마다 선택자를 평가하므로 패널보다 나중에 요소를 마운트해도 됩니다.
둘 다 없거나 인식할 수 없는 객체 또는 선택자	채팅 전용으로 실행됩니다. 핀, 카메라 이동, 경로가 없으며 콘솔에도 아무것도 기록되지 않습니다.

요소 속성

<kaleidr-map product="chat">은 선언형 사용 방식입니다. 요소 자체가 마운트 대상입니다.

<kaleidr-map product="chat" share-id="YOUR_MAP_ID" contained
             map-target="#store-map"
             style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>

속성	설정되는 옵션	참고
product="chat"	product	필수입니다.
publishable-key	publishableKey
share-id	shareId
map-target	mapTarget	CSS 선택자입니다.
contained	contained	값을 생략하면 true입니다. contained="false"는 false입니다.
lang	lang	BCP 47 태그입니다. 언어를 참조하세요.
chat-title	title	헤더 제목입니다. title은 HTML 툴팁이므로 사용하지 마세요.
placeholder	placeholder	입력창 자리표시자입니다.
theme	theme	JSON 문자열입니다. 마운트 후 값을 변경하면 새 테마가 적용됩니다.
flag	enabled	flag="false"는 마운트를 보류합니다.
api-base	apiBase
base	base
api-key	apiKey	publishable-key의 더 이상 권장되지 않는 별칭입니다.

요소 사용 시 알아둘 사항:

• 실행 중인 지도 객체를 전달할 수 없습니다. map에 대응하는 속성이 없습니다. 사용자 고유의 Mapbox, MapLibre, Google, Leaflet 지도와 연결하려면 Kaleidr.mount를 호출하세요. 요소 방식은 map-target으로 Kaleidr Viewer/Tile을 제어하거나 지도 없이 채팅만 실행합니다.
• 속성은 요소가 연결될 때 한 번만 읽습니다. 나중에 변경해도 적용되는 것은 theme뿐입니다. share-id, publishable-key, map-target, contained, lang, chat-title, placeholder, flag를 이후에 변경해도 아무런 효과가 없으므로 요소를 제거하고 새로 삽입하세요.
• 카메라 속성은 적용되지 않습니다. Chat 마운트에서는 center, zoom, pitch, bearing가 무시되며 이후 변경하면 지원하지 않는다는 경고가 기록됩니다.
• 요소는 기본적으로 display:block입니다. contained를 사용할 때는 위치와 크기를 지정하세요. 예제에서는 Safari 16.4 미만 버전도 지원하기 위해 스타일에 display:block을 명시합니다. 이전 Safari에서는 명시하지 않으면 요소가 인라인으로 남습니다. 테마와 레이아웃을 참조하세요.
• 요소를 제거하면 마운트가 파괴됩니다. 다시 삽입하면 새 패널과 세션이 만들어집니다.

모든 제품의 전체 속성 표는 kaleidr-map 요소를 참조하세요.

제어 핸들

Kaleidr.mount는 모든 제품에서 같은 형태의 핸들을 반환합니다. Chat의 경우:

멤버	Chat 지원 여부	동작
product	'chat'	읽기 전용입니다.
setTheme(theme)	지원	CSS 사용자 지정 속성 객체 또는 그 객체의 JSON 문자열을 받습니다. 기존 값에 새 값을 추가합니다. 키에 -- 접두사가 없으면 자동 추가합니다. 유효하지 않은 JSON 문자열이나 배열은 경고와 함께 무시됩니다.
destroy()	지원	패널, 장소 카드, 핀, 경로선을 제거하고 세션 갱신을 중지합니다. 여러 번 호출해도 안전합니다.
setCamera(camera)	미지원	경고만 기록하고 아무것도 하지 않습니다. 카메라 이동에는 지도 라이브러리의 API를 사용하세요.
setStyle(style)	미지원	경고만 기록하고 아무것도 하지 않습니다.

handle.setTheme({ '--highlight-color': '#0ea5e9' });
handle.destroy();

패널이 로드되기 전에 수행한 호출은 대기열에 저장되었다가 준비되면 실행됩니다. 로드 전에 destroy()를 호출하면 마운트가 취소됩니다.

핸들에는 ready Promise, on() 메서드, map 멤버가 없고 메시지를 보내거나 대화를 읽는 수단도 없습니다. 마운트 시 활성화 제어가 꺼져 있으면 핸들은 작동하지 않는 대체 객체가 됩니다. 모든 메서드가 아무것도 하지 않으며 콘솔 경고에서 마운트를 막는 제어 항목을 알려 줍니다.

지원되지 않는 메서드는 다음 메시지를 기록합니다:

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

네 제품 모두의 매트릭스는 kaleidr-map 요소를 참조하세요.

마운트 후 패널 동작

• “Ask Kaleidr” 또는 지정한 placeholder가 있는 입력 바를 표시합니다. 첫 질문을 보내면 채팅 창으로 확장됩니다.
• 질문마다 지금까지의 대화, 대화 ID, 지도가 연결된 경우 지도 확대 수준, 언어 태그가 함께 전송됩니다. 언어는 지정한 lang, 페이지 언어, en 순으로 결정됩니다. 페이지 외부로 전송되는 정보에 모든 요청이 나열되어 있습니다.
• 답변에 언급된 장소는 결과 카드와 연결된 지도의 핀이 됩니다. 카메라는 한 장소로 이동하거나 여러 장소를 화면에 맞춥니다.
• 하나의 마운트는 한 번에 한 대화만 보여 주며 대화마다 고유한 ID가 있습니다. 창을 닫으면 대화와 핀이 지워지고 다음 질문부터 새 ID로 대화를 시작합니다. 최소화하면 해당 대화가 보존됩니다. 그 상태에서 새 질문을 하면 새 대화를 시작하고, 최소화된 채팅을 다시 열면 이전 ID로 계속할 수 있습니다. 페이지를 새로고침하면 처음부터 다시 시작하며 아무것도 영구 저장되지 않습니다.

세션 교환

게시 가능한 키는 질문 요청에 직접 사용되지 않습니다. 패널이 요청하기 전에 SDK가 키를 수명이 짧은 세션 토큰으로 교환하고 패널에는 이 토큰만 전달합니다.

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"chat"}

{ "session_token": "kld_sess_live_…", "expires_in": 900, "product": "chat", "basemap_style_id": null }

동작	세부 사항
바인딩	세션은 세션을 요청한 출처와 chat 제품에 대해서만 유효합니다.
갱신	SDK는 현재 세션 만료 90초 전에 새 세션을 요청하며 백그라운드 탭이 다시 표시될 때 세션이 만료됐거나 만료가 임박했다면 다시 요청합니다.
갱신 실패	패널이 마운트된 동안 30초마다 다시 시도합니다.
첫 교환 실패	마운트가 실패합니다. 오류 하나가 기록되고 아무것도 표시되지 않으며 다시 시도하지 않습니다. 재시도하려면 다시 마운트하세요.
키 없이 shareId 사용	교환 요청은 POST …/b2b/v1/sdk/share-sessions이며 본문은 {"share_id":"…"}입니다. 세션은 300초간 유효합니다. 갱신이 401, 403 또는 404로 거부되면 페이지를 새로고침할 때까지 SDK가 더 이상 요청하지 않습니다.

인증과 범위에서 키, 세션, 범위를 자세히 설명합니다.

단일 페이지 앱의 수명 주기

• 지도가 포함된 뷰가 제거되면 handle.destroy()를 호출하세요. 패널이 핀을 제거할 수 있도록 지도를 제거하기 전에 패널을 파괴하세요.
• 뷰가 다시 나타나면 재마운트하세요. 새로운 세션 교환과 대화가 시작됩니다.
• destroy()는 패널 스타일시트와 :root 테마 속성을 문서에 남깁니다. destroy()가 제거하고 남기는 항목을 참조하세요.
• 지도 객체를 교체한다면(예: 지도를 다시 생성) 패널을 파괴하고 새 객체로 마운트하세요. 패널은 전달받은 지도 객체를 계속 참조합니다.

프레임워크 통합에서 React, Next.js, Vue의 마운트 및 정리 패턴을 설명합니다.

오류

SDK는 마운트가 실패했을 때 콘솔 오류 하나만 기록하며 서버가 제공한 이유를 그대로 표시하지 않습니다. HTTP 오류라면 브라우저 Network 탭에서 요청의 JSON 응답 본문을 확인하세요. 403 또는 404 코드 값은 detail 필드에 있으며 429 코드는 error 필드, 설명은 detail 필드에 있습니다.

마운트 시

콘솔	네트워크	원인
[kaleidr:chat] mount target not found: <selector>	요청 없음	선택자와 일치하는 요소가 없습니다.
[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …	요청 없음	서버 키를 전달했습니다.
[kaleidr:chat] [kaleidr] failed to load <url>	chat.js 요청 실패	번들이 차단되었거나 CDN에 접속할 수 없습니다.
CORS 오류 후 [kaleidr:chat]이 포함된 오류	POST …/sdk/sessions가 CORS로 차단됨	키가 존재하지 않거나, 취소 또는 만료되었거나, 페이지 출처가 키의 허용 출처 목록에 없습니다. API는 허용된 출처에만 CORS 헤더를 보내므로 브라우저가 상태와 본문을 숨깁니다.
[kaleidr:chat] kaleidr session exchange failed (403)	403 insufficient_scope	키에 ai 범위가 없습니다.
동일	403 product_not_allowed	키가 chat을 포함하지 않는 제품으로 제한되어 있습니다.
동일	403 tier_capability_not_allowed	조직의 현재 요금제가 이 기능을 허용하지 않습니다.
[kaleidr:chat] kaleidr session exchange failed (429)	429 rate_limited	이 키로 1분에 30건을 초과하는 세션 요청을 보냈습니다.
[kaleidr:chat] kaleidr session exchange failed (404)	404 sessions_disabled	플랫폼에서 세션 교환이 비활성화되었습니다. 키 문제는 아닙니다.
[kaleidr:chat] kaleidr session exchange failed (503)	503 sessions_not_configured	플랫폼 장애입니다. 새로고침 후 다시 시도하세요.
키 없이 shareId로 마운트할 때 [kaleidr:chat] kaleidr session exchange failed (403) 또는 (404)	403 chat_disabled, 403 origin_not_allowed 또는 404 not_found	게시 지도가 채팅을 거부했습니다. 게시된 지도의 Kaleidr AI를 참조하세요.
[kaleidr] embed is disabled — …(경고)	요청 없음	활성화 제어가 꺼져 있습니다. 메시지에서 제어 항목을 확인할 수 있습니다.
[kaleidr] theme string must be JSON …(경고)	해당 없음	theme이 JSON이 아닌 문자열이었습니다. 패널은 테마 없이 마운트됩니다.

패널 사용 중

패널은 대화에 한 줄을 추가하여 방문자에게 실패를 보여 줍니다. 사용자 코드에는 알림이 전달되지 않습니다.

방문자에게 보이는 내용	상태	원인
"Sorry — that didn't go through. Please try again."	401	세션이 더 이상 유효하지 않습니다. 키가 취소 또는 만료되었거나 허용 출처에서 현재 출처가 제거되었거나 마운트 시 인증 정보를 제공하지 않았습니다.
동일	5xx 또는 네트워크 장애	일시적인 장애입니다.
"You've reached your usage limit for now." 및 확인된 경우 초기화 시각	429 quota_exceeded	조직의 AI 크레딧을 소진했거나 키의 월간 한도에 도달했습니다.
동일	429 rate_limited	키의 요청 속도 제한입니다. 해당 페이지의 모든 방문자가 하나의 키를 공유합니다.
동일	429 visitor_limit_reached	키 없는 Chat에만 적용: 이 방문자의 분당 또는 일일 한도를 초과했습니다.

오류에 전체 목록이 있고 할당량 및 속도 제한에 한도에 관한 설명이 있습니다.

관련 페이지

• 기능과 제한
• 지원 지도
• 테마와 레이아웃
• kaleidr.js 및 kaleidr-map 요소