Kaleidr 기본 지도 사용하기

이 가이드를 마치면 선택한 스타일과 카메라 설정으로 Kaleidr 대화형 기본 지도를 페이지에 표시하고, 코드에서 카메라를 이동하거나 스타일을 변경할 수 있습니다. Free를 포함한 모든 요금제에서 동작하며, 새 키에 기본으로 포함되는 maps 범위가 있는 게시 가능 키가 필요합니다.

시작하기 전에

kaleidr.com/api-keys에서 발급한 게시 가능 키(kld_pk_live_…). API 키 발급을 참고하세요.
테스트 페이지의 출처(예: http://localhost:3000)가 키의 허용 출처에 포함되어야 합니다. 허용 출처를 지정하지 않은 키는 모든 사이트에서 동작합니다.
npx serve .처럼 HTTP로 페이지를 제공하는 방법이 필요합니다. 디스크에서 직접 연 파일에는 사용할 수 있는 출처가 없으므로 제한된 키에서 거부합니다.
사이트에 콘텐츠 보안 정책이 있다면 script-src에 https://cdn.kaleidr.com, connect-src에 https://api.kaleidr.com, frame-src에 https://map-embed.kaleidr.com을 허용하세요. 콘텐츠 보안 정책을 참고하세요.

1단계: 지도 추가하기

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

예상 결과: 처음에는 'Loading map…'이 표시되고 이어서 밝은 기본 지도가 나타납니다. Network 탭에서 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions로 보낸 POST가 200을 반환하고, 이후 https://map-embed.kaleidr.com/으로 문서 요청이 전송됩니다. iframe URL에는 스타일 ID만 포함되며 인증 정보는 포함되지 않습니다. 키는 세션 요청에만 사용되고 세션 토큰은 iframe URL에 넣지 않습니다.

요소에는 높이가 필요합니다. 지정하지 않으면 지도가 고정 높이 500px을 사용합니다. <kaleidr-map>은 기본적으로 display:block이므로 높이가 적용됩니다. 그래도 CSS에 명시하는 것이 좋습니다. Safari 16.4 이전 버전에서는 요소가 인라인으로 남아 height가 무시되기 때문입니다. (display:block)

2단계: 스타일 선택하기

style-id를 다음 일반 스타일 중 하나로 설정하세요.

`style-id`	모습
`kaleidr-morning`	밝은 흰색 지면, 청록색 물, 흰색 도로.
`kaleidr-afternoon`	중간 톤 지면, 녹색 식생, 회색 도로.
`kaleidr-evening`	황금빛 시간대의 따뜻한 모래색과 올리브색.
`kaleidr-night`	짙은 남색과 숯색, 호박색 고속도로.
`kaleidr-plain`	경계선과 지명이 표시된 흰색 화면. 줌 15부터 3D 건물 표시.
`kaleidr-editorial`	레이블이 없는 오후 색상. 작은 지도나 장식용.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night"
             style="display:block; height:480px"></kaleidr-map>

예상 결과: 동일한 지도 영역이 어두운 팔레트로 표시됩니다.

항상 style-id를 지정하세요. 생략하면 조직의 기본 지도가 설정되어 있을 때 해당 지도를 사용합니다. 기본 지도가 없으면 iframe에 'Couldn't find a map id in the URL.'이 표시됩니다.

스타일 ID는 정확히 일치해야 합니다. 약칭은 없으며 night는 kaleidr-night와 다릅니다.

3단계: 카메라 설정하기

카메라를 지정하지 않으면 스타일의 기본 시점으로 열리며, 대개 전 세계가 보입니다. 원하는 영역을 표시하려면 center(경도 먼저, 위도 나중)와 zoom을 전달하세요. pitch는 기울기, bearing은 회전 방향을 설정합니다.

<kaleidr-map product="tile" publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="12" pitch="45" bearing="-20"
             style="display:block; height:480px"></kaleidr-map>

예상 결과: 런던 중심부가 기울어지고 회전된 상태로 보입니다.

center 없이 zoom을 전달하면 무시됩니다. pitch와 bearing은 단독으로 동작합니다.

4단계: 코드로 카메라 이동 및 스타일 변경하기

요소 방식은 선언형 통합입니다. JavaScript에서 지도를 제어하려면 Kaleidr.mount로 마운트하고 반환된 핸들을 보관하세요.

<div id="basemap" style="height:480px"></div>
<p>
  <button id="paris">Fly to Paris</button>
  <button id="night">Night</button>
  <button id="day">Morning</button>
</p>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#basemap', {
    product: 'tile',
    publishableKey: 'kld_pk_live_…',
    styleId: 'kaleidr-morning',
    center: [-0.1276, 51.5072],
    zoom: 11,
  });

  document.getElementById('paris').addEventListener('click', () => {
    // duration is in milliseconds. Leave it out to jump with no animation.
    handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
  });
  document.getElementById('night').addEventListener('click', () => {
    handle.setStyle('kaleidr-night');
  });
  document.getElementById('day').addEventListener('click', () => {
    handle.setStyle('kaleidr-morning');
  });
</script>

예상 결과: 각 버튼이 현재 지도에서 변경을 적용합니다. iframe이 다시 로드되지 않고 Network 탭에도 새로운 세션 요청이 나타나지 않습니다.

알아둘 사항:

setCamera와 setStyle은 요소가 아닌 핸들에 있습니다.
setStyle은 Tile에서만 지원됩니다. 다른 제품에서 호출하면 경고만 남기고 아무 작업도 하지 않습니다.
Kaleidr.mount가 반환된 이후에는 언제든 핸들 메서드를 호출할 수 있습니다. iframe 안의 지도가 준비되기 전 호출은 보관되었다가 준비 신호가 오면 순서대로 적용됩니다. 6단계의 kaleidr-embed:ready 메시지를 기다릴 필요가 없습니다. 초기 카메라와 스타일은 마운트 옵션에서 지정하세요.
이미 마운트된 요소에서 center, zoom, pitch, bearing을 변경하면 지도가 움직이지만 style-id를 변경해도 아무 변화가 없습니다.

5단계: 채팅 패널을 지도에 연결하기(선택)

Kaleidr Chat 패널은 Tile 지도를 대상으로 사용할 수 있습니다. 답변에 나오는 장소를 지도에 핀으로 표시하고 카메라를 조정해 해당 장소가 보이게 합니다. Tile 요소를 위치 지정된 컨테이너에 넣고, 그 위에 채팅 요소를 겹친 다음 map-target으로 Tile 요소를 가리키세요.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile"
               publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               center="-0.1276,51.5072" zoom="11"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

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

예상 결과: 채팅 패널이 지도 왼쪽 위에 표시됩니다. 'coffee near Covent Garden'이라고 질문하면 Tile 지도에 핀이 나타납니다.

채팅 요소의 속성과 스타일이 하는 일:

항목	역할
`map-target="#basemap"`	채팅에서 제어할 Tile 요소의 CSS 선택자.
`contained`	패널을 채팅 요소 안에 배치합니다. 없으면 브라우저 창 왼쪽 위에 고정됩니다.
`position:absolute; inset:0`	채팅 요소를 지도 전체에 겹쳐 패널을 지도 모서리에 배치합니다.
`z-index:1`	채팅 레이어를 지도 위에 표시합니다.
`pointer-events:none`	패널 밖에서 지도를 끌거나 확대할 수 있습니다. 패널 자체는 계속 클릭할 수 있습니다.

참고:

기본 키에 maps와 ai 범위가 모두 있으므로 두 요소에 같은 키를 사용할 수 있습니다. 채팅 요소는 자체 세션을 요청하며 질문마다 조직의 AI 크레딧을 소비합니다.
두 요소의 순서는 중요하지 않습니다. 채팅에서 필요할 때 지도를 찾습니다.

패널 배치와 테마는 테마 및 레이아웃을, 도우미의 지원 기능과 제한 사항은 기능과 제한을 참고하세요.

6단계: 지도 로드 완료 감지하기(선택)

SDK에는 ready Promise가 없으며 요소도 이벤트를 발생시키지 않습니다. 대신 iframe이 지도를 그리면 페이지에 메시지를 보내고, 일부를 그리지 못했을 때도 메시지를 보냅니다.

const target = document.getElementById('basemap');

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  const frame = target.querySelector('iframe');
  if (!frame || event.source !== frame.contentWindow) return;

  const msg = event.data;
  if (!msg || typeof msg.type !== 'string') return;

  if (msg.type === 'kaleidr-embed:ready') {
    // { type, id: 'kaleidr-morning', source: 'tile' }
    console.log('basemap loaded', msg.id);
  } else if (msg.type === 'kaleidr-embed:error') {
    // { type, id, code: 'maplibre_error', message }, or
    // { type, id: null, code: 'no_id', message } when there is no style
    console.warn('basemap problem', msg.code, msg.message);
  }
});

세션 요청이 실패하면 iframe 자체가 만들어지지 않아 메시지가 오지 않습니다. 오류는 콘솔에서 확인하세요. 작동하지 않는 경우를 참고하세요.

전체 페이지 예제

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 basemap</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 2rem; }
    #basemap { height: 480px; }
  </style>
</head>
<body>
  <h1>Kaleidr basemap</h1>
  <p id="status">Loading the map…</p>

  <div id="basemap"></div>
  <p>
    <button id="paris">Fly to Paris</button>
    <button id="night">Night</button>
    <button id="day">Morning</button>
  </p>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const target = document.getElementById('basemap');
    const status = document.getElementById('status');

    const handle = Kaleidr.mount(target, {
      product: 'tile',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
    });

    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://map-embed.kaleidr.com') return;
      const frame = target.querySelector('iframe');
      if (!frame || event.source !== frame.contentWindow) return;
      const msg = event.data;
      if (msg && msg.type === 'kaleidr-embed:ready') {
        status.textContent = 'Map loaded.';
      }
    });

    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1200 });
    });
    document.getElementById('night').addEventListener('click', () => {
      handle.setStyle('kaleidr-night');
    });
    document.getElementById('day').addEventListener('click', () => {
      handle.setStyle('kaleidr-morning');
    });

    // In a single-page app, call handle.destroy() when the map leaves the screen.
  </script>
</body>
</html>

동작 방식

주제	동작
세션	SDK는 iframe을 만들기 전에 키를 짧은 유효기간의 Tile 세션으로 교환하고, 마운트된 동안 갱신합니다. 이때 키를 검사하고 지도 로드 1회를 기록합니다. 세션은 iframe에 전달하지 않으며 iframe URL에는 스타일과 카메라만 포함됩니다.
시작 시점	전달한 카메라 또는 스타일의 기본 시점.
스크롤	포인터가 지도 위에 있을 때 스크롤하면 지도가 확대·축소됩니다. 포인터가 지도 밖에 있으면 스크롤은 페이지를 이동합니다. 터치스크린에서는 드래그로 지도를 이동하고 손가락을 모으거나 벌려 확대·축소합니다.
높이	마운트 시 컨테이너의 높이를 사용하며, 높이가 없으면 고정 500px입니다.
로드	iframe은 화면 가까이 올 때 지연 로드됩니다.
제거	`handle.destroy()`는 iframe을 제거하고 세션 갱신을 중단합니다. `<kaleidr-map>` 요소를 제거해도 같습니다.
다시 삽입	제거한 요소를 다시 삽입하거나 다른 부모 요소로 이동하면 재마운트하고 새 세션을 생성합니다.

지도 로드 횟수 계산 방식

SDK가 Tile 세션을 얻을 때마다 지도 로드 1회로 계산합니다.

이벤트	지도 로드 횟수
지도 마운트	1
마운트된 동안 세션 갱신	갱신마다 1
마운트 제거 후 재마운트 또는 요소 재삽입	1
`setCamera`, `setStyle`, 이동, 확대·축소	0

세션은 기본적으로 15분 동안 유효하고, SDK는 만료 90초 전에 갱신합니다. 페이지가 전경 또는 배경에 있어도 같습니다. 몇 분만 보는 방문자는 보통 로드 1회를 사용하며, 페이지를 한 시간 열어 두면 약 5회가 계산됩니다.

사용량을 줄이려면:

대화상자를 닫거나, 경로를 변경하거나, 탭 패널을 제거하는 등 지도가 완전히 숨겨지면 마운트를 제거하세요.
렌더링할 때마다 요소를 다시 만들지 마세요. React, Vue 등은 프레임워크 통합을 참고하세요.
스타일 변경에는 재마운트 대신 setStyle을 사용하세요.

조직의 해당 기간 지도 로드 할당량이 소진되면 새 세션은 HTTP 429와 {"detail":"map_load_quota_exceeded"}로 거부됩니다. 이미 화면에 보이는 지도는 유지되지만 새 마운트는 아무것도 표시하지 않습니다. 할당량 및 속도 제한을 참고하세요.

작동 확인하기

페이지: 지도를 조작할 수 있고 하단에 지도 출처 표기가 나타납니다.
콘솔: [kaleidr가 포함된 오류나 경고가 없습니다.
Network 탭: https://cdn.kaleidr.com에서 kaleidr.js와 tile.js를 받아오며 POST …/sdk/sessions는 200과 session_token, expires_in이 포함된 JSON을 반환합니다. https://map-embed.kaleidr.com/?style=…으로 문서 요청도 전송됩니다.
리스너: source가 "tile"인 kaleidr-embed:ready 메시지 하나를 받습니다.

작동하지 않는 경우

SDK는 마운트 실패를 [kaleidr:tile] … 형식으로 콘솔에 기록합니다. 세션이 거부되면 HTTP 상태만 기록합니다. 자세한 원인은 Network 탭의 sessions 응답을 열어 확인하세요. 403과 map_load_quota_exceeded의 코드는 detail에, 429 rate_limited의 코드는 error에 들어갑니다.

증상	원인	해결 방법
화면이 비어 있고 `…/sdk/sessions`의 CORS 오류 및 `[kaleidr:tile]` 오류 발생	키가 없거나 취소됐거나 출처가 허용되지 않았습니다. 거부 응답에는 CORS 헤더가 없습니다.	kaleidr.com/api-keys에서 키와 정확한 출처(스킴, 호스트, 포트)를 확인해 등록하세요. 몇 분 뒤 새로고침하세요. Network 상태는 401 또는 403입니다.
`[kaleidr:tile] kaleidr session exchange failed (403)`	키에 `maps`가 없거나(`insufficient_scope`), 다른 제품만 허용되거나(`product_not_allowed`), 요금제가 요청을 허용하지 않습니다(`tier_capability_not_allowed`).	Network에서 `detail`을 확인하고 기본 범위가 포함된 키를 만드세요.
`[kaleidr:tile] kaleidr session exchange failed (429)`	지도 로드 할당량 소진(`map_load_quota_exceeded`) 또는 잦은 요청(`rate_limited`).	전자는 `detail`, 후자는 `error`를 확인하세요. 할당량 및 속도 제한을 참고하세요.
`sessions`가 404 반환	`api-base` 재정의에서 `/inference-api`가 빠졌습니다.	재정의를 제거하거나 `https://api.kaleidr.com/inference-api`를 사용하세요.
`[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	서버 키를 입력해 SDK가 요청 전 거부했습니다.	게시 가능 키를 사용하세요. 서버 키가 공개됐다면 교체하세요.
`[kaleidr:tile] Kaleidr tile: invalid style "…"…`	`style-id`에 공백이나 `?` 같은 허용되지 않는 문자가 있습니다.	2단계의 스타일 ID를 사용하세요.
iframe에 'Couldn't find a map id in the URL.'이 표시되고 `code: 'no_id'`, `id: null` 수신	`style-id`가 없고 조직 기본 지도도 없습니다.	`style-id`를 지정하세요.
iframe이 비어 있고 `maplibre_error`가 포함된 `kaleidr-embed:error` 수신	스타일이 존재하지 않습니다. 대개 ID 오타입니다.	2단계의 ID를 사용하세요.
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product`가 없거나 철자가 잘못됐습니다.	`product="tile"`로 설정하세요.
높이가 항상 500px	마운트할 때 높이가 없거나 `display:inline`을 사용했거나 Safari 16.4 미만에서 `display:block`이 없습니다.	높이와 `display:block`을 지정하세요. `height`
빈 화면과 콘텐츠 보안 정책 오류	로더, 세션 요청 또는 iframe이 차단됐습니다.	시작하기 전에의 세 호스트를 허용하세요.
`setStyle` 또는 `setCamera`가 동작하지 않음	요소에서 호출했거나 지도가 아직 준비되지 않았습니다.	`Kaleidr.mount`의 핸들에서 호출하고 `kaleidr-embed:error`와 콘솔을 확인하세요. 준비 전 호출은 이후 적용됩니다. 지도 준비 완료 알림이 제한된 대기 시간(일반적으로 iframe 로드 후 10초) 내에 오지 않아도 호출은 전송되며 콘솔에 `[kaleidr] the map frame has not reported ready`가 표시됩니다. 오류가 표시되는 프레임에는 이동하거나 변경할 지도가 없습니다.
요소의 `style-id` 변경이 동작하지 않음	정상 동작입니다. `style-id`는 최초 마운트 때만 읽습니다.	`handle.setStyle`을 쓰거나 새 요소를 삽입하세요.

제한 사항

페이지에서 Tile 지도에 마커, 레이어, 팝업을 직접 추가하거나 클릭 및 카메라 이벤트를 받을 수 없습니다. 연결된 채팅 패널은 장소를 표시할 수 있습니다.
현재 카메라 설정을 읽는 메서드가 없습니다.
Kaleidr 기본 지도를 표시하는 공식 지원 제품은 Tile입니다.
페이지 출처가 키에서 허용되지 않으면 Tile 지도를 표시하지 않습니다.

다음 단계

Tile 참조: 모든 옵션, 속성, 메시지.
프레임워크 통합: React, Next.js, Vue에서 추가 지도 로드 없이 마운트 및 제거하기.
Chat: 지도에 AI 도우미 추가하기.
할당량 및 속도 제한: 지도 로드 할당량 확인하기.

시작하기 전에​

1단계: 지도 추가하기​

2단계: 스타일 선택하기​

3단계: 카메라 설정하기​

4단계: 코드로 카메라 이동 및 스타일 변경하기​

5단계: 채팅 패널을 지도에 연결하기(선택)​

6단계: 지도 로드 완료 감지하기(선택)​

전체 페이지 예제​

동작 방식​

지도 로드 횟수 계산 방식​

작동 확인하기​

작동하지 않는 경우​

제한 사항​

다음 단계​