CDN 버전 관리
SDK는 버전이 지정된 한 경로에서 다섯 개 파일로 배포됩니다. 페이지는 첫 번째 파일만 참조하면 됩니다. 제품이 마운트될 때 이 파일이 나머지를 불러옵니다.
https://cdn.kaleidr.com/embed/v1/kaleidr.js the loader: window.Kaleidr and <kaleidr-map>
https://cdn.kaleidr.com/embed/v1/chat.js the chat panel
https://cdn.kaleidr.com/embed/v1/viewer.js the viewer's iframe loader
https://cdn.kaleidr.com/embed/v1/tile.js the tile iframe loader
https://cdn.kaleidr.com/embed/v1/editor.js the editor
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
제품 번들은 페이지에서 해당 제품을 처음 마운트할 때 요청되며 페이지당 최대 한 번입니다. Viewer만 표시하는 페이지는 chat.js나 editor.js를 다운로드하지 않습니다.
v1의 의미
v1은 특정 빌드가 아니라 호환성 계약을 뜻합니다.
- URL마다 파일이 하나씩 있고 새 릴리스는 같은 위치의 파일을 교체합니다.
- 패치 버전이나 콘텐츠 해시가 포함된 경로가 없습니다.
/embed/v1.2.3/kaleidr.js라는 경로가 존재하지 않으므로 특정 버전으로 고정할 수 없습니다. - 수정 사항과 이전 버전과 호환되는 추가 기능은
/embed/v1/에 게시되며 페이지 수정 없이 전달됩니다.
Kaleidr.version은 진단에 사용하는 문자열이며 요청 가능한 빌드를 식별하지 않습니다.
v1에서 안정적으로 유지되는 항목
| 안정적으로 유지되는 항목 | 의미 |
|---|---|
| 다섯 개 URL | 계속 연결됩니다. |
window.Kaleidr | mount, init, enable, version은 문서에 명시된 동작을 유지합니다. |
| 마운트 옵션과 요소 속성 | 문서화된 옵션은 이름과 의미가 유지됩니다. |
| 핸들 | 모든 핸들에는 setCamera, setTheme, setStyle, destroy가 있습니다. 제품이 지원하지 않는 메서드는 경고만 남기고 아무 작업도 하지 않습니다. 예외를 던지거나 메서드를 제거하지 않습니다. |
| iframe 메시지 두 가지 | kaleidr-embed:ready와 kaleidr-embed:error의 문서화된 필드가 유지됩니다. |
v1 안에서 변경될 수 있는 항목:
- 기능 추가. 새로운 옵션, 속성, 핸들 메서드, 메시지 필드, 오류 코드 및 스트림 이벤트가 추가될 수 있습니다. 메시지의 알 수 없는 필드, 알 수 없는
code, 인식하지 못하는 이벤트는 무시하도록 코드를 작성하세요. - 외관. 채팅 패널, 편집기, 지도 UI의 모습은 달라질 수 있습니다.
- 문서화되지 않은 동작. 이 문서에 설명되지 않은 모든 것에는 변경이 생길 수 있습니다. SDK와 iframe 사이의 다른
kaleidr-embed:메시지, 제품 번들이 정의하는 전역 변수, 콘솔 메시지의 정확한 문구 등이 포함됩니다.
HTTP API도 /inference-api/b2b/v1/에서 같은 규칙을 따릅니다. 호환성이 깨질 때만 v2가 출시됩니다. 변경 내용은 변경 기록에 기록됩니다.
호환성 을 깨는 변경의 배포 방식
기존 v1 연동을 중단시키는 변경은 /embed/v1/에 게시하지 않습니다. 이전 버전과 함께 새로운 메이저 버전으로 출시합니다:
https://cdn.kaleidr.com/embed/v2/kaleidr.js
https://cdn.kaleidr.com/embed/v2/<product>.js
기존 v1 스크립트 태그는 계속 v1 파일을 불러옵니다. 변경 사항을 검토하고 준비가 되면 스크립트 태그의 경로를 새 메이저 버전으로 바꾸세요. 로더는 자신의 메이저 버전에 맞는 제품 번들을 요청합니다.
캐싱
모든 파일은 다음 설정으로 제공됩니다
Cache-Control: public, max-age=300
CDN 사본은 새 릴리스마다 교체됩니다.
| 질문 | 답변 |
|---|---|
| 새 릴리스가 방문자에게 얼마나 빨리 적용되나요? | 대략 5분 이내입니다. 브라우저가 지난 5분에 이전 파일을 받았다면 그 캐시가 만료될 때까지 계속 사용합니다. |
| 방문자가 페이지를 열 때마다 SDK를 다시 받나요? | 아닙니다. 가져온 뒤 5분간 캐시된 사본을 사용하고 이후 CDN에 다시 확인합니다. |
| 제 쪽에서 파일을 더 오래 캐시해도 되나요? | 권장하지 않습니다. 프록시, 서비스 워커, 빌드 단계에서 오래 보관한 사본은 업데이트 후에도 오래된 코드를 제공하게 됩니다. |
하위 리소스 무결성(integrity="sha384-…")을 넣을 수 있나요? | 안 됩니다. 릴리스마다 파일 해시가 바뀌어 브라우저가 불일치하는 스크립트를 거부하고, 다음 릴리스 후 삽입 기능이 작동하지 않게 됩니다. |
kaleidr.js를 자체 번들에 복사해도 되나요? | 같은 이유로 안 됩니다. URL을 직접 참조하세요. |
사이트의 서비스 워커가 다른 오리진의 스크립트를 캐시한다면 https://cdn.kaleidr.com을 캐시 우선 규칙에서 제외하거나 재검증 방식을 사용하세요.
로더와 번들은 별도로 출시됩니다
다섯 파일은 독립적으로 배포됩니다. 따라서 릴리스 직후 잠시 새 kaleidr.js와 브라우저 캐시에 있는 이전 제품 번들이 함께 사용되거나 그 반대일 수 있습니다. SDK는 이런 상황을 처리합니다:
-
로더는 옵션을 번들에 전달하며 오래된 번들이 새 옵션을 인식하지 못해도 허용합니다.
-
제품이 지원하는 핸들 메서드라도 캐시된 번들에 아직 없으면 호출은 아무 효과가 없고 콘솔에 안내가 표시됩니다:
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …캐시를 우회하여 새로고침하면 최신 번들을 가져옵니다. 기존 캐시가 만료되어도 문제가 자동으로 해결됩니다.
Viewer와 Tile iframe 내부 페이지는 https://map-embed.kaleidr.com에서 제공되며 별도로 배포됩니다. 페이지에서 SDK를 캐시하는 방식은 이 페이지들에 영향을 주지 않습니다.
직접 호스팅
스크립트의 출처를 모두 자체 도메인으로 통일하려면 다섯 파일을 직접 제공할 수 있습니다. 단, 직접 호스팅한 사본에는 수정 사항이 자동 반영되지 않습니다. Kaleidr 측 API와 iframe 내부 페이지는 계속 바뀌므로 갱신하지 않은 사본은 점차 호환성이 떨어집니다.
직접 호스팅 방법:
-
다섯 파일 모두
https://your-origin/embed/v1/에 복제합니다. 경로는 고정이며 오리진만 바꿀 수 있습니다. -
로더가 실행되기 전에 번들의 위치를 알려줍니다:
<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script><script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>또는 각 마운트에서
base옵션이나base속성으로 지정합니다. -
일정에 따라 다시 복제하고 Kaleidr처럼 짧은 캐시 기간으로 제공하세요.
base 덮어쓰기에서 허용되는 오리진
로더는 아무 오리진에서나 번들을 불러오지 않습니다. 페이지 전역 변수, base 옵션, base 속성에 설정한 값은 다음 오리진에 해당할 때만 적용됩니다:
- Kaleidr CDN(
https://cdn.kaleidr.com), kaleidr.js자체를 불러온 오리진, 또는- 현재 페이지의 오리진.
로더와 번들이 동일한 오리진에서 제공될 때 직접 호스팅이 작동합니다. 2단계의 구성이 여기에 해당합니다. kaleidr.js가 https://cdn.example.com에서 오므로 https://cdn.example.com을 base로 허용합니다. 페이지 자체 오리진에서 번들을 제공해도 됩니다.
다른 값은 다른 kaleidr.com 호스트를 가리키더라도 무시합니다. 삽입 기능은 계속 마운트되지만 번들은 https://cdn.kaleidr.com에서 불러오고 콘솔에 다음 메시지가 표시됩니다:
[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.
이 규칙에 맞지 않는 두 구성:
kaleidr.js를https://cdn.kaleidr.com에서 불러오면서 base가 제3의 오리진을 가리키는 경우. 로더 역시 해당 오리진에서 불러오세요.- 로더와 번들을 서로 다른 자체 오리진에서 제공하고 둘 다 페이지의 오리진이 아닌 경우. 다섯 파일을 한 오리진에서 제공하세요.
자체 스크립트 출처만 허용하는 Content Security Policy가 있는 페이지에서 이 경고가 발생하면 https://cdn.kaleidr.com 번들 요청이 정책에 차단되어 아무것도 표시되지 않습니다. 정책이 아니라 base 설정을 고치세요.
직접 호스팅이 바꾸는 것과 바꾸지 않는 것:
kaleidr.js만 직접 제공해서는 부족합니다. base 덮어쓰기가 없으면 로더는 여전히https://cdn.kaleidr.com에서 번들을 가져옵니다.base의 오리진만 사용합니다. 입력값의 경로는 무시하며 그 오리진의/embed/v1/에서 번들을 요청합니다.window.__KALEIDR_EMBED_BASE__는 문자열이어야 하며 다른 값은 무시됩니다.- 직접 호스팅으로 바뀌는 것은 스크립트의 제공 위치뿐입니다. 세션 교환은 여전히
https://api.kaleidr.com에서, Viewer와 Tile iframe은https://map-embed.kaleidr.com에서, Editor 베이스맵은https://tile.kaleidr.com에서 가져옵니다. 콘텐츠 보안 정책은 이들을 계속 허용해야 합니다.