Google 지도에 Kaleidr Chat 연결하기

이 가이드를 완료하면 Google 지도 안에 채팅 패널이 고정된 웹페이지를 만들 수 있습니다. 방문자가 질문하면 답변이 패널에 실시간 표시되고 답변 속 장소가 Google 지도에 핀으로 나타나며, 카메라도 해당 장소를 보여주도록 이동합니다. 게시용 키가 있으면 Free를 포함한 모든 요금제에서 이용할 수 있습니다. 질문에는 조직의 AI 크레딧이 사용됩니다.

Google Maps 키와 Kaleidr 키는 서로 다릅니다. 지도 사용료는 Google이, 질문 사용료는 Kaleidr가 청구합니다. Kaleidr는 Google 키를 받지 않습니다.

시작하기 전에

kaleidr.com/api-keys에서 발급받은 Kaleidr 게시용 키 (kld_pk_live_…). 새 키에는 Chat에 필요한 ai 범위가 포함됩니다. API 키 발급을 참조하세요.
키에 허용된 출처가 설정되어 있다면 페이지 출처를 목록에 추가합니다. 로컬 개발 시 http://localhost:8080처럼 서버가 사용하는 출처를 추가합니다.
Google Cloud 프로젝트의 Google Maps JavaScript API 키. Maps JavaScript API가 사용 설정되어 있고 해당 출처가 키의 리퍼러 제한에서 허용되어야 합니다.
npx serve 또는 python -m http.server 8080처럼 HTTP로 페이지를 제공할 방법. 로컬 파일을 직접 열면 동작하지 않습니다.
사이트에서 콘텐츠 보안 정책을 사용한다면 Google Maps에 필요한 호스트와 함께 콘텐츠 보안 정책의 호스트를 허용합니다.

Google Maps JavaScript API는 항상 전역 google.maps를 정의하므로 채팅 번들에 라이브러리를 별도로 노출할 필요가 없습니다.

1단계: 지도와 채팅 레이어 배치하기

지도와 채팅 마운트 대상을 하나의 위치 지정 컨테이너 안에 배치하세요. 채팅 레이어는 지도 위에 겹치지만 포인터 이벤트는 통과시킵니다.

<div id="mapHost" style="position:relative; height:520px">
  <div id="map" style="position:relative; height:100%; z-index:0"></div>
  <div id="chat" style="position:absolute; inset:0; z-index:1; pointer-events:none"></div>
</div>

지도 요소는 height:100%로 래퍼를 채웁니다. position:relative와 z-index:0을 함께 적용하면 Google의 레이어가 지도 요소 안에서 채팅 레이어 아래에 유지됩니다.

예상 화면: 아직 아무것도 보이지 않으며 높이 520 px의 빈 영역만 있습니다.

3단계: `kaleidr.js` 로드하기

지도 콜백이 실행될 때 Kaleidr가 존재하도록 일반 script 태그로 Kaleidr 로더를 먼저 불러오세요.

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

예상 결과: 화면은 변하지 않습니다. 콘솔에서 Kaleidr.version을 확인하면 버전 문자열이 반환됩니다.

3단계: 지도를 생성하고 패널을 장착하는 콜백 정의

Google Maps 스크립트는 로드가 끝나면 지정한 이름의 함수를 호출합니다. 호출되기 전에는 google.maps가 존재하지 않으므로 그 함수 내부에서 지도를 만들고 패널을 장착하세요.

<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 51.5, lng: -0.12 },
      zoom: 11,
    });

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

예상 화면: 아직 변화가 없습니다. 함수는 정의됐지만 호출되지 않았습니다.

4단계: 콜백 아래에서 Google Maps 스크립트 불러오기

Google 스크립트 태그를 initMap을 정의한 스크립트 아래에 배치하세요.

<script async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>

순서가 중요합니다. Google 스크립트에는 async가 있어 다운로드가 끝나자마자 실행되며 즉시 initMap을 호출합니다. 태그가 앞에 있으면 브라우저가 initMap 정의를 읽기 전에 실행이 끝날 수 있고, 이때 Google은 initMap이 함수가 아니라고 보고합니다. 콜백을 먼저 정의하면 이러한 경쟁 상태를 막을 수 있습니다.

예상 화면: 런던 중심부의 Google 지도와 왼쪽 상단의 Ask Kaleidr 입력창이 표시됩니다.

전체 페이지

파일을 index.html로 저장하고 두 키를 교체한 뒤 HTTP로 폴더를 제공하세요.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Kaleidr Chat on Google Maps</title>
    <style>
      body { margin: 0; font-family: system-ui, sans-serif; }
      #mapHost { position: relative; height: 100vh; }
      #map { position: relative; height: 100%; z-index: 0; }
      #chat { position: absolute; inset: 0; z-index: 1; pointer-events: none; }
    </style>
  </head>
  <body>
    <div id="mapHost">
      <div id="map"></div>
      <div id="chat"></div>
    </div>

    <!-- 1. The Kaleidr loader. -->
    <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

    <!-- 2. The callback, defined before the Google script can call it. -->
    <script>
      function initMap() {
        const map = new google.maps.Map(document.getElementById('map'), {
          center: { lat: 51.5, lng: -0.12 },
          zoom: 11,
        });

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

    <!-- 3. The Google Maps script, last. -->
    <script async
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap&loading=async&v=weekly"></script>
  </body>
</html>

동작 방식

방문자	채팅 패널	Google 지도
질문 전송	창이 펼쳐지고 답변 텍스트가 실시간 표시됨	아직 변화 없음
대기	답변에 있는 장소마다 결과 카드 표시	위치가 확인되는 대로 핀이 표시됩니다. 장소가 하나면 그곳으로 이동해 확대 수준을 바꾸고, 여러 곳이면 56 px 여백을 두고 모두 맞춥니다.
핀 또는 결과 클릭	개요, 사진, 길찾기 도구가 있는 장소 카드 표시	결과 클릭 시 해당 장소로 지도 이동
길찾기 요청	거리와 소요 시간 표시	경로선을 그리고 화면에 맞춤
추가 질문	같은 대화에 메시지 추가	새로운 핀이 추가되고 기존 핀은 유지
채팅 닫기	입력창으로 돌아가며 대화 종료	핀과 경로 제거

Google Maps에만 해당하는 사항:

핀은 사용자 지정 오버레이를 통해 그리는 HTML 요소입니다. Map ID가 필요하지 않습니다. 페이지에서 Google의 marker 라이브러리를 불러오면 채팅 번들은 고급 마커를 대신 사용하며, 이때 Google은 지도에 mapId가 있어야 한다고 요구합니다.
한 장소로 이동할 때는 지도 이동 후 확대 수준을 변경합니다. 하나의 비행 애니메이션이 아닙니다.
여러 장소를 맞출 때 모든 변에 56 px 여백을 적용합니다. 채팅 패널의 공간을 고려하지 않아 장소가 패널 아래에 숨을 수 있습니다. 방문자가 지도를 이동하거나 패널을 최소화할 수 있습니다.
경로는 두 폴리라인으로 표시합니다. 흰색 테두리 선 위에 색상 선이 있습니다.
지도는 평면의 북쪽 고정 보기로 취급합니다. 어시스턴트는 방향이나 기울기를 설정하지 않습니다.
패널이 장착된 동안 세션이 백그라운드에서 갱신되므로 토큰을 직접 관리할 필요가 없습니다.

작동 확인하기

페이지에서

Ask Kaleidr 입력 막대가 지도 왼쪽 위에 표시됩니다.
Show me three museums in London을 입력하고 Enter를 누르세요. 답변이 순차적으로 표시되고 핀 3개가 생기며 지도가 모든 핀을 보여줍니다.

콘솔에서

[kaleidr가 포함된 오류 또는 경고가 없고 Google Maps API 오류도 없어야 합니다.

Network 탭에서

요청	예상 결과
`GET https://cdn.kaleidr.com/embed/v1/kaleidr.js`	200
`GET https://cdn.kaleidr.com/embed/v1/chat.js`	200
`POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions`	200, 아래 예시와 유사한 JSON 본문
`POST https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream`(질문 후)	200, `content-type: text/event-stream`

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

작동하지 않는 경우

SDK는 간단한 메시지만 기록하며 서버가 반환한 사유는 반복하지 않습니다. 요청이 실패하면 Network에서 해당 요청을 열어 JSON 응답을 확인하세요. 403 또는 404의 코드는 detail에, 429의 코드는 error에 기록되며 detail에는 설명 문장이 포함됩니다.

증상	원인	해결 방법
지도가 보이지 않고 Google 콘솔에 `initMap is not a function` 오류	`initMap` 정의 전에 Google 스크립트가 실행됨	4단계처럼 Google 스크립트를 콜백 아래로 이동
지도 없음 또는 Google 오류 대화 상자가 있는 회색 지도	Google 키에서 Maps JavaScript API가 활성화되지 않았거나 결제가 설정되지 않았거나 출처가 허용되지 않음	Kaleidr와 무관한 문제이므로 Google Cloud 프로젝트에서 수정
`initMap` 안에서 `Kaleidr is not defined`	`kaleidr.js`에 `async` 또는 `defer`가 있거나 Google 스크립트 뒤에서 로드함	일반 script 태그로 `kaleidr.js`를 먼저 로드
지도만 보이고 패널이 없으며 `…/sdk/sessions` CORS 오류 뒤 `[kaleidr:chat]` 오류	Kaleidr 키가 알려지지 않았거나 폐기됐거나 페이지 출처가 허용 목록에 없음. API는 허용된 출처에만 CORS 헤더를 반환하므로 브라우저가 응답을 숨김	키를 확인하고 kaleidr.com/api-keys에 스킴과 포트를 포함한 정확한 출처 추가
패널 없음, `[kaleidr:chat] kaleidr session exchange failed (403)`	키 자체는 유효하지만 Chat 권한이 없을 수 있음. `detail`은 `insufficient_scope`(`ai` 없음), `product_not_allowed`(다른 제품으로 제한), `tier_capability_not_allowed` 중 하나	`ai` 범위와 `chat` 제품 권한을 가진 키 사용
패널 없음, `[kaleidr:chat] Kaleidr: a server key (kld_sk_…) must never be used in the browser …`	서버 키를 전달해 요청이 전송되지 않음	게시용 키 (`kld_pk_live_…`) 사용, 서버 키가 배포됐다면 폐기
패널 없음, `[kaleidr:chat] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/chat.js`	콘텐츠 보안 정책이나 광고 차단으로 번들 로드 실패	`script-src`에 `https://cdn.kaleidr.com` 허용
패널이 지도 위가 아닌 브라우저 창 좌상단에 표시됨	`contained`가 없거나 `#chat` 위치 스타일이 없음	`contained: true`와 1단계 스타일 적용
패널이 지도 뒤에 가려짐	지도 요소에 독립적인 스태킹 컨텍스트가 없음	`#map`에 `z-index:0`, `#chat`에 `z-index:1` 유지
패널은 답하지만 핀과 지도 이동이 없음	`map`으로 전달한 값이 `google.maps.Map` 인스턴스가 아니라 DOM 요소 또는 래퍼 컴포넌트임	`new google.maps.Map(…)`가 반환한 객체 전달. 지원 지도 참조
답변과 지도 이동은 되지만 핀이 없음	`marker` 라이브러리를 로드했지만 `mapId`가 없음	지도 옵션에 `mapId`를 추가하거나 `marker`를 로드하지 않음
모든 질문에서 "죄송합니다. 다시 시도해 주세요." 표시	키가 폐기됐거나 허용 출처가 바뀌어 세션이 무효화됨	키 확인 후 페이지 새로고침
"현재 사용 한도에 도달했습니다." 표시	429: 조직 AI 크레딧 소진 또는 키의 요청 빈도 제한. 페이지 방문자가 키의 한도를 공유함	할당량 및 요청 제한 참조

추가 증상은 문제 해결 페이지를 참고하세요.

제한 사항

페이지에서는 패널의 콜백이나 이벤트를 받을 수 없습니다. 질문·답변·핀 클릭에 코드로 반응할 수 없습니다.
어시스턴트는 사용자가 추가한 오버레이·마커나 현재 지도에 보이는 영역을 알지 못합니다. 질문과 함께 전달되는 지도 정보는 확대 수준뿐입니다.
패널을 통해 어시스턴트에게 별도 지시나 자체 데이터를 제공할 수 없습니다.
답변 언어, 패널 제목, 입력창 안내 문구는 장착 옵션 lang, title, placeholder로 설정합니다. Chat 참고 문서를 참조하세요. 패널의 나머지 문구는 영어입니다.
Google Maps에서 여러 장소를 맞출 때 채팅 패널을 피하지 않습니다.
Chat 장착에서 handle.setCamera()는 작동하지 않고 경고만 기록합니다. Google API로 지도를 이동하세요.
SPA에서 지도 화면이 제거될 때 handle.destroy()를 호출하고 돌아왔을 때 다시 장착하세요.

전체 목록은 기능과 제한에 있습니다.

다음 단계

테마 및 레이아웃: 사이트에 맞게 패널 스타일 지정
지원 지도: Google Maps에서 가능한 어시스턴트 기능
Chat 참고 문서: 모든 옵션, 핸들, 오류
배포 체크리스트: 출시 전 확인 사항

시작하기 전에​

1단계: 지도와 채팅 레이어 배치하기​

3단계: kaleidr.js 로드하기​

3단계: 지도를 생성하고 패널을 장착하는 콜백 정의​

4단계: 콜백 아래에서 Google Maps 스크립트 불러오기​

전체 페이지​

동작 방식​

작동 확인하기​

작동하지 않는 경우​

제한 사항​

다음 단계​