Pular para o conteúdo principal

Tile

Tile coloca um mapa base da Kaleidr na sua página. Você escolhe um estilo, como kaleidr-morning ou kaleidr-night, e o SDK o apresenta em um iframe hospedado pela Kaleidr. Sua página não precisa carregar uma biblioteca de mapas.

Use Tile quando quiser um mapa base bonito e interativo sem precisar desenhar nele: um fundo de localização, um painel “onde estamos” ou o mapa em que o chat da Kaleidr coloca suas respostas.

Se já utiliza um mapa próprio do Mapbox, MapLibre, Google Maps ou Leaflet, você não precisa de Tile. Vincule o Chat ao mapa que já possui.

Visão geral​

PerguntaResposta
Do que preciso?Uma chave publicável (kld_pk_live_…) com escopo maps. As novas chaves o incluem por padrão.
Qual plano?Todos os planos, inclusive Free.
Como é exibido?Em um iframe disponibilizado por https://map-embed.kaleidr.com.
Como escolho a aparência?Com style-id. Abaixo estão seis estilos de uso geral.
Quanto custa?Uma carga de mapa por sessão Tile. Veja Como são contadas as cargas de mapa.
A página pode interagir com o mapa?Pode definir e mover a câmera, trocar o estilo e ouvir mensagens de carregamento e erro.

A menor incorporação​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

Três coisas fazem tudo funcionar:

  1. Uma chave. Crie uma chave publicável em kaleidr.com/api-keys. Veja Obter uma chave de API.
  2. Uma origem permitida. Se a chave listar origens permitidas, a origem da página deverá estar entre elas. A página precisa ser disponibilizada por HTTP ou HTTPS, não aberta diretamente do disco.
  3. Uma altura. O elemento é display:block por padrão, então seu height funciona. O exemplo também inclui display:block para versões do Safari anteriores à 16.4, nas quais o elemento continua inline.

Estilos​

style-idAparência
kaleidr-morningClaro: solo branco, água ciano e ruas brancas.
kaleidr-afternoonSolo em tons médios, vegetação verde e ruas cinza.
kaleidr-eveningHora dourada: areia quente e tons oliva.
kaleidr-nightAzul-marinho escuro e carvão, com rodovias âmbar.
kaleidr-plainTela branca com limites e nomes de lugares. Edifícios 3D aparecem a partir do zoom 15.
kaleidr-editorialPaleta de tarde sem rótulos, para mapas pequenos ou decorativos.

Sempre informe style-id. Se não informar, a incorporação usará o mapa base padrão da organização, quando existir, ou mostrará um erro quando não houver nenhum.

Como funciona​

  1. O SDK envia sua chave publicável à Kaleidr e recebe uma sessão Tile de curta duração. Esta etapa verifica a chave, o escopo e a origem da página e contabiliza uma carga de mapa. A resposta também inclui o mapa base padrão da organização, quando definido. A sessão serve somente para isso: o mapa não faz outras chamadas com ela.
  2. O SDK substitui o conteúdo do elemento por um iframe com o estilo solicitado. A URL do iframe contém apenas o ID do estilo e a câmera informada, nunca sua chave publicável nem o token de sessão.
  3. O mapa é desenhado dentro do iframe. A Política de Segurança de Conteúdo da página só precisa permitir o carregador, a solicitação de sessão e o iframe.
  4. Assim que o mapa for desenhado, o iframe envia uma mensagem kaleidr-embed:ready à página.

O que o visitante pode fazer​

Mover, girar e inclinar o mapa, além de ampliar pelos botões, pelo gesto de pinça ou pela roda do mouse. Rolar com o ponteiro sobre o mapa aplica zoom ao mapa; com o ponteiro fora do mapa, a rolagem move a página.

O que sua página pode fazer​

  • Definir a câmera inicial com center, zoom, pitch e bearing.
  • Mover a câmera depois com handle.setCamera(...).
  • Trocar o estilo com handle.setStyle('kaleidr-night'), sem recarregar.
  • Vincular um painel de chat. Uma montagem de Chat pode apontar para um elemento Tile e mostrar suas respostas nele.
  • Saber quando carregou pela mensagem kaleidr-embed:ready.

Como as cargas de mapa são contadas​

O uso de Tile é medido em cargas de mapa, a mesma unidade das visualizações dos seus mapas publicados. Uma carga é contada sempre que o SDK obtém uma sessão Tile:

  • uma vez quando o mapa é montado;
  • novamente cada vez que o SDK renova a sessão, pouco antes de expirar, enquanto a montagem existir. As sessões duram 15 minutos por padrão;
  • novamente se você destruir e montar outra vez ou remover e reinserir o elemento.

Um visitante que fica poucos minutos na página usa uma carga de mapa. Uma página aberta por uma hora usa cerca de cinco. Não é “uma por visualização de página”, portanto destrua as montagens Tile que não estiver mais exibindo.

Quando a organização esgota suas cargas de mapa no período, novas sessões Tile são recusadas com HTTP 429. Uma nova montagem não exibe nada; um mapa já exibido permanece na página. Veja os limites em Cotas e limites de taxa.

Limites​

  • Tile é um mapa base. Sua página não pode adicionar seus próprios marcadores, camadas ou pop-ups, nem recebe eventos de clique ou câmera. Um painel de chat vinculado pode mostrar lugares nele.
  • Tile é a maneira compatível de exibir mapas base da Kaleidr.
  • Alterar style-id em um elemento já montado não tem efeito. Use handle.setStyle ou insira um novo elemento.
  • Não existe chave separada para Tile. A mesma chave publicável dos outros produtos Kaleidr serve para Tile.

Próximos passos​