Erros, limites e controle de versão

Erros

Um comando que falha é rejeitado com um EmbedError. O code dele é estável e feito para tomar decisões no código; message é escrita para um desenvolvedor lendo o console.

const { EmbedError } = IconMapEmbed;

try {
  await map.applyBookmark({ bookmarkId });
} catch (e) {
  if (!(e instanceof EmbedError)) throw e;
  switch (e.code) {
    case "unknown_id":        return forgetBookmark(bookmarkId);
    case "denied_capability": return hideBookmarkMenu();
    default:                  report(e.code, e.message, e.requestId);
  }
}

O que cada código significa

Os códigos se dividem em quatro famílias, e a resposta adequada é diferente para cada uma.

Sua página não tem permissão: denied_origin, denied_capability. Quem decide é o autor. denied_origin rejeita o próprio ready: nenhuma sessão foi aberta, e nada vai funcionar até que o seu site seja adicionado às origens permitidas do mapa. denied_capability significa que um grupo está desativado (ou, para exportImage e print, que um rótulo de confidencialidade recusa a exportação). Oculte o recurso; tentar de novo não ajuda.

O mapa não tem isso: unsupported_command, unknown_id, undeclared_filter. Verifique capabilities.commands antes de oferecer um recurso e construa os seletores a partir do que o mapa informa (getLayers, getBookmarks, getFilterSchema), e não de IDs no seu código.

A chamada estava errada: invalid_args, too_large. Um bug no código que faz a chamada; a mensagem indica o argumento.

Tente de novo mais tarde: rate_limited, busy, budget_exceeded, data_error, timeout, not_ready. Espere um pouco antes de tentar, em vez de repetir em loop.

Dois códigos vêm do SDK, e não do mapa: timeout (nenhuma resposta em 15 segundos; altere com a opção commandTimeoutMs) e destroyed (você destruiu ou recarregou o mapa enquanto um comando estava em andamento).

Falhas de inicialização

Se o mapa não conseguir iniciar (uma publicação revogada, um token recusado), ready é rejeitado e a opção onError é chamada. O mapa mostra a própria mensagem ao leitor, a menos que você passe hideErrors: true e mostre a sua.

Limites

Estes limites são fixos. Sua página não pode aumentá-los, e um autor não pode reduzi-los; eles também são exportados como EMBED_LIMITS.

Capacidades, não versões

await map.ready é resolvido com um descritor do que este mapa vai responder:

{
  protocol: 2,
  commands: ["getView", "setView", ...],
  events:   ["viewChanged", "featureClick", ...],
  policy:   { enabled: true, read: true, camera: true, layers: true, ... },
  map:      { publishId, surface: "published", dataMode: "snapshot", bookmarks: true, locales: ["en-US", "de-DE", ...] }
}

commands já é a interseção de três coisas: o que esta versão do mapa implementa, o que este tipo de incorporação suporta e o que o autor ativou. Então a única verificação de que você precisa é:

if (capabilities.commands.includes("exportImage")) showExportButton();

Novos comandos chegam sendo adicionados a essa lista. Uma página escrita hoje continua funcionando; uma página que quer um comando mais novo o solicita e se adapta quando ele não está disponível.

Compatibilidade entre versões antigas e novas

O mapa e o SDK são lançados separadamente, então cada um lida com o outro sendo mais antigo.

A versão combinada fica em map.protocol. Você não deve precisar dela.

Ciclo de vida

map.reload();      // reload the frame; subscriptions are restored when it is back
map.destroy();     // remove the frame; anything in flight rejects with `destroyed`

getEmbed(element) retorna o handle já montado em um elemento, e reset(element) o destrói. Isso é útil em frameworks em que o código que monta o mapa não é o mesmo que faz a limpeza.

Modelo de segurança

Para uma revisão de segurança, estas são as propriedades que importam:

• Isolamento. O mapa é executado em um iframe de outra origem. Ele não consegue ler a sua página, e a sua página não consegue lê-lo; o único canal é postMessage.
• Quem pode falar. O mapa aceita mensagens apenas da janela que o colocou no frame, e só se a origem dessa janela estiver nas origens permitidas do autor. Um frame de terceiros na sua página não consegue controlar o mapa, mesmo a partir de uma origem permitida. O SDK, por sua vez, aceita mensagens apenas do frame que criou, na origem esperada, e não envia tokens para nenhum outro lugar.
• O que pode ser dito. Uma lista fechada de comandos com argumentos validados. Nenhum deles recebe uma URL, uma consulta, um estilo, HTML ou script.
• O que volta. Só o que um leitor já pode ver: campos da dica de ferramenta, nunca linhas inteiras; nunca a configuração, as fontes de dados ou as consultas do mapa.
• Quem decide. As origens permitidas e as chaves dos grupos de comandos fazem parte da publicação assinada e são impostas dentro do mapa e, quando um comando chega aos nossos servidores (refreshData), também lá.
• O acesso aos dados não muda. A API não cria nenhum caminho novo até os dados. Um mapa publicado lê o que a publicação congelou ou o que a segurança em nível de linha do token permite; uma incorporação organizacional lê como o leitor conectado.
• Rótulos de confidencialidade. A exportação de imagem e a impressão seguem as mesmas regras de rótulos de confidencialidade de qualquer outra exportação do Icon Map.
• Telemetria. Contamos as sessões de controle e quais grupos de comandos são usados. Os valores dos argumentos (valores de filtro, seleções, títulos dos seus menus) nunca são coletados.

A mesma lista de origens permitidas também define a política frame-ancestors, então ela determina quais sites podem sequer exibir o mapa em um frame.