본문으로 건너뛰기

Tile 참고 문서

product="tile"은 스타일 ID로 선택한 Kaleidr 기본 지도를 표시합니다. SDK는 게시 가능 키를 Tile 세션으로 교환한 후 마운트 대상의 내용을 https://map-embed.kaleidr.com/?style=<style>을 로드하는 iframe으로 교체합니다. 지도는 이 iframe 안에서 렌더링됩니다.

Kaleidr는 세션을 통해 키, 권한 범위 및 페이지 출처를 확인하고 지도 로드를 집계하며 조직의 기본 바탕지도를 전달합니다. 세션은 iframe으로 전달되지 않습니다. iframe URL에는 스타일 ID와 전달한 카메라 정보(camera, pitch, bearing)만 있고 게시 가능 키나 세션 토큰은 없습니다. iframe 안의 지도도 이 둘로 요청하지 않습니다.

키게시 가능 키(kld_pk_live_…). 필수입니다.
범위maps. 새 키에 기본으로 포함됩니다.
요금제Free를 포함한 모든 요금제.
렌더링 위치https://map-embed.kaleidr.com에서 제공하는 iframe.
사용량Tile 세션당 지도 로드 1회.
CSPscript-src https://cdn.kaleidr.com, connect-src https://api.kaleidr.com, frame-src https://map-embed.kaleidr.com.

단계별 안내는 Kaleidr 바탕지도 사용을 참조하세요.

마운트​

요소를 사용하는 경우:

<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="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

JavaScript에서:

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

옵션​

마운트 옵션속성형식기본값필수설명
productproduct'tile'없음예Tile을 선택합니다.
publishableKeypublishable-key문자열없음예kld_pk_… 키이며 maps 범위가 필요합니다. 서버 키(kld_sk_…)는 요청을 보내기 전에 브라우저에서 거부됩니다.
styleIdstyle-id문자열설정된 경우 조직의 기본 바탕지도권장아래 표의 스타일 ID 또는 스타일 문서의 전체 https:// URL입니다. ^[A-Za-z0-9._:/~-]{1,200}$와 일치해야 합니다.
centercenter[longitude, latitude]; 속성은 "longitude,latitude"스타일의 기본 뷰아니요초기 중심.
zoomzoom숫자스타일의 기본 뷰아니요초기 확대 수준. 마운트 시 center가 없으면 무시됩니다.
pitchpitch숫자, 도스타일의 기본 뷰아니요초기 기울기.
bearingbearing숫자, 도스타일의 기본 뷰아니요초기 회전.
apiBaseapi-baseURLhttps://api.kaleidr.com/inference-api아니요세션 교환 요청 주소입니다. /inference-api 경로가 포함되어야 하며 운영 환경에서는 설정할 필요가 없습니다.
viewerBaseviewer-baseURLhttps://map-embed.kaleidr.com아니요iframe을 로드하는 출처로, 출처만 사용됩니다. 지도 데이터가 아닌 지도 페이지의 호스트입니다.
basebaseURLhttps://cdn.kaleidr.com아니요SDK가 tile.js를 로드하는 출처입니다. 기본 주소 재정의에 나열된 출처만 허용합니다.
enabledflag불리언없음아니요각 마운트의 활성화 게이트 설정입니다.

shareId, theme, map, mapTarget, contained, tileBase는 Tile 마운트에 영향을 주지 않습니다.

스타일 ID​

style-id모양
kaleidr-morning밝은 스타일: 흰 땅, 청록색 물, 흰 도로.
kaleidr-afternoon중간 톤의 땅, 녹색 식생, 회색 도로.
kaleidr-evening골든아워: 따뜻한 모래색과 올리브색.
kaleidr-night짙은 남색과 차콜색, 황색 고속도로.
kaleidr-plain경계와 장소 이름이 있는 흰색 캔버스. 줌 15부터 3D 건물이 표시됩니다.
kaleidr-editorial라벨을 뺀 오후 색상 팔레트로, 작은 지도나 장식용 지도에 적합합니다.

규칙:

  • ID는 정확히 일치해야 하며 대소문자를 구분합니다. 짧은 별칭은 없습니다.
  • styleId를 생략하면 세션에서 전달된 조직의 기본 바탕지도를 사용합니다. 설정되지 않았다면 iframe에 "Couldn't find a map id in the URL."이 표시됩니다. 계정 설정에 의존하지 않도록 styleId를 지정하세요.
  • 명시적으로 전달한 styleId는 언제나 조직 기본값보다 우선합니다.
  • 존재하지 않는 ID를 전달하면 iframe이 비고 kaleidr-embed:error 메시지가 maplibre_error 코드와 함께 발생합니다.
  • 허용되지 않는 문자가 포함되면 마운트하지 않습니다. 콘솔에는 [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.가 표시됩니다. 따라서 스타일 URL에는 쿼리 문자열을 포함할 수 없습니다.

카메라​

초기 카메라는 스타일의 기본 뷰를 사용하되, 전달한 각 필드가 해당 기본값을 덮어씁니다. 기본 뷰가 없는 스타일은 전 세계를 표시합니다. 중심 [0, 20], 줌 2, 기울기와 회전 없음으로 시작합니다.

  • center에서는 경도가 먼저 옵니다. [-0.1276, 51.5072]는 런던입니다.
  • 마운트 시 zoom은 center와 함께 지정한 경우에만 적용됩니다.
  • pitch와 bearing은 center와 독립적입니다.

크기​

  • iframe의 너비는 마운트 대상의 100%이며 테두리가 없고 모서리가 둥글게 처리됩니다.
  • 마운트 시 대상에 높이가 있으면 iframe 높이도 그 100%이고, 없으면 고정 500픽셀입니다.
  • 마운트 시 대상의 자식 요소를 교체하고, 인라인 위치 지정이 없다면 position:relative와 overflow:hidden을 설정합니다.
  • <kaleidr-map>은 기본적으로 display:block이므로 height가 적용됩니다. 높이를 지정하세요. Safari 16.4 이전 버전에서는 기본 블록 표시가 적용되지 않으므로 예제에 display:block도 추가합니다.

핸들​

Kaleidr.mount는 핸들을 동기적으로 반환합니다. 모든 제품의 동작은 핸들 표를 참조하세요.

멤버Tile에서의 동작
handle.product'tile'
handle.setCamera(camera)지도를 이동합니다.
handle.setStyle(style)다시 마운트하지 않고 바탕지도를 교체합니다.
handle.setTheme(theme)지원하지 않습니다. 경고만 기록합니다.
handle.destroy()iframe을 제거하고 세션 갱신을 중단합니다.

setStyle(style)​

handle.setStyle('kaleidr-night');

스타일 ID나 전체 스타일 URL을 받아 마운트 시 styleId와 동일하게 처리합니다. iframe은 새로 로드되지 않고 카메라도 유지되며 지도 로드 횟수가 추가되지 않습니다. setStyle을 지원하는 유일한 제품은 Tile입니다.

setCamera(camera)​

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 1200,            // milliseconds
});
필드형식설명
center[number, number]경도, 위도.
zoom숫자줌 수준. 마운트할 때와 달리 zoom은 center 없이도 작동합니다.
pitch숫자기울기(도).
bearing숫자회전(도).
duration숫자애니메이션 길이(밀리초). 생략하거나 0이면 즉시 이동합니다.

모든 필드는 선택 사항입니다. 생략한 필드는 현재 값을 유지합니다.

호출 시점​

setCamera와 setStyle은 Kaleidr.mount가 반환된 후 언제든지, 바로 다음 줄에서도 호출할 수 있습니다. iframe 안의 지도가 준비되기 전에 호출하면 대기열에 순서대로 보관했다가 준비되면 적용합니다. 최근 256개 호출을 보관합니다. 일정 시간(보통 iframe 로드 후 10초)이 지나도 준비 신호가 없으면 보관한 호출을 그대로 보내고 콘솔 경고를 한 번 표시합니다. 먼저 kaleidr-embed:ready를 기다릴 필요는 없습니다. 지도 시작 뷰나 스타일은 마운트 옵션으로 지정하는 편이 좋으며, 변경 과정 없이 해당 상태로 열립니다.

마운트 후 요소 속성​

마운트된 <kaleidr-map product="tile">에서 center, zoom, pitch, bearing을 변경하면 애니메이션 없이 지도가 이동합니다. style-id, publishable-key 또는 다른 속성을 변경해도 반응하지 않습니다.

iframe 메시지​

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id는 전달한 스타일 ID 또는 URL입니다. no_id일 경우 값은 null이고 iframe에 "Couldn't find a map id in the URL."이 표시되며 ready는 전송되지 않습니다.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== target.querySelector('iframe')?.contentWindow) return;
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});
  • ready는 지도가 그려지면 한 번 전송되며 setStyle 이후 다시 전송되지 않습니다.
  • maplibre_error는 ready 이전이나 이후에 여러 번 발생할 수 있습니다.
  • iframe은 loading="lazy"로 생성되므로 뷰포트에 가까워지기 전에는 메시지가 오지 않습니다.
  • 세션이 거부되면 iframe이 생성되지 않아 메시지가 없습니다. 콘솔 오류를 확인하세요.
  • iframe은 type이 kaleidr-embed:로 시작하는 다른 메시지도 게시합니다. SDK가 Chat 패널을 지도에 연결할 때 사용하지만 공개 계약에는 포함되지 않습니다.

세션 및 사용량​

Tile을 마운트할 때마다 SDK는 다음을 전송하고

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

{"product":"tile"}

다음을 받습니다.

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id는 조직의 기본 바탕지도이며 설정되지 않았다면 null입니다.

"product":"tile"로 성공적으로 교환할 때마다 조직에 지도 로드 1회가 집계됩니다. 교환 시점은 다음과 같습니다.

시점횟수
마운트 시1
마운트가 유지되는 동안 세션 만료 90초 전매번 1
탭이 다시 표시되고 세션 만료까지 90초 이내이거나 이미 만료된 경우1
destroy() 후 다시 마운트하거나 제거한 요소를 다시 삽입할 때1

참고:

  • 세션 갱신에 실패하면 30초마다 다시 시도하며 이미 표시된 지도는 제거하지 않습니다.
  • 첫 교환에 실패하면 마운트가 실패하고 자동 재시도하지 않습니다. 다시 마운트해야 합니다.
  • destroy()는 갱신을 중단합니다.
  • 카메라 이동, 스타일 변경, 방문자의 지도 조작은 집계되지 않습니다.

Tile 세션 교환은 아래 중 가장 먼저 해당하는 사유로 거부됩니다.

상태detail원인
403publishable_key_required게시 가능 키가 아닙니다.
403origin_required요청에 출처가 없습니다.
403origin_not_allowed페이지 출처가 키의 허용 목록에 없습니다.
403product_not_allowed키가 다른 제품으로 제한되어 있습니다.
403tier_capability_not_allowed현재 요금제에서 이 제품을 허용하지 않습니다.
403insufficient_scope키에 maps 범위가 없습니다.
429map_load_quota_exceeded조직의 지도 로드 할당량이 소진되었습니다.

이러한 검사에 앞서 플랫폼에서 세션 교환을 비활성화했다면 404 sessions_disabled가, 플랫폼 장애가 있다면 503 sessions_not_configured가 반환됩니다. 둘 다 키 때문에 발생하는 오류는 아닙니다. 전체 코드는 오류를 참조하세요.

Chat 연결​

Chat 마운트는 Tile 요소를 제어할 수 있습니다. Tile 요소에 id를 지정하고 Chat의 map-target 속성(마운트 옵션 mapTarget)으로 가리키세요.

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               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>

Tile 지도에서 어시스턴트는 팝업이 있는 핀을 찍고 카메라를 장소에 맞추며 경로, 도시 같은 영역의 윤곽선, 실시간 차량 위치를 그립니다. 절차는 Kaleidr 바탕지도 사용, 레이아웃은 테마와 배치, 옵션은 Chat 참고 문서에 있습니다.

콘솔 메시지​

메시지의미
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"유효한 product가 없어 마운트하지 않습니다.
[kaleidr:tile] kaleidr session exchange failed (<status>)교환이 거부되었습니다. 네트워크 탭의 응답을 보세요. 403은 detail에 코드가 있으며 map_load_quota_exceeded도 이 필드에 있습니다. 429는 error를 확인하면 됩니다. 예를 들면 rate_limited입니다.
…/sdk/sessions의 CORS 오류 후 [kaleidr:tile] 가져오기 오류키가 없거나 폐기되었거나 출처가 허용되지 않았습니다. 허용되지 않은 출처에는 CORS 헤더가 없어 브라우저가 SDK에 응답을 숨깁니다.
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.서버 키를 전달했습니다. 요청은 전송되지 않습니다.
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.styleId에 허용되지 않은 문자가 있습니다.
[kaleidr:tile] mount target not found: <selector>Kaleidr.mount가 선택자에 맞는 요소를 찾지 못했습니다.
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.jsTile 번들을 로드하지 못했습니다.
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …Tile이 지원하지 않는 핸들 메서드를 호출했습니다.
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …오래된 tile.js가 캐시에 있습니다. 캐시를 우회해 새로고침하세요.

지원하지 않는 기능​

  • 지도에 사용자 지정 마커, 레이어, 팝업 추가.
  • 클릭, 카메라 이동, 선택 이벤트.
  • 현재 카메라 상태 읽기.
  • iframe 없이 지도 사용.

관련 문서​