kaleidr.js — o loader

Uma única tag script instala window.Kaleidr e define o elemento <kaleidr-map>:

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

A façade é um loader leve. Ela gerencia apenas: versão, configuração, carregamento de scripts, registro de produtos, passagem de chaves, seleção da forma de integração, ciclo de vida da montagem, normalização de erros e flag de dormancy. O comportamento real de cada produto fica em seu próprio bundle, carregado sob demanda por URL no primeiro uso.

Kaleidr.mount(target, options) → KaleidrHandle

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

Retorna um handle de forma síncrona enquanto o bundle do produto carrega em segundo plano; chamadas feitas antes do carregamento entram em fila e são executadas quando estiver pronto.

Opções

Opção	Tipo	Observações
product	'chat' | 'viewer' | 'editor' | 'tile'	Obrigatório. Seleciona o bundle + a forma de integração padrão.
publishableKey	string	Chave de navegador publishable (kld_pk_live_…). Obrigatória para chat/editor/tile; viewer não deve receber uma chave e rejeita com product_not_allowed se uma for passada. O SDK troca a chave por uma sessão de curta duração vinculada à origem em tempo de execução.
apiKey	string	Alias obsoleto de publishableKey. Também aceita uma chave legada kld_live_….
shareId / mapId	string	Apenas Viewer. Obrigatório — omiti-lo causa erro no carregamento do bundle.
styleId	string	Tile/editor. Tile: um ID de estilo de mapa-base Kaleidr (padrão: canvas padrão do viewer). Editor: um ID de estilo ou URL completa de estilo — se omitido, aplica-se o padrão salvo da organização e depois kaleidr-morning.
map	map instance	Chat: seu mapa Mapbox / MapLibre / Google ativo na página ao qual será anexado.
mapTarget	string	Chat: seletor CSS de um elemento de mapa host (caminho declarativo).
contained	boolean	Apenas Chat. Padrão false. Fixa o painel dentro do elemento de montagem em vez de deixá-lo flutuar em document.body — sem isso, o painel sai do layout e parece quebrado.
center zoom		Câmera inicial (viewer, editor, tile).
pitch bearing		Câmera inicial em viewer, editor e tile.
theme	object or JSON object string	Conjunto de tokens CSS (ex.: { '--kd-accent': '#2da84a' }). Chat também aceita atualização em tempo real pelo handle. Temas nomeados como string não são suportados; passar uma string simples gera um aviso e é ignorado.
doorway	'iframe' | 'attach'	Opção de escape — substitui o padrão do produto.
base	string	Substitui a origem CDN da qual os bundles são carregados (dev / self-host).
viewerBase	string	Viewer/tile: a origem carregada pelo iframe. Diferente de base — o iframe nunca aponta para o CDN.
tileBase	string	Editor: o CDN de tiles usado para resolver valores styleId do catálogo. Padrão https://tile.kaleidr.com.
apiBase	string	Deve incluir o caminho do serviço. Padrão https://api.kaleidr.com/inference-api; uma origem simples como https://api.kaleidr.com retorna 404 na troca de sessão. Aplica-se a chat, editor e tile — qualquer produto que execute uma troca de sessão.
enabled	boolean	Substituição de dormancy por montagem.

KaleidrHandle

O formato do handle é um superset — cada produto implementa apenas os métodos que consegue suportar. Consulte Handle matrix para saber qual método faz o quê em cada produto.

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

Atualmente, chamar um método não suportado registra um aviso [kaleidr] e retorna — o loader não lança erro. Esse comportamento faz parte do contrato do alias principal v1.

Kaleidr.init()

Atualiza qualquer <kaleidr-map> já existente no DOM. É chamado automaticamente no carregamento; chame-o depois de inserir elementos dinamicamente.

Kaleidr.enable(on = true)

O SDK está ativo por padrão — você não precisa habilitar nada, e o quickstart funciona como está escrito.

enable() funciona como interruptor de desligamento: passar false impede que mount() carregue qualquer bundle, permitindo colocar incorporações atrás de um banner de consentimento ou desativá-las em uma página sem remover o markup. O mesmo interruptor está disponível como window.__KALEIDR_EMBED_ENABLED__ = false (antes de o script ser executado) ou pelo atributo flag / opção enabled por montagem.

Kaleidr.version

A string de versão do loader.

Substituir a base do CDN

Para desenvolvimento local ou self-hosting, aponte o loader para outra origem:

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>