채팅

Kaleidr Chat은 지도를 이미 표시하는 페이지에 추가하는 채팅 패널입니다. 방문자가 “테이트 모던 근처에서 아침 식사를 할 수 있는 곳은 어디인가요?”라고 질문하면 답변이 패널에 순차적으로 표시되고, 답변에 등장하는 장소가 사용자의 지도에 핀으로 나타납니다. 카메라도 해당 장소를 보여주도록 움직입니다.

패널은 iframe이 아닌 사용자의 페이지에서 실행됩니다. 스크립트 하나를 로드하고 공개 가능 키와 현재 실행 중인 지도 객체를 사용해 Kaleidr.mount를 호출하면 패널이 지도에 연결됩니다. 기존 지도 라이브러리, 스타일, 레이어 및 컨트롤은 그대로 유지됩니다.

방문자 경험

지도 왼쪽 위에 Ask Kaleidr라고 적힌 입력 표시줄이 나타납니다.
방문자가 질문을 보내면 입력 표시줄이 채팅 창으로 확장되고 답변이 텍스트로 점차 표시됩니다.
답변에 언급된 각 장소는 채팅 결과 카드와 지도 핀이 됩니다. 장소가 하나이면 카메라가 그곳으로 이동하고, 여러 곳이면 모두 보이도록 화면을 맞춥니다.
핀이나 결과를 클릭하면 간단한 소개, 사진, 길찾기, 해당 장소에 대한 추가 질문 입력란이 있는 장소 카드가 열립니다.
길찾기를 요청하면 지도에 경로선이 그려지고 경로에 맞게 화면이 조정됩니다.
이전 질문의 핀은 지원되는 모든 지도와 Kaleidr Viewer 또는 Tile 요소에서 대화가 끝날 때까지 남아 있습니다. 채팅 창을 닫으면 대화가 종료되고 핀과 경로가 제거됩니다.

뷰포트 너비가 768 px 이하일 때는 패널이 떠 있는 창 대신 하단 시트 형태로 표시됩니다.

지도에 적용되는 동작

수행하는 동작	수행하지 않는 동작
자체 핀 추가 및 제거	사용자의 레이어, 소스 또는 마커 읽기, 변경, 제거
장소로 카메라 이동 또는 여러 장소가 보이도록 화면 조정	레이어, 마커 또는 현재 표시 영역을 Kaleidr에 전송
경로선을 그리고 다시 제거	이벤트가 발생할 때 사용자 코드의 콜백 호출
현재 확대/축소 수준을 읽어 각 질문과 함께 전송합니다. Mapbox GL JS 및 MapLibre GL JS에서는 핀의 위치와 레이블을 표시하기 위해 페이지 내부에서만 카메라와 스타일의 레이블 글꼴도 읽습니다	지도 컨트롤이나 제스처를 대신 조작

지도 라이브러리마다 카메라 및 그리기 기능이 다르므로 정확한 동작은 조금씩 달라집니다. 지원 지도에서 비교표를, 기능 및 제한에서 패널이 보내는 모든 요청과 데이터를 확인할 수 있습니다.

요구 사항

요구 사항	값
요금제	Free 이상. 질문은 조직의 AI 크레딧을 사용합니다.
키	kaleidr.com/api-keys에서 발급한 공개 가능 키 `kld_pk_live_…`.
범위	`ai`. 모든 새 키에 기본 포함됩니다.
허용 출처	키에 허용 출처가 지정되어 있으면 페이지의 출처가 목록에 있어야 합니다.
지도 라이브러리	Mapbox GL JS, MapLibre GL JS, Google Maps JavaScript API 또는 Leaflet을 마운트 전에 페이지 전역 변수로 로드해야 합니다.
페이지	HTTP 또는 HTTPS로 제공해야 합니다. 디스크에서 직접 연 파일에는 사용할 수 있는 출처가 없습니다.
콘텐츠 보안 정책	사이트에서 설정한 경우 콘텐츠 보안 정책에 명시된 호스트를 허용해야 합니다.

API 키 발급에서 키를 만들고 허용 출처를 설정하는 방법을 안내합니다.

세 가지 실행 방법

보유한 항목	전달할 값	결과
직접 사용하는 Mapbox, MapLibre, Google 또는 Leaflet 지도	`publishableKey` 및 `map`	패널이 사용자의 지도를 제어합니다. 일반적인 방식입니다.
Kaleidr Studio에서 게시한 지도	없음: Kaleidr AI 타일에서 Control Tower를 켠 지도를 삽입	지도에 패널이 포함되며 지도 소유자가 질문 비용을 부담합니다. 게시된 지도의 Kaleidr AI를 참조하세요.
지도 없음	`publishableKey`만 전달	채팅 전용 패널로 답변과 장소 카드는 있지만 핀이나 카메라 이동은 없습니다.

가장 간단한 실행 페이지

이 페이지는 MapLibre 지도 안에 채팅 패널을 배치합니다. 키를 바꾸고 파일을 저장한 뒤 http://localhost:8080처럼 키가 허용하는 출처에서 제공하세요.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on MapLibre</title>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.css" />
  </head>
  <body>
    <div id="mapHost" style="position:relative; height:520px">
      <div id="map" style="position:absolute; inset:0; z-index:0"></div>
      <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
    </div>

    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-0.12, 51.5],
        zoom: 11,
      });

      Kaleidr.mount('#chat', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,
        contained: true,
      });
    </script>
  </body>
</html>

contained: true는 패널을 #chat 내부에 배치합니다. 이 설정이 없으면 지도가 페이지 어디에 있든 브라우저 뷰포트 왼쪽 위에 고정된 창으로 표시됩니다. 테마 및 레이아웃에 두 가지 구성이 설명되어 있습니다.

지원하지 않는 기능

패널을 기반으로 개발하기 전에 다음 제한을 팀에 알려주세요.

콜백이나 이벤트가 없습니다. 방문자가 질문하거나 답변이 도착하거나 핀을 클릭해도 코드에 알림이 전달되지 않습니다.
사용자 지정 컨텍스트를 전달할 수 없습니다. 패널을 통해 시스템 지시, 페르소나, 매장 목록 또는 지도 레이어의 내용을 어시스턴트에 제공할 수 없습니다. 조직에서 업로드한 데이터로 답변하는 기능은 요금제에 따라 제한되는 별도 기능입니다. 사용자 데이터를 참고하세요.
네이티브 모바일 SDK가 없습니다. 패널은 웹페이지용입니다.

답변 언어, 패널 헤더 제목, 입력란 자리표시자는 lang, title, placeholder 옵션으로 설정할 수 있습니다. lang을 지정하지 않으면 페이지의 <html lang>을 사용합니다. Chat 레퍼런스를 참조하세요.

전체 목록은 기능 및 제한에 있습니다. 대화와 인터페이스를 완전히 제어하려면 대신 백엔드에서 HTTP API를 호출하세요. 서버 빠른 시작을 참조하세요.

다음 단계

구현: Mapbox · MapLibre · Google Maps · Leaflet
이해: 기능 및 제한 · 지원 지도
페이지에 적용: 테마 및 레이아웃
참조: Chat 레퍼런스
출시: 운영 환경 체크리스트 · 문제 해결

방문자 경험​

지도에 적용되는 동작​

요구 사항​

세 가지 실행 방법​

가장 간단한 실행 페이지​

지원하지 않는 기능​

다음 단계​