Pular para o conteúdo principal

Viewer

O Viewer incorpora na sua página um mapa publicado no Kaleidr Studio. O mapa é apresentado num iframe alojado pela Kaleidr, pelo que a sua página não precisa de carregar uma biblioteca de mapas nem de uma chave de API. Basta o identificador do mapa publicado.

Use o Viewer quando o mapa já existe no Studio e pretende mostrá-lo aos visitantes: localizador de lojas, mapa de campus, percurso de um evento ou mapa de dados num artigo.

Em resumo​

PerguntaResposta
Do que preciso?Do identificador de um mapa publicado. Sem chave de API nem sessão.
Que plano?Todos os planos, incluindo Free. Publicar exige uma conta Kaleidr.
Como é apresentado?Num iframe servido a partir de https://map-embed.kaleidr.com.
O que mostra?O mapa publicado pelo autor: marcadores, percursos, camadas estilizadas, conjuntos de dados e sobreposições de imagens carregados no painel Dados do Studio.
Como o incorporo?Com um <iframe> simples ou com o elemento <kaleidr-map product="viewer"> do SDK.
Quanto custa?Cada visualização conta como um carregamento de mapa para a organização proprietária.
A página pode controlar o mapa?Pode definir e mover a câmara e receber mensagens de carregamento e erro. Nada mais.

Incorporação mínima​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer"
             share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

Substitua YOUR_MAP_ID pelo identificador mostrado no código de incorporação do Studio após publicar. O elemento usa display:block por predefinição, pelo que height se aplica. O exemplo também define display:block para versões do Safari anteriores à 16.4, nas quais o elemento continua em linha e ignora height.

Se não puder adicionar scripts à página (um construtor de sites, um CMS ou uma ferramenta de newsletters que aceite HTML), use o iframe gerado pelo Studio:

<iframe
  src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID"
  width="100%"
  height="480"
  style="border:0;"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation; microphone; fullscreen; clipboard-write"
  title="Kaleidr map"
></iframe>

Ambas as opções mostram o mesmo mapa. Incorporar um mapa publicado explica quando escolher cada uma.

Como funciona​

  1. Publica um mapa no Studio. O Studio atribui-lhe um identificador e fornece um excerto de incorporação.
  2. A sua página carrega o excerto. O elemento do SDK, ou o iframe simples, aponta para https://map-embed.kaleidr.com/embed/YOUR_MAP_ID.
  3. A página dentro do iframe obtém e desenha o mapa publicado, incluindo os conjuntos de dados e sobreposições de imagens carregados pelo autor. Se o mapa tiver domínios permitidos, verifica primeiro se o domínio da sua página consta da lista.
  4. Depois de desenhar o mapa, o iframe envia kaleidr-embed:ready à sua página. Se não conseguir desenhar, envia kaleidr-embed:error e mostra uma breve explicação em vez do mapa.

A sua página nunca recebe os dados do mapa nem consegue aceder ao interior do iframe. A biblioteca cartográfica, os estilos e os pedidos de rede permanecem dentro do iframe, pelo que a Política de Segurança de Conteúdos só precisa de autorizar esse frame.

O que o visitante pode fazer​

  • Deslocar, rodar e inclinar o mapa e ampliar com os botões de zoom, o gesto de pinça ou a roda do rato. Deslocar com o ponteiro sobre o mapa amplia o mapa, tal como no Studio. Com o ponteiro fora do mapa, o deslocamento move a página.
  • Mostrar onde estão com o botão de localização, depois de o navegador lhes pedir autorização.
  • Abrir pop-ups de locais clicando no mapa, caso o autor os tenha ativado no Studio.
  • Consultar as legendas e a linha de atribuições no rodapé do mapa.
  • Perguntar ao Kaleidr AI sobre o mapa, no painel Ask Kaleidr quando o autor ativou Control Tower no bloco Kaleidr AI do Studio, e nos pop-ups quando Popup Window está ativo. Consulte Kaleidr AI num mapa publicado.

A incorporação é apenas de leitura. Os visitantes não podem editar o mapa e nenhuma das suas ações é guardada.

O que a sua página pode fazer​

  • Definir a câmara inicial com center, zoom, pitch e bearing. Por predefinição, usa-se a vista guardada pelo autor. Os valores fornecidos pela sua página prevalecem campo a campo.
  • Mover a câmara depois com handle.setCamera(...) ou alterando os atributos de câmara do elemento.
  • Saber quando o mapa carregou ou falhou ouvindo as duas mensagens enviadas pelo iframe.
  • Remover o mapa com handle.destroy() ou removendo o elemento.

Controlos para o proprietário do mapa​

Estes controlos ficam no Studio, não no código de incorporação:

  • Publicar e retirar de publicação. Um mapa publicado mostra o estado atualmente guardado no Studio. Uma edição guardada fica pública no carregamento seguinte da incorporação, sem voltar a publicar. Republicar regista uma nova versão publicada mantendo o mesmo link. Para editar em privado, retire primeiro o mapa de publicação e volte a publicá-lo ao terminar. Retirar de publicação para todas as incorporações; publicar novamente repõe os mesmos URLs. Consulte Retirar um mapa de publicação.
  • Dados carregados. Os conjuntos de dados e as sobreposições de imagens do mapa publicado ficam visíveis para os visitantes. Elimine um conjunto de dados no painel Dados ou retire o mapa de publicação para deixar de o disponibilizar. Os links de partilha continuam a funcionar após retirar a publicação; eliminar um conjunto de dados também o remove desses links. Um mapa publicado é público: publique apenas dados que qualquer pessoa possa ler. Consulte Dados carregados num mapa publicado.
  • Domínios permitidos. Limite os sites onde o mapa aparece. A verificação utiliza o referenciador enviado pela página, pelo que uma página sem referenciador não pode mostrar um mapa com restrição de domínio.
  • Kaleidr AI. Ative o painel Ask Kaleidr (Control Tower) e o chat com IA nos pop-ups (Popup Window) no bloco Kaleidr AI do mapa.

Limites​

  • Não há chave, pelo que controlos baseados na chave, como origens permitidas, não se aplicam. Utilize os domínios permitidos do mapa.
  • A sua página não consegue ler as camadas do mapa, adicionar marcadores nem receber eventos de clique.
  • A incorporação não redimensiona a própria altura. Atribua uma altura ao elemento ou iframe.
  • Quando a organização proprietária esgota os carregamentos de mapas do período, a incorporação mostra uma mensagem de limite até à reposição do saldo.
  • Cada visitante transfere todos os conjuntos de dados que o mapa desenha, por inteiro, pelo que mapas com tabelas grandes demoram mais a aparecer.

Próximos passos​