SDK de editor de mapas: como adicionar criação de mapas a um produto SaaS

Um SDK de editor de mapas adiciona criação ou edição de mapas a um produto SaaS sem obrigar os usuários a migrar para um construtor separado. O aplicativo host mantém identidade, permissões, projetos, cobrança, propriedade dos dados e política de publicação, enquanto o SDK fornece o canvas e as ferramentas dentro da página. O Kaleidr Editor monta seu próprio mapa MapLibre, autentica-se com uma chave publicável restrita por origem e mantém as alterações na memória até que o host defina a persistência.

As seções a seguir abordam limites do produto, arquitetura, montagem, persistência, segurança, experiência do usuário e erros comuns. Para conectar uma conversa a um renderizador ativo, consulte Como adicionar chat com IA a um mapa. Para conhecer a categoria mais ampla de SDKs, consulte O que é um SDK de mapas com IA?.

Fundamentos de um SDK de editor de mapas

• Superfície versus produto: o editor controla o canvas de edição; o host controla usuários, projetos, permissões, persistência e lançamento.
• Na memória por padrão: o Kaleidr Editor independente não persiste alterações; planeje o salvamento e a publicação antes do lançamento.
• Chave publicável + design: use uma chave de navegador restrita por origem com o escopo design; nunca exponha chaves de servidor.
• Monte uma vez, destrua uma vez: vincule o ciclo de vida às rotas da SPA e às trocas de tenant.
• Direitos de publicação separados: editar um rascunho não exige a mesma permissão que publicar um mapa para o público.

Como adicionar um SDK de editor de mapas a um produto SaaS?

Este guia insere um espaço de criação de mapas em um fluxo SaaS existente para que o usuário possa abrir um projeto, editar em um canvas MapLibre, escolher um estilo de mapa base, usar as ferramentas disponíveis no mapa e sair sem vazar o estado do SDK. Quando existe uma integração de persistência, salvamento, publicação e transferência continuam sob controle do host. Os exemplos usam o Kaleidr Editor porque ele documenta um produto Editor dentro da página por meio do loader compartilhado; o mesmo modelo de responsabilidades se aplica à avaliação de qualquer SDK de editor de mapas de terceiros.

Qual é a diferença entre um SDK de editor de mapas, Studio, Viewer e GIS?

Um SDK de editor de mapas é um componente reutilizável que adiciona a outro aplicativo ferramentas de criação — navegação, seleção, desenho, estilização e controles relacionados. Ele não deve substituir o sistema de contas, banco de dados, direitos de acesso, trilha de auditoria nem fluxo de projetos do host. Uma divisão confiável determina que o editor controla a superfície de edição, enquanto o produto host controla usuário, projeto, permissões, persistência e decisão de publicação.

O Kaleidr Studio é o produto completo de criação orientado primeiro por prompts e organizado em Prompt → Process → Refine → Deploy. O Kaleidr Editor é a superfície de edição incorporável. O Kaleidr Viewer exibe um mapa publicado. Esses caminhos compartilham conceitos de renderização e estilo, mas não são superfícies de produto intercambiáveis.

Como a arquitetura SaaS deve controlar o estado do editor?

Um fluxo de produção para edição de mapas exige responsabilidades claras entre a interface host, o editor, as credenciais, as políticas do backend, os sistemas de dados e a entrega. O SaaS host controla identidade, tenant, navegação, projetos, cobrança, permissões e fluxo de trabalho. O Kaleidr Editor controla a superfície de edição dentro da página, seu mapa MapLibre, o ciclo de vida e as ferramentas disponíveis no cliente. Uma chave publicável concede ao navegador acesso ao produto Editor e ao recurso design. O backend do host controla autorização, persistência, versionamento, auditoria, importações, exportações e política de publicação. Os sistemas de dados oficiais controlam conjuntos de dados e regras de negócio. Um Viewer ou outro destino entrega os resultados aprovados em modo somente leitura.

O backend do host não deve confiar em um ID de projeto, tenant ou conjunto de dados, nem em um destino de publicação fornecido pelo navegador, sem autorizá-lo novamente. Montar o editor torna a criação de mapas nativa, mas o navegador continua sendo um ambiente não confiável. A documentação pública estabelece que product: "editor" seleciona o pacote Editor, que a entrada padrão é attach/in-process em vez de iframe, que styleId aceita um ID de mapa base do catálogo ou uma URL completa de estilo, que o mapa base padrão é kaleidr-morning e que o handle sempre fornece destroy(), enquanto atualizações de câmera e tema ficam disponíveis quando compatíveis. A incorporação independente não persiste alterações e também não inclui as superfícies completas do Studio orientadas por IA, o Control Tower nem uma biblioteca autônoma de ativos 3D sem configuração adicional do backend.

Como montar o Kaleidr Editor com segurança?

Confirme o acesso Pro ou Enterprise para chaves de API e incorporações, uma chave publicável permitida para Editor com o escopo design, as origens exatas autorizadas em desenvolvimento, staging e produção, um elemento de destino com altura explícita, um estilo inicial, um modelo de projetos e permissões do host, uma estratégia de persistência e a desmontagem da SPA. Carregue uma única vez o loader versionado de https://cdn.kaleidr.com/embed/v1/kaleidr.js. O loader fica inativo por padrão; portanto, habilite as incorporações antes de carregá-lo ou passe a opção enabled em cada montagem. Uma montagem mínima é assim:

const editor = Kaleidr.mount("#editor", {
  product: "editor",
  publishableKey: "kld_pk_live_REPLACE_ME",
  styleId: "kaleidr-morning",
  enabled: true
});

window.addEventListener("pagehide", () => {
  editor.destroy();
});

Substitua a chave de exemplo por uma chave publicável real, reserve altura suficiente no canvas para as ferramentas de edição e anuncie o status de carregamento ou falha fora do mapa. O exemplo segue a referência de anexação do Editor, o guia de integração do Editor e a referência do loader kaleidr.js atuais. Ele monta o editor, mas não salva a especificação em memória, pois a referência pública do handle não documenta métodos de persistência. O elemento <kaleidr-map> pode selecionar product="editor" com publishable-key e style-id quando a marcação declarativa é suficiente. Prefira a API imperativa quando o host precisa de um handle explícito ou de um ciclo de vida gerenciado pelo framework. No React ou em outra SPA, monte uma vez em um effect e chame destroy() na limpeza; não remonte a cada alteração de um campo do formulário.

Como planejar persistência, segurança e UX?

A incorporação independente mantém as alterações na memória. As equipes geralmente escolhem um destes três caminhos: tratar o Editor como uma superfície temporária para protótipos; manter a criação completa no Kaleidr Studio quando os usuários podem sair da interface SaaS; ou desenvolver um fluxo integrado ao host com carregamento do projeto, validação, salvamento de rascunho, versionamento, resolução de conflitos, aprovação, publicação, reversão e auditoria. A referência pública do SDK do Editor não documenta métodos que possam ser inventados, como salvamento ou listeners de alteração não documentados; confirme com a Kaleidr o mecanismo compatível de transferência de estado antes de prometer salvamento aos clientes. As rotas design da plataforma, como análise de conjuntos de dados, aplicação parcial de especificações de mapa e catálogos de estilos ou temas, devem ficar no backend do host por trás de uma chave de servidor. O Editor no navegador continua usando a chave publicável por meio do SDK.

Restrinja chaves publicáveis a origens exatas, exija HTTPS fora do desenvolvimento local, limite as chaves a design e somente aos produtos necessários e destrua o editor ao trocar de conta ou tenant. No backend, autorize cada projeto e conjunto de dados por usuário e tenant, valide a propriedade independentemente do estado do navegador, valide as especificações do mapa antes de persistir ou publicar e separe as permissões de rascunho, revisão e publicação. O OWASP API Security Top 10 trata falhas de autorização no nível de objeto como um dos principais riscos: um ID de projeto fornecido pelo navegador nunca é autorização suficiente. Mantenha a interface do produto visível para que os usuários saibam qual projeto estão editando, coloque salvar e publicar na interface do host em vez de inventar um falso estado “Salvo” com base apenas em alterações na memória e reserve mais espaço vertical do que um visualizador costuma exigir. Dê à região do editor um nome acessível, preserve o acesso por teclado às ações ao redor, evite armadilhas de foco, anuncie o status de salvamento e os erros e ofereça alternativas sem arrastar sempre que possível, conforme as WCAG 2.2.

Veredito final

Um SDK de editor de mapas pode adicionar criação cartográfica a um produto SaaS sem reconstruir do zero um canvas completo de edição, a integração com o renderizador e o modelo de autenticação do navegador. Atualmente, o Kaleidr Editor oferece uma superfície incorporável dentro da página, baseada em MapLibre e autenticada por uma chave publicável com o escopo design. A incorporação independente mantém as alterações na memória; portanto, montar o editor não equivale a entregar um sistema completo e persistente de criação. Escolha o Editor SDK quando o produto precisar de uma superfície de edição integrada e a equipe host assumir projetos, permissões, persistência, publicação e auditabilidade. Escolha o Kaleidr Studio quando um fluxo completo e separado de criação for aceitável. Confirme a transferência de estado e qualquer integração assistida por IA antes de prometer salvamento aos clientes.

Adicione edição de mapas ao seu produto SaaS

Monte o Kaleidr Editor com o loader JavaScript versionado, uma chave publicável restrita por origem e o escopo design. Leia o guia de integração do Editor para conhecer as opções de anexação e o ciclo de vida. Para autenticação, endpoints de design e fluxos integrados ao host, consulte a documentação para desenvolvedores e os requisitos do Enterprise.

Perguntas frequentes

O que é um SDK de editor de mapas?

Um SDK de editor de mapas é um componente reutilizável que adiciona ferramentas de criação ou edição de mapas a outro aplicativo. O produto host normalmente mantém usuários, projetos, permissões, persistência e publicação.

O Kaleidr Editor pode ser incorporado a um produto SaaS?

Sim. O SDK atual documenta product: "editor" para montagem dentro de um elemento de destino. O Editor cria seu próprio mapa MapLibre na página.

O Editor independente salva os mapas dos usuários?

Não. A documentação pública afirma que as alterações ficam em uma especificação na memória e não são persistidas pela incorporação independente. Planeje a persistência do host antes do lançamento.

Qual credencial o Editor usa?

Use por meio do SDK uma chave publicável de navegador com o escopo design, restrita às origens aprovadas. Nunca coloque uma chave de servidor no código do navegador.

O Kaleidr Editor é igual ao Kaleidr Studio?

Não. O Studio é o produto completo de criação e publicação orientado primeiro por prompts. O Editor é a superfície de edição incorporável para uso em outro aplicativo.

References

• Kaleidr. Attach the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/guides/attach-the-editor
• Kaleidr. Auth & Scopes. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
• Kaleidr. CORS & Allowed Origins. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
• Kaleidr. Editor — Mount the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/editor-attach
• Kaleidr. Endpoints. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/endpoints
• Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 3 August 2026. https://kaleidr.com/pricing
• MapLibre. Map — MapLibre GL JS. Accessed 3 August 2026. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
• OWASP. OWASP Top 10 API Security Risks — 2023. Accessed 3 August 2026. https://owasp.org/API-Security/editions/2023/en/0x11-t10/
• World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 3 August 2026. https://www.w3.org/TR/WCAG22/

@misc{kaleidr_editor_attach,
  title  = {Editor -- Mount the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/sdk/editor-attach}
}

@misc{kaleidr_editor_guide,
  title  = {Attach the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/guides/attach-the-editor}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{kaleidr_auth_scopes,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{owasp_api_security,
  title  = {OWASP Top 10 API Security Risks -- 2023},
  author = {{OWASP}},
  note   = {Accessed 3 August 2026},
  url    = {https://owasp.org/API-Security/editions/2023/en/0x11-t10/}
}

@misc{wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 3 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}