빠른 시작

이 페이지에서는 대부분의 팀에 필요한 순서대로 가장 간단한 세 가지 작동 예제를 소개합니다.

1. 이미 사용 중인 지도에 Chat 추가. 장소에 대한 질문에 답하고 자체 지도에 핀, 카메라 이동, 경로를 표시하는 채팅 패널입니다.
2. 게시된 지도. Kaleidr Studio에서 만든 지도를 내 페이지에 삽입합니다.
3. 기본 지도. Kaleidr가 디자인한 기본 지도를 완성된 지도로 페이지에 보여 줍니다.

각 방식에는 HTML 파일 하나만 필요합니다. 모두 Free 요금제에서 작동합니다.

방식	제품	필요한 키	표시 위치
자체 지도의 Chat	chat	공개 가능 키	내 페이지의 지도 위
게시된 지도	viewer	없음	Kaleidr iframe 내부
기본 지도	tile	공개 가능 키	Kaleidr iframe 내부

먼저 전체 모델을 이해하려면 Kaleidr 작동 원리를, 어떤 제품이 필요한지 모르겠다면 경로 선택을 읽으세요.

시작하기 전에

• Kaleidr 계정. kaleidr.com에서 가입하세요. 이 페이지의 모든 예제는 Free로 충분합니다.

• Chat과 기본 지도에 사용할 공개 가능 키. kaleidr.com/api-keys에서 만드세요. 접두사는 kld_pk_live_입니다. API 키 받기에 절차가 있습니다. 게시된 지도에는 키가 필요 없습니다.

• 페이지를 제공할 웹 서버. 로컬 개발 중에도 HTTP로 파일을 제공하세요. 파일이 있는 폴더에서 다음 방법 중 하나를 실행할 수 있습니다.

  python -m http.server 8000
  # or
  npx serve -l 8000

  그런 다음 http://localhost:8000/your-file.html을 엽니다. 디스크에서 직접 열지 마세요. file:// 페이지에는 키의 허용 출처로 등록할 수 있는 출처가 없습니다.

• 키에 허용 출처가 있다면 페이지 출처를 등록. 목록이 비어 있는 키는 모든 사이트에서 작동하지만, 목록이 있으면 등록된 사이트만 허용합니다. 테스트 중에는 http://localhost:8000을 추가하세요.

• 사이트에 콘텐츠 보안 정책이 있다면 Kaleidr 로드를 허용. Content-Security-Policy 헤더가 없는 페이지는 설정이 필요하지 않습니다. 있다면 콘텐츠 보안 정책을 참고하세요.

세 가지 방식은 모두 동일한 스크립트 태그로 시작합니다. 개발자가 직접 로드할 파일은 하나뿐이며, 제품을 마운트할 때 제품 코드가 자동으로 로드됩니다.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

자체 지도에 Chat 추가

MapLibre GL JS 지도와 그 안에 고정된 채팅 패널을 만들 것입니다. “Where can I get ramen near Bryant Park?”라고 질문하면 답변이 스트리밍되고 각 장소에 핀이 나타나며 카메라가 움직입니다.

예제에는 MapLibre GL JS를 사용하지만 Chat은 Mapbox GL JS, Google Maps JavaScript API, Leaflet에도 연결할 수 있습니다. 지원 지도를 참고하세요.

1. 페이지 만들기

파일을 chat.html로 저장하고 kld_pk_live_…를 공개 가능 키로 바꾸세요.

<!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" />
    <style>
      body { margin: 0; }
      /* The chat panel docks inside this box, so it must be positioned and sized. */
      #stage { position: relative; height: 100vh; }
      #map { position: absolute; inset: 0; }
    </style>
  </head>
  <body>
    <div id="stage">
      <div id="map"></div>
    </div>

    <!-- 1. Your map library, loaded as a page global (window.maplibregl). -->
    <script src="https://unpkg.com/maplibre-gl@5.17.0/dist/maplibre-gl.js"></script>
    <!-- 2. The Kaleidr loader. -->
    <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', // replace with your own style
        center: [-73.9857, 40.7484], // [longitude, latitude]
        zoom: 11,
      });

      const chat = Kaleidr.mount('#stage', {
        product: 'chat',
        publishableKey: 'kld_pk_live_…',
        map,             // the live map instance, not a selector
        contained: true, // dock the panel inside #stage
      });

      // When you remove the map (for example on a route change in a single-page app):
      // chat.destroy();
    </script>
  </body>
</html>

이 파일에서 중요한 점은 세 가지입니다.

• 지도 라이브러리가 페이지 전역 객체여야 합니다. Chat 코드는 window.maplibregl에서 MapLibre를 찾습니다. 스크립트 태그로 로드하면 전역이 자동으로 설정됩니다. npm에서 import했다면 마운트 전에 window.maplibregl = maplibregl을 직접 설정하세요.
• map은 지도 객체입니다. CSS 선택자가 아니라 생성한 지도 인스턴스를 전달하세요.
• contained: true에는 위치와 높이가 있는 영역이 필요합니다. 패널은 마운트 대상 안에 표시됩니다. contained가 없으면 지도 위치와 관계없이 브라우저 창의 왼쪽 위에 고정됩니다.

데모 스타일은 세부 정보가 적은 세계 지도입니다. 핀은 올바른 좌표에 표시되지만 도로를 보려면 자체 스타일을 사용하세요.

2. 제공하고 질문하기

파일 폴더에서 로컬 서버를 시작하고 http://localhost:8000/chat.html을 엽니다.

확인할 결과:

• 지도가 창을 가득 채우고 왼쪽 위에 텍스트 입력이 있는 채팅 패널이 나타납니다.
• 브라우저 Network 탭에서 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions에 대한 요청이 200을 반환합니다. SDK가 키를 단기 세션으로 교환했다는 뜻입니다.
• Where can I get ramen near Bryant Park?와 같은 장소 질문을 입력하면 답변이 텍스트로 스트리밍되고 장소마다 핀이 추가되며 카메라가 핀들을 포함하도록 움직입니다. Network 탭의 …/b2b/v1/chat/control/stream 요청은 답변 스트리밍 동안 열린 상태입니다.
• 콘솔에 [kaleidr를 포함하는 오류가 없습니다.

3. 작동하지 않을 때

증상	원인	해결 방법
패널이 없고 콘솔에서 …/sdk/sessions에 대한 CORS 오류와 [kaleidr:chat] 오류가 발생	키가 틀렸거나 폐기됐거나 페이지 출처가 키의 허용 출처 목록에 없음. API가 CORS 헤더 없이 응답하여 브라우저가 CORS 오류로 표시함	키 값을 확인하세요. kaleidr.com/api-keys에서 포트까지 포함한 정확한 출처를 추가하거나 테스트 중 목록을 비웁니다.
패널이 지도 안이 아닌 브라우저 창 왼쪽 위에 표시	contained: true가 없거나 마운트 대상의 위치가 지정되지 않음	contained: true를 전달하고 대상에 position: relative와 높이를 지정합니다.
패널은 답변하지만 핀이 나타나지 않음	지도 라이브러리가 페이지 전역에 없으므로 Chat이 핀을 만들 수 없음	스크립트 태그로 라이브러리를 로드하거나 Kaleidr.mount 전에 window.maplibregl을 설정합니다.

문제 해결에는 각 증상과 정확한 콘솔 메시지가 정리되어 있습니다.

이 방식의 다음 단계는 MapLibre에 Chat 연결의 자세한 안내와 패널 동작을 설명한 기능 및 제한입니다.

게시된 지도

Kaleidr Studio에서 만든 지도를 자신의 페이지에 표시합니다. API 키는 필요 없으며 게시된 지도의 공개 ID로 삽입할 수 있습니다.

1. 지도 게시 및 ID 복사

1. Kaleidr Studio에서 지도를 열고 Publish를 선택합니다.
2. Publish & embed 페이지에서 Go Live를 선택합니다.
3. Embed code의 코드를 복사합니다. URL 끝부분이 ID입니다. https://map-embed.kaleidr.com/embed/abc123에서 ID는 abc123입니다.

확인할 결과: 프로젝트 상태가 live로 표시되고 임베드 코드 아래 실시간 미리보기에 방문자에게 보일 지도가 나타납니다.

2. 페이지 만들기

map.html로 저장하고 YOUR_SHARE_ID를 복사한 ID로 바꿉니다.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A published Kaleidr map</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="viewer"
      share-id="YOUR_SHARE_ID"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

요소에 높이가 필요합니다. 지정하지 않으면 지도는 기본적으로 높이 500픽셀이 됩니다. <kaleidr-map> 요소는 기본적으로 display:block이므로 높이 지정이 적용됩니다. 예제에서도 display:block을 적습니다. 이는 일반 브라우저에서 문제없으며, 요소가 인라인으로 남아 높이를 무시하는 Safari 16.4 이전 버전을 지원하기 위한 것입니다.

사이트 빌더나 CMS 입력 필드처럼 페이지에 스크립트를 추가할 수 없다면 Studio의 iFrame 탭에서 제공하는 일반 iframe을 사용하세요. 로더가 필요 없습니다.

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_SHARE_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

3. 페이지 제공

http://localhost:8000/map.html을 엽니다.

확인할 결과:

• 지도 높이는 480픽셀이고 페이지 폭에 맞으며 Studio에서 저장한 시점으로 시작합니다.
• 포인터가 지도 위에 있을 때 스크롤하면 지도가 확대/축소됩니다. 포인터가 지도 옆에 있으면 스크롤은 페이지를 이동합니다.
• Elements 패널의 <kaleidr-map> 내부에 <iframe>이 있으며 주소가 https://map-embed.kaleidr.com/embed/로 시작합니다.

프레임에 **"This map isn't available — it may have been unpublished, paused, or the link is incorrect."**가 보이면 ID가 잘못되었거나 지도가 게시되지 않은 상태입니다. **"This map isn't allowed to render on this site. Please contact the map owner."**가 보이면 지도 표시가 다른 도메인으로 제한된 것입니다.

다음 단계는 지도의 표시 도메인을 제한하는 지도 삽입과, 키 없이 방문자가 질문하도록 만드는 게시된 지도에서 Chat입니다.

기본 지도

Kaleidr에서 디자인한 기본 지도를 페이지에 표시합니다. 지도 라이브러리를 설치하거나 스타일을 작성할 필요 없이 완성된 인터랙티브 지도를 사용할 수 있습니다.

1. 페이지 만들기

basemap.html로 저장하고 kld_pk_live_…를 자신의 공개 가능 키로 교체합니다.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A Kaleidr basemap</title>
  </head>
  <body>
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <kaleidr-map
      product="tile"
      publishable-key="kld_pk_live_…"
      style-id="kaleidr-morning"
      center="-73.9857,40.7484"
      zoom="11"
      style="display:block; height:480px"
    ></kaleidr-map>
  </body>
</html>

• style-id는 기본 지도 스타일을 지정하므로 항상 설정하세요. kaleidr-morning은 일반적으로 쓰는 스타일 중 하나입니다. 다른 스타일은 Tile을 참고하세요.
• center는 longitude,latitude 순서입니다. zoom을 설정할 때는 center도 지정해야 합니다. center 없이 지정한 zoom은 무시됩니다.

2. 페이지 제공

http://localhost:8000/basemap.html을 엽니다.

확인할 결과:

• 맨해튼 미드타운을 중심으로 한 높이 480픽셀의 기본 지도.
• Network 탭에 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 요청이 200을 반환하고 이어 https://map-embed.kaleidr.com에서 iframe이 로드됩니다.
• 포인터가 지도 위에 있을 때 스크롤하면 지도가 확대/축소됩니다.

아무것도 렌더링되지 않고 콘솔에 …/sdk/sessions에 대한 CORS 오류가 나온다면 Chat 예제와 마찬가지로 키가 잘못됐거나 출처가 허용 목록에 없는 것입니다.

Tile 세션마다 조직의 월간 지도 로드 허용량에서 1회가 차감됩니다. 할당량 및 속도 제한을 참고하세요.

다음은 실행 중 스타일 변경과 카메라 조작을 설명하는 Tile 사용입니다.

로드한 구성 요소

세 방식은 모두 다음 두 가지를 사용합니다.

• **Kaleidr.mount(target, options)**는 JavaScript에서 제품을 마운트하고 핸들을 즉시 반환합니다. 제품 코드가 백그라운드에서 로드되며, 준비되기 전에 호출한 핸들 작업은 보관되었다가 준비 후 적용됩니다.
• **<kaleidr-map>**은 HTML에서 같은 작업을 합니다. 속성은 마운트 옵션의 이름을 하이픈으로 바꾼 것(share-id, style-id, publishable-key)입니다. 예외는 enabled 옵션이 flag 속성이 되고 Chat의 title 옵션이 chat-title 속성이 된다는 점입니다.

자체 지도에 Chat을 연결할 때는 실제 지도 객체가 필요하므로 Kaleidr.mount를 사용하세요. 다른 제품은 어느 방식이든 가능합니다.

모든 제품의 핸들에는 destroy() 메서드가 있습니다. 나머지는 제품에 따라 다릅니다. setCamera는 viewer, tile, editor에서 동작하지만 chat에서는 지원되지 않습니다. Chat은 답변할 때 연결된 지도를 직접 움직이며, 개발자가 지도를 이동할 때는 자신의 지도 라이브러리 카메라 API를 사용합니다. 전체 표는 <kaleidr-map> 요소를 참고하세요.

지금 알아둘 제한

• Chat은 자체 핀, 경로, 카메라 이동을 추가합니다. 기존 레이어나 마커를 변경하거나 Kaleidr로 전송하지 않으며 페이지에 이벤트를 보내지도 않습니다. 기능 및 제한을 참고하세요.
• Viewer와 Tile은 iframe에서 실행됩니다. 자체 레이어나 마커를 추가할 수 없습니다. 이것들이 필요하다면 기존 지도를 유지하고 Chat을 연결하세요.
• Kaleidr 기본 지도는 Tile로 표시합니다. Kaleidr 스타일이나 타일을 기존 지도 라이브러리에 직접 로드하는 방식은 지원되지 않습니다.
• SDK는 웹페이지용입니다. npm 패키지와 네이티브 모바일 SDK는 없습니다. 백엔드는 서버 API를 호출합니다.
• 키가 필요한 마운트는 사용량을 소비합니다. Chat 답변은 조직의 AI 크레딧을, Tile 세션은 지도 로드 수를 소비합니다. Kaleidr 작동 원리를 참고하세요.

다음에 선택할 경로

원하는 작업	읽을 문서
Mapbox GL JS에 Chat 연결	Mapbox에 Chat 연결
MapLibre GL JS에 Chat 연결	MapLibre에 Chat 연결
Google Maps에 Chat 연결	Google Maps에 Chat 연결
Leaflet에 Chat 연결	Leaflet에 Chat 연결
패널 위치 및 브랜드 색상 조정	테마 및 레이아웃
게시된 지도에서 방문자에게 Chat 제공	게시된 지도에서 Chat
게시 지도 삽입 및 도메인 제한	지도 삽입
기본 지도 표시 및 스타일 전환	Tile 사용
웹페이지에 지도 편집기 추가	Editor 연결
React, Next.js 또는 Vue에서 SDK 사용	프레임워크
백엔드에서 Kaleidr 호출	서버 빠른 시작
AI 답변에 자체 비즈니스 데이터 사용	내 데이터
운영 환경 배포	운영 체크리스트