본문으로 건너뛰기

Editor — 지도 에디터 마운트

product="editor"는 Kaleidr 지도 에디터를 페이지에 마운트합니다. 요소 내부에 자체 MapLibre 지도를 생성하고 제어하는 attach 방식이며, iframe이 아닙니다.

  • 통합 방식: attach — MapLibre는 부모 문서에서 실행됩니다.
  • 필수 범위: design.
  • 최소 플랜: Pro — Free 키는 design 범위를 허용하지 않습니다.

시작하기 전에​

  • 페이지 origin이 키의 origin allowlist에 포함되어 있어야 합니다. 그렇지 않으면 세션 교환이 403 session_origin_mismatch로 실패합니다. file://은 Origin을 보내지 않으므로 항상 실패합니다 — HTTP(S)로 제공하세요. API 키 받기를 참조하세요.
  • CSP는 SDK loader, 'wasm-unsafe-eval'(페이지 내 MapLibre), tile/vendor host를 허용해야 합니다 — Content Security Policy를 참조하세요.

마운트​

const handle = Kaleidr.mount('#editor', {
  publishableKey: 'kld_pk_live_…',
  product: 'editor',
  styleId: 'kaleidr-night',  // catalog basemap id or a full style URL
  // Omit it and the organization's stored default applies, falling back to
  // kaleidr-morning when it has none.
});

독립형 embed는 에디터의 클라이언트 측 도구를 실행합니다 — 지도 위 편집 UI가 베이스맵 위에 마운트되고 편집 내용은 embed의 인메모리 spec에만 존재합니다(아무것도 영구 저장되지 않음). AI 기반 UI(map-design 및 Control Tower)와 3D 모델 라이브러리는 독립형 embed에 포함되지 않으며 Kaleidr backend와 host가 제공하는 asset이 필요합니다.

개발용 베이스맵에는 tileBase: 'https://tile-dev.kaleidr.com'을 전달하세요 — 카탈로그 style id가 production tile.kaleidr.com 대신 해당 주소를 기준으로 해석됩니다. 에디터 연결을 참조하세요.

카메라 옵션​

center, zoom, pitch, bearing은 마운트 시 적용됩니다. 통합 SDK는 이후 선언형 카메라 속성 변경도 editor handle을 통해 전달합니다.

Handle​

handle.destroy();
handle.setCamera({ center: [-0.12, 51.5], zoom: 11 });  // supported
  • handle.setTheme(...)은 마운트 시점에 JSON CSS-token 객체를 받습니다. handle을 통한 실시간 업데이트는 후속 SDK 릴리스에서 제공될 예정입니다(마운트 시점에는 이미 작동합니다).
  • handle.setStyle(...)은 editor에 노출되지 않습니다. 마운트 시 styleId를 사용하거나, 기반 MapLibre 지도의 자체 style API를 사용해 마운트 후 스타일을 변경하세요.

베이스맵 요청에는 키가 자동으로 포함됩니다​

Kaleidr 베이스맵은 키 인증 방식입니다 — tile.kaleidr.com은 알 수 없는 브라우저 origin을 거부합니다. 따라서 embed는 MapLibre의 transformRequest를 통해 publishable 키를 베이스맵 요청에 자동으로 추가합니다:

// what the embed does internally — you don't write this
transformRequest: (url) =>
  url.startsWith('https://tile.kaleidr.com/')
    ? { url: `${url}?key=kld_pk_live_…` }
    : { url };

알아두어야 할 두 가지 결과:

  • 키의 allowed origins에 페이지 origin이 포함되어야 합니다. 사이트 origin 없이 생성된 키는 모든 tile에 대해 429 tile_access_restricted를 반환합니다. 다음에서 업데이트하세요: kaleidr.com/api-keys.
  • Kaleidr tile URL만 다시 작성됩니다. 다른 host의 styleUrl을 전달하면 embed는 해당 요청을 그대로 둡니다 — 키가 제3자 origin에 첨부되는 일은 없습니다.