Pular para o conteúdo principal

Editor — monte o editor de mapas

product="editor" monta o editor de mapas da Kaleidr na sua página. Ele cria e controla seu próprio mapa MapLibre dentro do elemento — uma integração attach, não um iframe.

  • Forma de integração: attach — o MapLibre é executado no documento pai.
  • Escopo necessário: design.
  • Plano mínimo: Pro — chaves Free não permitem o escopo design.

Antes de começar​

  • A origem da sua página deve estar na lista de origens permitidas da chave. Caso contrário, a troca de sessão falha com 403 session_origin_mismatch. file:// não envia nenhum Origin e sempre falha — use HTTP(S). Consulte Obter uma chave de API.
  • Sua CSP deve permitir o loader do SDK, 'wasm-unsafe-eval' (MapLibre na página) e os hosts de tiles/fornecedores — consulte Content Security Policy.

Montagem​

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.
});

A incorporação independente executa as ferramentas do editor no lado do cliente — as superfícies de edição sobre o mapa são montadas sobre o mapa-base e as alterações permanecem na especificação em memória da incorporação (nada é persistido). As superfícies orientadas por AI (map-design e Control Tower) e a biblioteca de modelos 3D não fazem parte da incorporação independente; elas precisam de um backend Kaleidr e de recursos servidos pelo host.

Para um mapa-base de desenvolvimento, passe tileBase: 'https://tile-dev.kaleidr.com' — os IDs de estilo do catálogo serão resolvidos contra ele em vez de tile.kaleidr.com de produção. Consulte Anexar o editor.

Opções de câmera​

center, zoom, pitch e bearing são respeitados na montagem. O SDK unificado também encaminha alterações declarativas posteriores dos atributos da câmera por meio do handle do editor.

Handle​

handle.destroy();
handle.setCamera({ center: [-0.12, 51.5], zoom: 11 });  // supported
  • handle.setTheme(...) aceita um objeto JSON de tokens CSS no momento da montagem; a atualização em tempo real pelo handle chegará em uma versão posterior do SDK (na montagem já funciona).
  • handle.setStyle(...) não é exposto no editor. Use styleId na montagem ou a API de estilo do próprio mapa MapLibre subjacente para alterações após a montagem.

As solicitações de mapa-base incluem sua chave automaticamente​

Os mapas-base da Kaleidr exigem autorização por chave — tile.kaleidr.com rejeita origens de navegador que não reconhece. Por isso, a incorporação adiciona automaticamente sua chave publishable às solicitações de mapa-base por meio de transformRequest do MapLibre:

// 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 };

Duas consequências importantes:

  • As origens permitidas da sua chave devem incluir a origem da página. Uma chave criada sem a origem do seu site retorna 429 tile_access_restricted para cada tile. Atualize em kaleidr.com/api-keys.
  • Somente URLs de tiles da Kaleidr são reescritas. Se você passar uma styleUrl em outro host, a incorporação deixa essas solicitações intactas — sua chave nunca é anexada a uma origem de terceiros.