kaleidr.js, o carregador

kaleidr.js é o script inicial de todas as incorporações Kaleidr. Define o global window.Kaleidr e o elemento personalizado <kaleidr-map>. É pequeno e não contém biblioteca de mapas nem código de produto. Ao montar um produto, carrega seu pacote da mesma CDN e passa as opções.

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

Não existe pacote npm. O SDK é carregado apenas com uma tag de script. Para React, Next.js, Vue e TypeScript, consulte Integração com frameworks.

Carregar o script

Pergunta	Resposta
Onde colocar a tag?	Em qualquer lugar. Os elementos <kaleidr-map> montam independentemente de aparecerem antes ou depois dela.
Quando posso chamar Kaleidr.mount?	Após o script executar. Com uma tag <script src> comum, qualquer script posterior pode chamar.
Posso usar async ou defer?	Sim para elementos. Para Kaleidr.mount, aguarde o evento load da tag, pois window.Kaleidr só existe depois dele.
Com que frequência?	Uma vez por página.
Posso adicionar integrity?	Não. O arquivo é atualizado no mesmo endereço e um hash fixo deixará de conferir na próxima versão. Veja Versionamento da CDN.
Roda no servidor?	Não. Precisa de window e document. Em apps renderizados no servidor, carregue apenas no navegador.

Carregando com async e montando quando o script chegar:

<div id="map" style="height:480px"></div>
<script>
  const s = document.createElement('script');
  s.src = 'https://cdn.kaleidr.com/embed/v1/kaleidr.js';
  s.async = true;
  s.onload = () => {
    Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });
  };
  document.head.appendChild(s);
</script>

window.Kaleidr

Membro	Descrição
Kaleidr.mount(target, options)	Monta um produto em um elemento e devolve um handle.
Kaleidr.init()	Inicializa os elementos <kaleidr-map> já presentes no documento. Raramente necessário.
Kaleidr.enable(on)	Liga ou desliga as montagens posteriores.
Kaleidr.version	String de versão do carregador.

Kaleidr.mount(target, options)

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

Parâmetro	Tipo	Descrição
target	Seletor CSS ou HTMLElement	Elemento alvo. Um seletor é resolvido uma vez com document.querySelector.
options	objeto	Obrigatório. Veja Opções.

Retorna um handle.

Comportamento:

• Retorna imediatamente. A troca de sessão e o carregamento do pacote ocorrem em segundo plano. Chamadas ao handle ficam em fila e são aplicadas, na ordem, quando o produto estiver pronto. Para Viewer e Tile, quando o mapa dentro do iframe avisar que está pronto; setCamera logo após mount funciona.
• Uma montagem malsucedida não lança exceção. Alvo ausente, pacote indisponível, sessão recusada ou ID inválido geram erro no console com [kaleidr:<product>]. Ainda se recebe um handle, mas seus métodos não fazem nada. A única chamada que lança exceção é Kaleidr.mount('#map') sem objeto de opções: TypeError.
• Não avisa seu código. Não há promessa para aguardar nem callback. Veja Verificar a montagem.
• Uma montagem por alvo. Antes de montar de novo, chame handle.destroy() no anterior. Destruir e remontar no mesmo elemento é seguro mesmo durante o primeiro carregamento: a montagem destruída não interfere na nova.

Opções

Opção	Tipo	Padrão	Produtos	Descrição
product	'chat' | 'viewer' | 'editor' | 'tile'	nenhum, obrigatório	todos	Produto a montar.
publishableKey	string	nenhum	chat, editor, tile	Sua chave publicável kld_pk_…. O SDK a troca por uma sessão curta e fornece apenas a sessão ao produto. Não passe ao Viewer. Uma chave de servidor (kld_sk_…) é recusada antes da requisição.
shareId	string	nenhum	viewer, chat	Viewer: ID do mapa publicado. Chat sem chave: mapa publicado cujo proprietário fornece o chat.
mapId	string	nenhum	viewer	Apelido de shareId se shareId não for informado.
styleId	string	mapa-base padrão da organização	tile, editor	ID de estilo, como kaleidr-morning, ou URL de estilo completa.
map	instância de mapa ativa	nenhum	chat	Mapa que o assistente controla: Mapbox GL JS, MapLibre GL JS, Google Maps ou Leaflet. Veja Mapas compatíveis. Omita para chat sem mapa.
mapTarget	seletor CSS	nenhum	chat	Elemento Viewer ou Tile <kaleidr-map> que o assistente controla em vez de map.
contained	booleano	false	chat	Fixa o painel dentro do alvo, que precisa de posicionamento e tamanho. Por padrão, janela fixa no canto superior esquerdo.
lang	string	<html lang> válido da página, senão inglês	chat	Idioma das respostas como tag BCP 47, por exemplo en, ko ou pt-BR. Veja Idioma do Chat.
title	string	título próprio do painel	chat	Título do cabeçalho; no elemento, o atributo é chat-title.
placeholder	string	marcador do painel	chat	Texto de exemplo na entrada.
center	[longitude, latitude]	padrão do produto	viewer, tile, editor	Centro inicial.
zoom	número	padrão do produto	viewer, tile, editor	Zoom inicial; Viewer e Tile precisam também de center.
pitch	número	padrão do produto	viewer, tile, editor	Inclinação inicial em graus.
bearing	número	padrão do produto	viewer, tile, editor	Rotação inicial em graus.
theme	objeto ou string JSON de objeto	nenhum	chat, editor	Chat: propriedades CSS personalizadas, por exemplo { '--highlight-color': '#0b5fff' }. Editor: 17 chaves de tema. Strings que não são JSON são ignoradas com aviso.
enabled	booleano	nenhum	todos	Controle por montagem do bloqueio de ativação. Lido apenas na montagem.
base	URL	https://cdn.kaleidr.com	todos	Origem dos pacotes. Só a origem é usada, com pacotes em /embed/v1/. Apenas as origens permitidas pela substituição de base são respeitadas; outras são ignoradas com aviso.
viewerBase	URL	https://map-embed.kaleidr.com	viewer, tile	Origem do iframe; só a origem é usada.
apiBase	URL	https://api.kaleidr.com/inference-api	chat, editor, tile	Destino da troca de sessão e das requisições. Deve incluir /inference-api; apenas a origem resulta em 404.
tileBase	URL	https://tile.kaleidr.com	editor	Host onde IDs de estilo são resolvidos.

Observações:

• apiKey é um apelido obsoleto de publishableKey.
• As quatro opções …Base servem para testes de outras implantações; não são necessárias em produção. base move apenas os pacotes: a página do mapa, API e host do mapa-base ficam na Kaleidr, a menos que cada um seja alterado.
• lang, title e placeholder são lidos na montagem. Para alterar, destrua e monte de novo.
• Opções não usadas por um produto são ignoradas sem aviso.

Substituição de base

base (opção ou atributo) e o global window.__KALEIDR_EMBED_BASE__ indicam a origem dos pacotes. A substituição só vale quando a origem é uma destas:

Origem permitida	Exemplo
CDN da Kaleidr	https://cdn.kaleidr.com
Origem de onde kaleidr.js foi carregado	kaleidr.js vem de https://static.example.com e base é https://static.example.com.
Origem da própria página	Página em https://www.example.com/… com base definido como https://www.example.com.

Qualquer outro valor é ignorado. A montagem acontece, os pacotes vêm da CDN padrão e o console mostra um aviso:

[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.

O global deve ser uma string; qualquer outro valor é descartado sem mensagem. Hospedagem própria funciona dentro dessa regra se carregador e pacotes vierem da mesma origem.

Câmera padrão por produto:

Produto	Câmera padrão
viewer	Vista salva pelo autor do mapa.
tile	Vista padrão do estilo ou do mundo todo.
editor	Centro [0, 0], zoom 2, inclinação 0, rotação 0.
chat	Não se aplica; Chat não cria mapa.

Detalhes em cada referência: Chat, Viewer, Tile, Editor.

O handle

Kaleidr.mount retorna o mesmo formato de handle para todos os produtos.

interface KaleidrHandle {
  readonly product: 'chat' | 'viewer' | 'editor' | 'tile';
  setCamera(camera: {
    center?: [number, number]; // [longitude, latitude]
    zoom?: number;
    pitch?: number;
    bearing?: number;
    duration?: number;         // milliseconds
  }): void;
  setTheme(theme: string | Record<string, string>): void;
  setStyle(style: string): void;
  destroy(): void;
}

Todos os métodos existem em todo handle. O efeito depende do produto:

Método	chat	viewer	editor	tile
setCamera(camera)	avisa	sim	sim	sim
setTheme(theme)	sim	avisa	avisa	avisa
setStyle(style)	avisa	avisa	avisa	sim
destroy()	sim	sim	sim	sim

“Avisa” significa que a chamada não faz nada e o console mostra um aviso.

[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. See the handle matrix at https://docs.kaleidr.com/sdk/kaleidr-map-element#handle-matrix.

Isso faz parte do contrato /embed/v1: método não suportado nunca lança exceção.

Detalhes dos métodos:

• setCamera: campos omitidos mantêm seus valores. duration anima o movimento; ausente ou 0, o mapa muda imediatamente. No Chat, setCamera não é suportado porque o painel não é dono do mapa. Mesmo assim, o assistente move o mapa ao responder; para mover por conta própria, use a API da biblioteca do mapa.
• setTheme: apenas Chat. Aceita objeto de propriedades CSS personalizadas ou string JSON dele.
• setStyle: apenas Tile. Aceita ID ou URL de estilo.
• destroy: remove o que foi montado, para renovações da sessão e descarta chamadas pendentes. Chamar duas vezes é inofensivo. Um handle destruído não pode ser reutilizado; monte novamente.

Você pode chamar o handle imediatamente após mount. Em Viewer e Tile, setCamera (e setStyle no Tile) chamado antes de o mapa do iframe ficar pronto é guardado e aplicado em ordem quando o mapa envia kaleidr-embed:ready ou sua primeira posição de câmera. Guardam-se as 256 chamadas mais recentes. Se não houver sinal após uma espera limitada, geralmente 10 segundos depois do iframe carregar, as chamadas são enviadas assim mesmo e um aviso aparece:

[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. The frame may be showing an error (an unpublished map, a blocked request).

A espera começa quando o iframe carrega; um iframe fora da tela que ainda não começou a carregar conserva as chamadas. Não é preciso aguardar kaleidr-embed:ready. Essa mensagem e kaleidr-embed:error ainda indicam sucesso ou falha; veja Mensagens do Viewer.

O handle não tem promessa ready, método on() nem membro map ou iframe.

Kaleidr.init()

Inicializa todos os elementos <kaleidr-map> existentes no documento no momento da chamada. O carregador já faz isso, e os elementos inseridos depois se montam sozinhos. Raramente necessário; chamadas repetidas são inofensivas.

Bloqueio de ativação

As incorporações ficam ativadas por padrão. Com o bloqueio desligado, Kaleidr.mount não carrega nem envia nada e devolve um handle inerte. Use para esperar o consentimento do visitante ou desligar incorporações sem remover o HTML.

Os três controles

Controle	Alcance	Como definir
Sinalizador da página	Todas as montagens na página	window.__KALEIDR_EMBED_ENABLED__ = false, antes das montagens a reter
Kaleidr.enable()	Todas as montagens seguintes	Kaleidr.enable(false)
Por montagem	Uma montagem	Opção enabled: false ou atributo flag="false"

Como a montagem decide

Em cada montagem, o SDK consulta os três controles:

1. Se qualquer controle for explicitamente false, a montagem é retida.
2. Senão, se algum controle for explicitamente true, ela ocorre.
3. Caso contrário, vale o padrão ligado.

Três consequências importantes:

• Um false só pode ser liberado pelo controle que o definiu. Kaleidr.enable(true) não libera um enabled: false nem um sinalizador da página em false. Controles não se sobrepõem.
• O bloqueio é verificado apenas na montagem. Liberar um controle não inicia as montagens retidas; desligá-lo não remove as existentes. Após liberar, monte de novo com Kaleidr.mount ou remova e reinsira o elemento.
• O sinalizador é lido em todas as montagens, não só quando o script carrega. Uma atribuição posterior afeta a montagem seguinte.

Bloqueio definido por	Como liberar
window.__KALEIDR_EMBED_ENABLED__ = false	Atribuir true ou excluir a variável.
Kaleidr.enable(false)	Chamar Kaleidr.enable(true) ou Kaleidr.enable(null) para voltar ao padrão.
enabled: false ou flag="false"	Montar novamente sem ele. Alterar flag em elemento já montado não funciona.

Quando uma montagem é retida, o console mostra um aviso indicando o controle responsável:

[kaleidr] embed is disabled — window.__KALEIDR_EMBED_ENABLED__ is false. Reassigning it releases that lever — Kaleidr.enable() cannot.

Valores aceitos

Os controles são rigorosos com valores booleanos para que strings inesperadas não liguem as incorporações por engano.

Controle	Conta como true	Conta como false	Ignorado com aviso
window.__KALEIDR_EMBED_ENABLED__	true	false	Qualquer valor não booleano, inclusive as strings "true" e "false"
Kaleidr.enable(x)	sem argumento, true, "true", "1", "yes", "on"	false, 0, "", "false", "0", "no", "off"	Outras strings, undefined, objetos, funções
Opção enabled	true, "true", "1", "yes", "on"	false, 0, "", "false", "0", "no", "off"	Outras strings, objetos, funções
Atributo flag	flag sem valor, "true", "1", "yes", "on"	"false", "0", "no", "off"	Qualquer outro valor

A comparação ignora maiúsculas, minúsculas e espaços ao redor. Dois cuidados com valores armazenados:

• Kaleidr.enable(null) redefine o controle para o padrão; não significa “sem preferência”. localStorage.getItem(key) retorna null quando nada foi gravado, como antes do consentimento. Nunca encaminhe o valor armazenado diretamente; compare antes: Kaleidr.enable(stored === 'true').
• Valor ignorado preserva o estado anterior do controle; não ativa nem desativa.

Exemplo: aguardar consentimento para montar

A página retém todos os elementos pelo sinalizador, que funciona porque os elementos montam assim que o carregador executa. Após consentimento libera o mesmo controle e reinsere os elementos para montar.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Consent-gated map</title>
  <script>
    // A real boolean, set before the loader. A stored string is compared, never passed through.
    window.__KALEIDR_EMBED_ENABLED__ =
      localStorage.getItem('embeds-consent') === 'true';
  </script>
  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
</head>
<body>
  <div id="banner">
    This page shows an interactive map from Kaleidr.
    <button id="accept">Show the map</button>
  </div>

  <kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
               style="display:block; height:480px"></kaleidr-map>

  <script>
    const banner = document.getElementById('banner');
    if (window.__KALEIDR_EMBED_ENABLED__) banner.hidden = true;

    document.getElementById('accept').addEventListener('click', () => {
      localStorage.setItem('embeds-consent', 'true');
      banner.hidden = true;

      // 1. Release the lever that held the embeds.
      window.__KALEIDR_EMBED_ENABLED__ = true;

      // 2. A held element does not mount by itself. Re-insert each one.
      document.querySelectorAll('kaleidr-map').forEach((el) => {
        const parent = el.parentNode;
        const next = el.nextSibling;
        el.remove();
        parent.insertBefore(el, next);
      });
    });
  </script>
</body>
</html>

Antes do consentimento, a aba Rede mostra kaleidr.js e nada mais da Kaleidr: sem pacote, requisição de sessão ou iframe.

Se montar por JavaScript, dispense o bloqueio: só chame Kaleidr.mount após o consentimento. Ele é útil para elementos HTML, gerenciadores de tags ou código de outras equipes que chama mount, quando você precisa de um interruptor para a página toda:

Kaleidr.enable(false);            // hold every later mount
// …
Kaleidr.enable(true);             // release it
const handle = Kaleidr.mount('#map', { product: 'viewer', shareId: 'YOUR_MAP_ID' });

Globais da página

Global	Tipo	Leitura	Finalidade
window.__KALEIDR_EMBED_ENABLED__	booleano	Em cada montagem	Sinalizador da página do bloqueio de ativação.
window.__KALEIDR_EMBED_BASE__	string de URL	Em cada montagem	Origem dos pacotes em hospedagem própria. Só a origem conta e deve ser permitida pela substituição de base. Veja Versionamento da CDN.

Verificar a montagem

O SDK não fornece ao seu código aviso de sucesso ou falha. Você pode observar:

Produto	Carregado	Falhou
viewer	O iframe envia kaleidr-embed:ready.	O iframe envia kaleidr-embed:error ou o console mostra erro [kaleidr:viewer].
tile	O iframe envia kaleidr-embed:ready.	Sessão recusada só no console; erro de desenho envia kaleidr-embed:error.
chat	Sem sinal; o painel aparece na página.	Só no console.
editor	Sem sinal; o editor aparece na página.	Só no console.

As duas mensagens estão em Mensagens do Viewer.

Quando uma montagem falha

Causa	O que aparece	Requisição enviada?
O seletor não encontra alvo	[kaleidr:<product>] mount target not found: <selector>	Não
Elemento sem product válido	[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	Não
Chave de servidor informada	[kaleidr:<product>] 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.	Não
Chave desconhecida ou revogada, ou origem não permitida	Erro CORS em sessions, depois erro [kaleidr:<product>] de requisição. Nada aparece.	Sim
Escopo insuficiente, restrição de produto ou plano incompatível	[kaleidr:<product>] kaleidr session exchange failed (403). Nada aparece.	Sim
Cargas de mapa esgotadas (tile) ou muitas sessões	[kaleidr:<product>] kaleidr session exchange failed (429). Nada aparece.	Sim
Pacote não carrega	[kaleidr:<product>] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/<product>.js	n/a
Viewer sem ID ou com ID inválido	[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.	Não
Editor sem chave	[kaleidr:editor] [editor-embed] attach() requires an { apiKey }	Não
Chat sem chave nem shareId	Painel aparece, mas todas as perguntas falham.	Não na montagem
Bloqueio desligado	[kaleidr] embed is disabled — …	Não

O SDK nunca exibe o motivo do servidor. Para uma sessão recusada, registra apenas o status HTTP. O motivo está no corpo da resposta: para 403/404, campo detail, como {"detail":"insufficient_scope"}; para 429, campo error, com frase em detail. A exceção map_load_quota_exceeded vem em detail. Na aba Rede, abra a requisição sessions. Se CORS ocultar a resposta, refaça em um terminal:

curl -i https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "x-api-key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "content-type: application/json" \
  -d '{"product":"chat"}'

HTTP/2 403
content-type: application/json

{"detail":"origin_not_allowed"}

Use a origem exata da página com erro. No teste, passe "chat", "editor" ou "viewer": troca bem-sucedida de "tile" conta uma carga de mapa. Veja Erros para todos os códigos.

Uma primeira troca malsucedida encerra aquela montagem. O SDK não tenta novamente. Corrija e remonte.

Troca de sessão em resumo

Para Chat, Editor e Tile, o SDK nunca usa a chave publicável diretamente na API de execução; primeiro a troca por uma sessão.

1. Ao montar, envia POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions com cabeçalho x-api-key: <your publishable key> e corpo {"product":"<product>"}. O navegador adiciona Origin.
2. A Kaleidr verifica em ordem: se a chave é publicável, se há origem, se a origem é permitida quando há lista, se chave e plano permitem o produto, e o escopo: ai para Chat, design para Editor, maps para Tile, nenhum para Viewer.
3. Resposta: {"session_token": "…", "expires_in": 900, "product": "…", "basemap_style_id": …}. basemap_style_id indica mapa-base padrão da organização, ou null quando não há.
4. O produto usa o token de sessão, vinculado à origem e ao produto, nas chamadas.
5. O SDK renova 90 segundos antes de expirar e quando uma aba em segundo plano retorna com sessão quase vencida. Se a renovação falhar, tenta a cada 30 segundos enquanto a montagem existir.
6. handle.destroy() interrompe as renovações.

Viewer não precisa de sessão. Chat com shareId, sem chave, obtém a sessão do mapa publicado, não de uma chave. Veja Chat em mapa publicado.

Requisição e resposta estão em Endpoints. Tipos de chave, sessões e limites da lista de origens permitidas estão no Modelo de segurança.

Outras mensagens de console

Mensagem	Significado
[kaleidr] <method>() is not supported on product "<product>" — the call is a no-op. …	Você chamou um método do handle não suportado pelo produto.
[kaleidr] <method>() IS supported on product "<product>", but this mount did not expose it, so the call did nothing. …	O pacote em cache é mais antigo que o carregador; recarregue sem cache.
[kaleidr] the map frame has not reported ready — calls held for it are sent now, and may reach no map. …	O mapa Viewer/Tile não sinalizou prontidão no prazo descrito no handle. As chamadas setCamera e setStyle foram enviadas mesmo assim; observe kaleidr-embed:error.
[kaleidr] theme must be an object of CSS tokens, not an array; ignored.	theme era array.
[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.	theme era uma string sem { inicial.
[kaleidr] theme JSON parse failed (…); ignored.	JSON de theme inválido.
[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. …	flag ou contained tinha valor inválido; a mensagem mostra flag="…" ou contained="…".
[kaleidr] base "<value>" is IGNORED — bundles load from <origin>. …	base ou window.__KALEIDR_EMBED_BASE__ apontou uma origem não permitida pela substituição de base; usa-se a CDN padrão.
[kaleidr] window.__KALEIDR_EMBED_ENABLED__ must be a boolean; got <type> (…). …	Sinalizador da página não era booleano e foi ignorado.
[kaleidr] Kaleidr.enable(): "<value>" is not a recognized boolean — the value is IGNORED. …	Valor inválido em Kaleidr.enable.
[kaleidr] enabled: "<value>" is not a recognized boolean — the value is IGNORED. …	Valor inválido em enabled.
[kaleidr] Kaleidr.enable(undefined) is IGNORED and leaves the gate exactly as it was. …	Chamaram Kaleidr.enable com undefined.
[kaleidr] Kaleidr.enable(null) RESET the gate to the build default, releasing the <value> set earlier. …	Kaleidr.enable(null) liberou uma configuração anterior.

Não disponível

• Pacote npm, compilação ES module ou tipos fornecidos. Copie a declaração de Integração com frameworks.
• SDK nativo para iOS, Android, React Native ou Flutter.
• Promessa ready, eventos ou callbacks no handle.
• Cliente JavaScript da API sem montar um produto. Use a API de servidor no backend.

Relacionados

• Elemento <kaleidr-map>
• Integração com frameworks
• Versionamento da CDN
• Política de segurança de conteúdo
• Solução de problemas