Integrar o editor de mapas

Ao terminar este guia, a sua página mostrará as ferramentas de edição sobre mapas do Kaleidr num mapa base Kaleidr, adaptadas à sua marca. Funciona em todos os planos, incluindo o Free. É necessária uma chave publicável com o âmbito design, incluído por predefinição nas novas chaves.

As edições não são guardadas

O editor incorporado mantém o trabalho apenas na memória da página. Nada é guardado, exportado ou publicado a partir da incorporação, e a página não recebe callbacks de alterações. Recarregar a página ou chamar handle.destroy() elimina as edições. Se precisar de mapas permanentes, crie-os no Kaleidr Studio e incorpore-os com o Viewer.

Antes de começar

Uma chave publicável (kld_pk_live_…) de kaleidr.com/api-keys. Consulte Obter uma chave API.
A origem da página de teste, por exemplo http://localhost:3000, nas origens permitidas da chave. Uma chave sem restrições funciona em qualquer site.
Uma forma de disponibilizar a página por HTTP, como npx serve ..
Se o site usar Content Security Policy, permita as diretivas do editor descritas em Content Security Policy. O editor funciona dentro da página e precisa de configurações connect-src, img-src, worker-src, font-src e style-src dispensáveis nos produtos iframe.
Não mantenha outro editor Kaleidr na mesma página.

Passo 1: adicionar um contentor com dimensões e montar

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

Resultado esperado: um mapa base Kaleidr com vista do mundo preenche o contentor (kaleidr-morning, a menos que a organização tenha definido outro padrão), com o botão Create no mapa. Selecione Create para abrir a barra lateral do editor com ferramentas de Texto, Imagem, Marcador e Popup.

O contentor precisa de ter altura. O editor ocupa 100% da largura e altura do contentor e os painéis permanecem dentro dele.

Também pode usar o elemento. É display:block por predefinição, pelo que a altura se aplica; o exemplo explicita display:block para compatibilidade com Safari anterior a 16.4:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

Passo 2: escolher o mapa base e a câmara inicial

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

Resultado esperado: mapa base escuro sobre o centro de Londres, inclinado e rodado.

O mapa base é escolhido nesta ordem:

styleId, se o fornecer. Use, por exemplo, kaleidr-morning, kaleidr-afternoon, kaleidr-evening, kaleidr-night, kaleidr-plain ou kaleidr-editorial. Veja os estilos na referência Tile.
Caso contrário, o mapa base padrão da organização, se existir.
Se nenhum estiver definido, kaleidr-morning.

Os valores iniciais da câmara são centro [0, 0], zoom 2, inclinação 0 e orientação 0. Ao contrário de Viewer e Tile, o editor aceita zoom sem center.

Uma opção de câmara passada a Kaleidr.mount que não seja um número finito é ignorada e indicada na consola. No elemento, atributos de câmara não numéricos são ignorados sem mensagem.

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

Passo 3: personalizar os painéis (opcional)

Forneça theme para harmonizar os painéis com o seu produto. Este objeto aceita até 17 chaves predefinidas; as restantes são ignoradas.

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

Resultado esperado: a ferramenta ativa, os contornos de foco e os botões principais usam a cor da marca; os painéis usam a sua fonte.

As 17 chaves estão na referência do editor.

Três aspetos importantes:

Os valores são CSS. brandColor aceita qualquer cor CSS, cardRadius qualquer medida CSS e fontPrimary qualquer valor font-family. Carregue a fonte por sua conta.
O tema aplica-se a todo o documento enquanto o editor está montado e é restaurado quando é destruído. Só afeta os seus estilos quando estes utilizam as mesmas propriedades personalizadas.
O tema só é lido durante a montagem. handle.setTheme não é suportado no editor. Para mudar o tema, destrua e volte a montar o editor, perdendo todas as edições.

No elemento, theme é uma string JSON:

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

Passo 4: mover a câmara a partir da página (opcional)

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

Resultado esperado: o mapa voa até Paris. Tudo o que o utilizador colocou no mapa permanece na respetiva localização.

setCamera é a única maneira de a sua página controlar o mapa do editor. O handle não expõe o objeto do mapa.

Passo 5: desmontar

handle.destroy();

destroy() remove o editor, o mapa e os painéis do contentor e repõe o tema. As edições são descartadas.

Numa aplicação de página única, chame destroy() quando a rota ou componente que contém o editor for removido. Se usar o elemento, removê-lo do documento tem o mesmo efeito. Consulte Integração com frameworks.

Só pode existir um editor de cada vez por página; destrua sempre o editor atual antes de montar outro.

Página completa

Guarde como index.html, insira a chave e disponibilize a pasta por HTTP a partir de uma origem permitida.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

Como funciona

Tópico	Comportamento
Onde funciona	No documento. O canvas do mapa e os painéis do editor são elementos no contentor de montagem.
Sessão	O SDK troca a chave por uma sessão de curta duração antes de iniciar o editor e renova-a enquanto estiver montado.
Edições	Apenas na memória; não são guardadas, exportadas, publicadas nem comunicadas à página.
Mapa base	Carregado pela página de `https://tile.kaleidr.com` e definido na montagem.
Tema	Aplicado a todo o documento na montagem e restaurado na destruição.
Câmara	Definida na montagem, movida por `handle.setCamera`.
Utilização	A sessão do editor não conta como carregamento de mapa e o editor incorporado não tem funções de IA que consumam créditos. As solicitações de mapa base que incluem sua chave acrescentam cargas de mapa em lotes: uma carga a cada 20 solicitações em uma hora. Consulte Cargas de mapa.
Sinais	Nenhum: sem eventos de pronto, alterações ou callbacks de erro.

Informe os utilizadores

O editor não avisa que o trabalho é temporário. Se os utilizadores passarem tempo a editar, esclareça-o na interface, como na página completa acima, para não criarem a expectativa de recuperar o mapa mais tarde.

Verificar o funcionamento

Na página: o mapa base preenche o contentor, Create abre a barra lateral e é possível colocar texto ou marcadores.
Na consola: nenhuma linha contém [kaleidr.
No separador Rede: kaleidr.js e editor.js de https://cdn.kaleidr.com, uma chamada POST …/sdk/sessions com estado 200 e pedidos a https://tile.kaleidr.com para estilos e mosaicos.

Se não funcionar

O SDK regista falhas de montagem na consola como [kaleidr:editor] …. Se a sessão for recusada, regista apenas o estado HTTP. Consulte a resposta do pedido sessions no separador Rede: num 403 o código está em detail; num 429 está em error e a explicação em detail.

Sintoma	Causa	Solução
Nada aparece. Consola: `[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	Não foi passada uma chave.	Forneça `publishableKey`.
Nada aparece; erro CORS em `…/sdk/sessions` e erro `[kaleidr:editor]`.	Chave desconhecida ou revogada, ou origem não autorizada.	Confirme a chave e adicione a origem exata (esquema, anfitrião e porta) em kaleidr.com/api-keys; aguarde alguns minutos.
`[kaleidr:editor] kaleidr session exchange failed (403)`	Falta o âmbito `design` (`insufficient_scope`), chave limitada a outros produtos (`product_not_allowed`) ou plano incompatível (`tier_capability_not_allowed`).	Consulte `detail` e crie uma chave com os âmbitos padrão.
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	Foi utilizada uma chave de servidor.	Use uma chave publicável e rode a chave de servidor se a página esteve pública.
O contentor continua vazio e sem altura.	O destino de montagem não tem altura.	Defina-a; para Safari anterior a 16.4 acrescente `display:block`.
Os painéis aparecem, mas o mapa fica vazio e `https://tile.kaleidr.com` devolve 429 com `"error":"tile_access_restricted"`.	O anfitrião do mapa base recusou o acesso.	Verifique a chave e a origem permitida, aguarde alguns minutos após alterar a chave e recarregue; contacte o suporte se persistir. `[kaleidr:editor] …`
Os painéis aparecem, mas o mapa fica vazio e a consola acusa violação CSP.	A política bloqueia o mapa base, o worker ou as imagens.	Acrescente as diretivas de Content Security Policy.
O editor não tem estilos.	A política bloqueia estilos inline.	Permita `'unsafe-inline'` em `style-src`.
O segundo editor falha ou o primeiro para.	Existem dois editores montados.	Destrua o primeiro antes do segundo.
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	O tema só é lido na montagem.	Passe `theme` ao montar.
`[kaleidr] theme string must be JSON…`	O atributo `theme` não é um objeto JSON.	Use aspas simples à volta do atributo e aspas duplas dentro do JSON.
Uma chave de tema não funciona.	A chave é desconhecida ou tem erro ortográfico; é ignorada sem aviso.	Consulte a lista.
As edições desapareceram.	A página recarregou, o editor foi destruído ou o elemento foi movido/removido.	É o comportamento esperado; veja o aviso inicial.

Limites

Nada é guardado, exportado ou publicado a partir da incorporação.
Sem callbacks de alteração, sinal de prontidão ou callback de erro.
Sem acesso ao objeto do mapa; não é possível criar camadas próprias nem ler o que foi desenhado.
Sem separador Data, catálogo de designs, painel IA, biblioteca de modelos 3D, partilha ou projetos. A barra inclui Text, Image, Marker, Popup, Background, Layer, Design e Legend; veja Âmbito.
Um editor por página.
O mapa base e o tema não podem ser alterados após a montagem.

Próximos passos

Referência do editor: todas as opções e chaves de tema.
Integração com frameworks: montar e destruir com React, Next.js e Vue.
Content Security Policy: diretivas para o editor.
Incorporar um mapa publicado: quando precisar de mapas permanentes.

Antes de começar​

Passo 1: adicionar um contentor com dimensões e montar​

Passo 2: escolher o mapa base e a câmara inicial​

Passo 3: personalizar os painéis (opcional)​

Passo 4: mover a câmara a partir da página (opcional)​

Passo 5: desmontar​

Página completa​

Como funciona​

Informe os utilizadores​

Verificar o funcionamento​

Se não funcionar​

Limites​

Próximos passos​