Referência do Viewer

product="viewer" apresenta um mapa publicado no Kaleidr Studio. O SDK substitui o conteúdo do destino de montagem por um iframe que carrega https://map-embed.kaleidr.com/embed/<id>. O mapa é desenhado dentro desse iframe.

Chave	Nenhuma. Não passes uma.
Plano	Todos os planos, incluindo Free.
Apresentação	Um iframe de https://map-embed.kaleidr.com.
Contabilização	Um carregamento de mapa por visualização, a cargo da organização proprietária.
CSP	script-src https://cdn.kaleidr.com e frame-src https://map-embed.kaleidr.com.

Para um guia, consulta Incorporar um mapa publicado.

Montagem

Com o elemento:

<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>

A partir de JavaScript:

const handle = Kaleidr.mount('#map', {
  product: 'viewer',
  shareId: 'YOUR_MAP_ID',
});

Sem SDK:

<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>

Barra de chat

layout="bar" transforma o Viewer numa barra de chat: um único campo de pergunta para a tua página, sem mapa até um visitante perguntar. Uma pergunta abre o mapa publicado, e o Kaleidr AI do mapa responde-lhe aí.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
             chat-title="Ask about the neighborhood"
             prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>

As respostas abrem num de dois sítios:

Definição	O que faz uma pergunta
Sem results-url (predefinição)	O mapa abre sobre a página, ocupando a janela, e faz a pergunta. O visitante fecha-o com o botão de fechar. Uma pergunta posterior vai para o mesmo mapa, pelo que a conversa continua.
results-url="/map"	O navegador vai para essa página com ?q=<question>. Um Viewer nessa página com prompt-param="q" faz a pergunta quando o mapa abre, se o visitante veio de uma página da mesma origem.

Uma página de resultados:

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

• Quem responde é o mapa. A pergunta vai para o painel Ask Kaleidr do próprio mapa, pelo que o mapa precisa do Control Tower ativado (Studio, Kaleidr AI), e aplicam-se as regras do Kaleidr AI num mapa publicado: o proprietário paga, e os domínios permitidos do mapa decidem onde responde. Num mapa sem Control Tower, o mapa abre e a pergunta não é feita.
• A barra não carrega nenhum mapa. O mapa carrega, e conta como carregamento de mapa, quando um visitante pergunta.
• A barra é desenhada numa shadow root própria, pelo que o CSS da tua página não lhe altera o estilo, e os seus estilos não precisam de permissão style-src. Tem a largura do elemento e a altura do seu conteúdo.
• As suas próprias etiquetas seguem lang, ou o idioma do navegador do visitante quando lang não está definido: inglês, espanhol, francês, alemão, português, japonês, coreano, chinês simplificado e tradicional, e árabe. O teu chat-title, placeholder e prompts aparecem tal como os escreves.
• prompt pré-preenche o campo, e handle.send() pergunta a partir do código. handle.send('Parks nearby') faz essa pergunta; handle.send() pergunta o que está no campo.

O construtor em template.kaleidr.com escreve os dois snippets para um mapa à tua escolha.

Layouts de locais

layout="locator" e layout="listings" mostram o mapa publicado ao lado de uma lista de uma coleção da Biblioteca de locais que o mapa desenha, com os filtros e os cartões da coleção.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
             filters="search|category|open_now"
             style="display:block; height:600px"></kaleidr-map>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
             filters="price|beds|baths"
             style="display:block; height:720px"></kaleidr-map>

Layout	A lista	Os pinos
locator	Locais ordenados por distância, com um campo de pesquisa, um botão Perto de mim, os filtros e uma contagem. Uma pesquisa que não corresponde a nenhum local da lista move o mapa para o local pesquisado.	A camada da coleção, com o estilo definido no Studio.
listings	Cartões com fotografia, em duas colunas numa moldura larga, ordenados por Distância, Preço: menor para maior ou Preço: maior para menor.	Etiquetas de preço.

• A lista fica ao lado do mapa numa moldura com 768 píxeis de largura ou mais, e abaixo disso numa folha sobre o mapa que o visitante arrasta para cima.
• A lista e o mapa mantêm-se sincronizados. Selecionar um local na lista move o mapa até ele e abre o seu cartão; selecionar um pino desloca a lista até ele. A lista, os pinos e a contagem mostram sempre os mesmos locais.
• A lista mostra 50 locais de cada vez, com Mostrar mais.
• Perto de mim pede a localização ao visitante. O iframe que o SDK cria permite-o; um iframe simples precisa de allow="geolocation".
• Num mapa que não desenha nenhuma coleção, ambos os layouts mostram só o mapa.

filters escolhe quais dos Filtros para visitantes da coleção mostrar, separados por |. Aparecem pela ordem da coleção, seja qual for a ordem em que os escreves, e um filtro que a coleção não oferece é ignorado. Sem filters, o layout mostra todos os filtros da coleção.

Filtro	Mostra	Corresponde a
search	Um campo de texto	Locais cujo nome, endereço ou categoria contém o texto.
category	Botões de categoria, até às 30 mais frequentes	Locais de qualquer categoria selecionada.
price	Mínimo e máximo	Locais com preço dentro do intervalo. Um local sem preço fica oculto assim que o intervalo é reduzido.
beds, baths	Qualquer, 1+, 2+, 3+, 4+	Locais com pelo menos esse número.
open_now	Um interruptor	Locais abertos neste momento, no seu próprio fuso horário. Os locais sem horário ficam ocultos enquanto está ativo.

Todos os filtros que um visitante define aplicam-se em conjunto.

card define quanto mostra o cartão de um local. auto, a predefinição, é o cartão desenhado no Studio. compact mostra apenas o título, o subtítulo e as ações, para uma moldura pequena.

As ações de local funcionam como a coleção as define. Rotas desenha o percurso no mapa e oferece o Apple Maps e o Google Maps; um Link abre num novo separador; Ligar abre uma ligação telefónica; uma ação de solicitação, como Schedule a Tour, abre o formulário de solicitação da empresa sobre o mapa.

Layout de guia

layout="guide" abre um mapa de estabelecimentos com o seu painel Ask Kaleidr ao lado: o guia do bairro de um hotel, ou o mapa da zona de um espaço. Lista uma coleção de Estabelecimentos (collection, ou então a primeira coleção de Estabelecimentos que o mapa desenha) e precisa do Control Tower ativado. Num mapa que não desenha nenhuma coleção de Estabelecimentos, o layout mostra apenas o mapa.

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

• O chat vem primeiro. Num frame com 769 píxeis de largura ou mais, o painel tem 400 píxeis de largura, à esquerda do mapa. Mais estreito, é uma folha sobre o mapa a 45% da altura, que o visitante arrasta até 85%. A nota de que as respostas são geradas por IA fica sob o campo.
• Os chips de categoria acima do campo são as oito categorias mais comuns da coleção. Um chip mostra os pinos dessa categoria e pergunta "Mostra-me categoria perto de âncora" no idioma do visitante. Plan My Day pergunta "Planeia o meu dia à volta de âncora".
• A âncora é o Pino de Referência do mapa, definido nas definições do mapa no Studio: um local de uma coleção que o mapa desenha, ou um ponto colocado no mapa, como o teu hotel. É desenhada como um pino próprio com o seu nome, e "perto" no guia significa perto dela. Um mapa sem âncora usa o seu centro.
• O plano do dia. Quando lhe pedem para planear um dia, o guia desenha um percurso que começa na âncora e visita primeiro locais das tuas próprias coleções e depois dados de locais próprios da Kaleidr, e mostra-o como um cartão de paragens com nome e as suas horas, no idioma do visitante.
• Os cartões dos estabelecimentos mostram o cartão criado no Studio, com Staff Pick nos locais que marcares, e por baixo os cartões das tuas Conexões. O conteúdo conectado aparece só nos cartões, nunca nas respostas do guia.
• Solicitações. A ação Reserve de um estabelecimento abre o formulário de solicitação da empresa.

O guia no fluxo do chat

O viewer indica à Kaleidr AI do mapa qual layout mostra. Um cliente de POST /chat/control/stream vê dois campos que pertencem ao guia:

Campo	Onde	Forma
layout	O corpo do pedido	"guide" enquanto um layout de guia é mostrado; omitido caso contrário, o que corresponde a um turno de mapa comum. No máximo 16 caracteres, ou o pedido é recusado com 422 invalid_layout.
itinerary	Um evento do fluxo, repetido no evento end	{ title, stops: [{ name, time?, note? }] }: o título do plano do dia e de 1 a 12 paragens com nome, já no idioma do visitante. Uma note aparece só para os teus próprios locais.

Um cliente que não mostra planos do dia pode ignorar o evento.

Layout ao vivo

layout="live" mostra onde estão agora os teus veículos e onde param hoje: o percurso de um food truck, um shuttle, um serviço móvel. Lê duas coleções: uma coleção de Veículos, cujas posições vêm do rastreamento ao vivo, e uma coleção de Paradas com o horário.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
             collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
             style="display:block; height:640px"></kaleidr-map>

Opção	Predefinição	Lê
collection	A primeira coleção de Veículos que o mapa desenha	Os veículos mostrados ao vivo.
stops	A primeira coleção de Paradas que o mapa desenha	As paradas e as suas janelas de atendimento.

Num mapa que não desenha nenhuma das duas, o layout mostra apenas o mapa. O painel fica ao lado do mapa num frame com 769 píxeis de largura ou mais, e é uma folha sobre o mapa abaixo disso.

• Uma etiqueta Ao vivo encabeça o painel, ou Fora de serviço agora quando nenhum veículo está de turno.
• Uma linha por veículo mostrado: o seu nome; Em movimento, Parado, Em e a parada, ou Visto há 5 min quando o último relatório é mais antigo do que o Marcar como Desatualizado Após da frota; e Próxima parada com Cerca de 12 min e uma etiqueta Estimativa.
• Rota de hoje: as paradas de hoje pela ordem das suas janelas, cada uma com a sua janela, o veículo que a atende e um selo.
• Quanto tempo até mim? pede a localização do visitante, ou usa uma posição aproximada da cidade se ele recusar, e mostra quanto tempo os veículos mostrados levariam a chegar até ele. A localização serve apenas para essa estimativa e nunca é guardada.
• Selecionar um veículo segue-o até o visitante mover o mapa. Selecionar uma parada abre o seu cartão, com as janelas de hoje ou a próxima data de atendimento.

Selo	Quando
Aqui agora	O veículo fez check-in na parada.
Fechado hoje	O motorista marcou o veículo como fechado por hoje.
Aberto agora	Uma janela da parada contém este momento.
A seguir: 11:00–14:00	A parada tem uma janela mais tarde hoje.
Hoje não	A parada não tem nenhuma janela hoje. O seu cartão indica a próxima data de atendimento nos próximos 14 dias.

O que o visitante vê move-se com suavidade e nunca adivinha. Um veículo desliza de uma posição comunicada para a seguinte e nunca se adianta ao último relatório. As posições atualizam a cada 10 segundos, salvo se o autor do mapa escolheu outro intervalo (de 5 a 60 segundos), e fazem pausa enquanto a página está oculta. Os estados de hoje e as estimativas atualizam a cada minuto. Uma atualização falhada mantém a última imagem.

Só são mostrados os veículos de turno, com a precisão que a precisão pública da frota permite. Um veículo cujo turno termina desaparece na atualização seguinte.

Cada tempo é uma estimativa. É calculado a partir da distância por estrada e de velocidades típicas, e não inclui o trânsito. É arredondado ao minuto para cima e mostrado como Cerca de 12 min ou Cerca de 1 h 20 min, nunca como hora de chegada. Sem percurso por estrada entre os dois, a linha diz Sem estimativa. Os percursos por estrada são construídos com dados do OpenStreetMap, © colaboradores do OpenStreetMap, sob a ODbL.

Request Pickup é a ação de solicitação da coleção de Paradas. Quando o seu autor ativou Deixar os visitantes escolher a recolha e o destino, o visitante define primeiro uma recolha, a própria parada salvo se a mudar, e um destino, cada um pesquisando um endereço ou tocando no mapa, e depois preenche o formulário de solicitação. Ambos os pontos seguem com a solicitação.

As etiquetas do painel seguem o idioma do viewer, nos mesmos dez idiomas da barra de chat.

Opções

Opção de montagem	Atributo	Tipo	Predefinição	Obrigatório	Descrição
product	product	'viewer'	nenhum	sim	Seleciona Viewer.
shareId	share-id	cadeia de caracteres	nenhum	sim	ID do mapa publicado, obtido do código de incorporação do Studio. Tem de corresponder a ^[A-Za-z0-9._~-]{1,100}$.
mapId	map-id	cadeia de caracteres	nenhum	não	Alias de shareId, utilizado quando shareId não existe.
center	center	[longitude, latitude]; atributo "longitude,latitude"	vista guardada	não	Centro inicial.
zoom	zoom	número	vista guardada	não	Zoom inicial; ignorado na montagem sem center.
pitch	pitch	número, graus	vista guardada	não	Inclinação inicial.
bearing	bearing	número, graus	vista guardada	não	Rotação inicial.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	não	Origem do iframe. Só se utiliza a origem. Não é necessário em produção.
base	base	URL	https://cdn.kaleidr.com	não	Origem de onde o SDK carrega viewer.js. Só se utiliza a origem e apenas são aceites as da Substituição da base.
enabled	flag	booleano	nenhum	não	Controlo por montagem do mecanismo de ativação.
prompt	prompt	cadeia de caracteres	nenhum	não	Pergunta a fazer ao Kaleidr AI do mapa quando o mapa abre. Numa barra de chat, o texto pré-preenchido do campo. No máximo 500 caracteres.
promptParam	prompt-param	cadeia de caracteres	nenhum	não	Lê prompt deste parâmetro de consulta do URL da própria página: q na página de resultados de uma barra de chat. Só é lido quando o visitante veio de uma página da mesma origem, para que uma ligação de outro sítio não possa fazer o seu mapa perguntar nada.
layout	layout	'map', 'bar', 'locator', 'listings', 'guide' ou 'live'	'map'	não	bar monta a barra de chat. locator e listings mostram o mapa ao lado de uma lista de uma coleção: consulta Layouts de locais. guide abre o chat ao lado de um mapa de estabelecimentos: consulta Layout de guia. live mostra os veículos e as paradas de hoje: consulta Layout ao vivo.
collection	collection	string	a primeira coleção do tipo do layout que o mapa desenha	não	Localizador, anúncios e guia: o identificador da coleção a listar. Ao vivo: o identificador da coleção de Veículos.
stops	stops	string	a primeira coleção de Paradas que o mapa desenha	não	Ao vivo: o identificador da coleção de Paradas.
filters	filters	matriz de cadeias de caracteres; o atributo separa-as com |	todos os filtros da coleção	não	Localizador e anúncios: quais de search, category, price, beds, baths e open_now mostrar, entre os que a coleção oferece.
card	card	'auto' ou 'compact'	'auto'	não	Os cartões compact mostram apenas o título, o subtítulo e as ações.
prompts	prompts	matriz de cadeias de caracteres; o atributo separa-as com |	nenhum	não	Barra de chat: perguntas de exemplo, apresentadas como botões que as fazem.
title	chat-title	cadeia de caracteres	nenhum	não	Barra de chat: a etiqueta por cima do campo.
placeholder	placeholder	cadeia de caracteres	«Ask about this map», no idioma da barra	não	Barra de chat: o texto de ajuda do campo.
accent	accent	cor CSS	#2da84a	não	Barra de chat: a cor do botão de envio, do ícone e do anel de foco.
theme	theme	'light', 'dark' ou 'auto'	'light'	não	Barra de chat: as suas cores. auto segue a definição do sistema do visitante.
lang	lang	etiqueta de idioma	idioma do navegador do visitante	não	Barra de chat: o idioma das suas próprias etiquetas.
resultsUrl	results-url	URL	nenhum	não	Barra de chat: envia os visitantes para esta página com ?q=<question> em vez de abrir o mapa sobre a página.

publishableKey, styleId, map, mapTarget e contained não afetam uma montagem Viewer. Fornecer uma chave é contraproducente: o SDK troca-a por uma sessão que o Viewer nunca usa e, se a troca for recusada, o mapa nem aparece.

O identificador

shareId aceita os dois tipos de ID gerados pelo Studio para um mapa:

• ID do mapa publicado. É o ID no código da página Publicar e incorporar e no separador Incorporar da janela Partilhar; ambos apresentam o mesmo.
• ID de uma ligação partilhada. É o ID de 16 caracteres no fim do URL no separador Partilhar ligação da janela Partilhar.

O ID do mapa publicado mostra o mapa tal como está guardado nesse momento. O ID da ligação mostra a cópia do mapa criada quando a ligação foi gerada. O Kaleidr AI aceita qualquer um dos IDs: numa ligação partilhada, segue os interruptores do Kaleidr AI da cópia, enquanto o mapa estiver publicado e nos domínios permitidos atuais do mapa; consulta Chat num mapa publicado.

Um ID vazio ou inválido não lança uma exceção. O SDK escreve

[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.

e não apresenta nada. Kaleidr.mount devolve mesmo assim um controlador, cujos métodos não produzem efeitos.

URL de iframe simples

https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>

Parâmetro de consulta	Valor	Efeito
camera	longitude,latitude ou longitude,latitude,zoom	Centro inicial e, opcionalmente, zoom.
pitch	número, graus	Inclinação inicial.
bearing	número, graus	Rotação inicial.
q	texto, no máximo 500 caracteres	Pergunta a fazer ao Kaleidr AI do mapa quando o mapa abre. Só é feita quando o Viewer está incorporado numa página, e ignorada num mapa sem Control Tower.
layout	locator, listings, guide ou live	Um layout de locais, o guia ou o layout ao vivo. Qualquer outro valor mostra o mapa.
collection	um identificador de coleção	A coleção que o layout lista; em live, a coleção de Veículos.
stops	um identificador de coleção	Em live, a coleção de Paradas.
filters	nomes de filtros separados por |	Os filtros que o layout mostra.
card	auto ou compact	Quanto mostra o cartão de um local.

O SDK constrói o mesmo URL a partir das opções de câmara, de prompt, layout, collection, stops, filters e card.

Câmara

A câmara inicial é composta pelas fontes seguintes. Cada fonte posterior substitui apenas os campos que fornece.

1. A vista predefinida do mapa de base.
2. A vista guardada pelo autor no Studio. O autor pode guardar vistas diferentes para larguras de computador, tablet e telemóvel, sendo selecionada a correspondente à largura do iframe. Também pode configurar o mapa para enquadrar o conteúdo, ajustando-o ao espaço disponível.
3. A câmara fornecida por ti (center, zoom, pitch, bearing nas opções ou atributos, ou camera, pitch e bearing no URL de iframe).

A câmara fornecida pela página prevalece sobre a vista do autor, mesmo que este tenha configurado vistas por largura ou enquadramento de conteúdo. Os campos que não forneces conservam os valores do autor.

Um mapa com vistas por largura ou enquadramento de conteúdo ajusta-se novamente quando o iframe muda de tamanho, até que o visitante mova o mapa. Uma câmara fornecida pela página desativa também esse ajuste automático: após passar uma câmara na abertura ou chamar setCamera, o mapa deixa de reenquadrar ao redimensionar. setCamera só altera os campos especificados e mantém os restantes.

Em center, a longitude vem primeiro: [-0.1276, 51.5072] corresponde a Londres.

Dimensões

• O iframe ocupa 100% da largura do destino, não tem contorno e apresenta cantos arredondados.
• A altura ocupa 100% do destino quando este tem altura na montagem; caso contrário, é fixa em 500 píxeis.
• A montagem substitui os filhos do destino e define position:relative (se não existir posição inline) e overflow:hidden.
• <kaleidr-map> é display:block por predefinição, pelo que height se aplica. Define uma altura. Os exemplos também incluem display:block para Safari anterior à versão 16.4, no qual o elemento se mantém inline.

Controlador

Kaleidr.mount devolve o controlador de forma síncrona. Consulta a matriz do controlador dos quatro produtos.

Membro	No Viewer
handle.product	'viewer'
handle.setCamera(camera)	Move o mapa.
handle.setTheme(theme)	Não suportado; apresenta um aviso e nada faz.
handle.setStyle(style)	Não suportado; apresenta um aviso e nada faz.
handle.send(text)	Pergunta ao Kaleidr AI do mapa, como se o visitante tivesse escrito text. Numa barra de chat, send() sem texto pergunta o que está no campo. Uma pergunta enviada enquanto outra está a ser respondida espera por ela, e uma mais recente substitui qualquer uma ainda em espera.
handle.setFilters(filters)	Define os filtros para visitantes de um layout de locais. Não faz nada no layout map.
handle.showVehiclesLayer(layer)	Desenha ou move a tua própria camada de veículos.
handle.clearVehiclesLayer()	Remove a tua camada de veículos.
handle.destroy()	Remove o iframe e deixa de escutar mensagens.

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 800,             // milliseconds
});

Campo	Tipo	Descrição
center	[number, number]	Longitude, latitude.
zoom	número	Nível de zoom. Ao contrário da montagem, zoom funciona sem center.
pitch	número	Inclinação em graus.
bearing	número	Rotação em graus.
duration	número	Duração da animação em milissegundos. Omitido ou 0, salta de imediato.

Todos os campos são opcionais. Os omitidos conservam os valores atuais.

Podes chamar setCamera logo após o retorno de Kaleidr.mount, incluindo na linha seguinte. Uma chamada feita antes de o mapa no iframe estar pronto é guardada e aplicada pela ordem correta quando o mapa comunica que está pronto. São guardadas as últimas 256 chamadas. Se não houver confirmação após uma espera limitada, normalmente 10 segundos depois de o iframe carregar, as chamadas são enviadas na mesma, com um aviso na consola. Não precisas de esperar por kaleidr-embed:ready. Para escolher a vista inicial, é melhor usar opções de montagem: o mapa abre diretamente nessa vista.

Não existe método para ler a câmara de volta.

setFilters(filters)

handle.setFilters({
  q: 'downtown',
  category: ['Outlet', 'Flagship'],
  price: [250000, null],     // [min, max]; null leaves that end open
  beds: 2,
  baths: 1,
  open_now: true,
});

Campo	Tipo	Define
q	cadeia de caracteres	O campo de pesquisa.
category	matriz de cadeias de caracteres	As categorias selecionadas.
price	[number | null, number | null]	O preço mínimo e máximo.
beds	número	O número mínimo de quartos.
baths	número	O número mínimo de casas de banho.
open_now	booleano	O interruptor Aberto agora.

Todos os campos são opcionais. O visitante vê os filtros mudar como se os tivesse definido, e pode voltar a alterá-los. Um campo de um filtro que o layout não mostra, e qualquer outro campo, é ignorado. Tal como em setCamera, uma chamada feita antes de o mapa estar pronto é guardada e aplicada quando estiver. Um bundle do viewer anterior aos layouts de locais não tem setFilters; nesse caso a chamada não faz nada e regista um aviso na consola de que a montagem não o expõe.

showVehiclesLayer(layer)

Desenha no mapa incorporado veículos que a tua página já acompanha, como posições do teu próprio sistema de despacho. Os dados vão da tua página para o iframe e para mais nenhum lado: nada passa pelos servidores da Kaleidr, e o viewer não descarrega nada para esta camada.

handle.showVehiclesLayer({
  layer_id: 'shuttles',
  vehicles: [
    { id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
    { id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
  ],
});

// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });

handle.clearVehiclesLayer();

Campo	Tipo	Descrição
layer_id	string	Dá nome à camada. O mesmo id outra vez atualiza-a no lugar.
vehicles	array, no máximo 2.000	Os veículos a desenhar.
vehicles[].id	string	Obrigatório. Identifica um veículo de uma chamada para a seguinte.
vehicles[].lat, vehicles[].lng	number	Obrigatório. A posição do veículo.
vehicles[].name	string	A etiqueta desenhada ao lado do veículo.
vehicles[].color	cor hexadecimal CSS	A cor do veículo. Sem ela, é desenhado a cinzento.
vehicles[].bearing	number, graus	A direção para onde o veículo está virado.
attribution	string	Um crédito para os teus dados, mostrado no cartão de um veículo ao tocá-lo.

• O mesmo layer_id atualiza no lugar. Cada veículo desliza de onde está desenhado até ao seu novo ponto, ao longo do tempo desde a tua chamada anterior, no máximo 30 segundos. Um veículo ausente da nova chamada desaparece.
• Um layer_id novo, ou nenhum, substitui a camada. O mapa mostra uma camada de veículos de cada vez.
• Um veículo sem id, ou sem lat e lng finitos, é descartado, tal como todos os veículos a partir do 2.001.º.
• Para mover os veículos, chama de novo. O viewer nunca vai buscar dados para esta camada.
• Tal como em setCamera, uma chamada feita antes de o mapa estar pronto é guardada e aplicada quando estiver.

Os tipos LiveLayerData e LiveVehicle do SDK declaram a forma da camada. showVehiclesLayer e clearVehiclesLayer são métodos do viewer: em chat, editor e tile registam um aviso e não fazem nada. Um bundle do viewer anterior a esta camada não tem nenhum dos dois; nesse caso a chamada não faz nada e regista um aviso na consola de que a montagem não o expõe.

Atributos do elemento após a montagem

Num <kaleidr-map product="viewer"> já montado, alterar center, zoom, pitch ou bearing move o mapa sem animação. Alterar share-id ou qualquer outro atributo não faz nada. Para mostrar outro mapa, remove o elemento e insere um novo.

Mensagens do iframe

O iframe envia mensagens para a página que o incorpora. Duas são sinais públicos de «carregado» e «falhou»:

// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }

// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== iframe.contentWindow) return; // which embed sent it
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

Com o SDK, iframe é o primeiro <iframe> dentro do destino: target.querySelector('iframe').

Códigos de erro

code	Terminal	Significado
no_id	sim	O URL do iframe não contém ID do mapa. id é null.
not_found	sim	Não existe mapa publicado nem ligação partilhada com esse ID: o mapa nunca foi publicado ou foi retirado de publicação, o mapa da ligação partilhada foi excluído ou a Kaleidr removeu a ligação, ou o ID está mal escrito.
domain_not_allowed	sim	O mapa restringe domínios e a página não está autorizada, ou não enviou referente.
map_loads_exhausted	sim	A organização proprietária esgotou os carregamentos de mapa do período.
fetch_failed	sim	Não foi possível obter o mapa.
maplibre_error	não	O mapa iniciou, mas algum elemento não foi desenhado. Pode chegar mais de uma vez antes ou depois de ready.

Após um código terminal, o iframe mostra uma breve mensagem no lugar do mapa e não envia ready.

Regras

• ready é enviado uma vez por carregamento, depois de o mapa ser desenhado e a vista ser contada.
• O SDK cria o iframe com loading="lazy", pelo que as mensagens só chegam quando se aproxima da área visível.
• O iframe envia outras mensagens cujo type começa por kaleidr-embed:. O SDK usa-as para ligar Chat ao mapa. Não são um contrato público e podem mudar; não construas lógica dependente delas.
• O iframe só aceita mensagens de controlo, como movimentos de câmara de setCamera, da página que o incorpora diretamente. Ignora mensagens de outras janelas ou frames; chama setCamera a partir da página que contém o iframe.
• Nem o SDK nem o elemento emitem eventos DOM ou disponibilizam uma promessa ready.

Mensagens que o visitante vê

Aparecem dentro do iframe, no lugar do mapa:

Texto	Código
"Loading map…"	nenhum: o mapa está a carregar
"Couldn't find a map id in the URL."	no_id
"This map isn't available — it may have been unpublished, paused, or the link is incorrect."	not_found
"This map isn't allowed to render on this site. Please contact the map owner."	domain_not_allowed
"This map has reached its map load limit. It will be available again when the owner's allowance resets."	map_loads_exhausted
"Could not load the map. Please try again in a moment."	fetch_failed
"Unexpected error loading the map."	nenhum: falha inesperada no arranque

Dados carregados

Um mapa publicado desenha os conjuntos de dados e sobreposições de imagem que o autor adicionou no painel Dados do Studio. O iframe carrega-os diretamente, sem opções, atributos ou chaves, e os dados nunca passam pela tua página.

Comportamento	Detalhe
O que aparece	Todos os conjuntos de dados e sobreposições de imagem incluídos no mapa publicado, como camadas configuradas pelo autor.
Quem os pode ler	Qualquer pessoa que consiga abrir o mapa. Domínios permitidos não tornam os dados confidenciais.
O que recebe o navegador	Cada conjunto de dados por inteiro, com todas as colunas. Um conjunto grande demora mais a aparecer.
Se um conjunto não carregar	O resto do mapa é desenhado sem essa camada.
Eliminar um conjunto no painel Dados	É apagado e deixa de ser servido no mapa publicado e em todas as ligações partilhadas que o mostravam. Um navegador que já o carregou mantém-no; uma ligação de transferência emitida pode funcionar até uma hora.
Retirar a publicação do mapa	O ID publicado deixa de servir o mapa e os seus dados. O iframe mostra not_found. Publicar novamente recupera o mesmo ID.
Ligações partilhadas	A ligação é uma cópia do desenho no momento em que foi criada e continua a mostrar o mapa após a retirada de publicação, sem Kaleidr AI até o mapa ser publicado novamente. O Studio não permite apagar nem pausar ligações; funcionam até o mapa ser eliminado ou Kaleidr retirar a ligação a pedido do proprietário. Consulta Ligações partilhadas.

Dados carregados num mapa publicado explica estes casos.

Domínios permitidos

O proprietário pode restringir os sites que apresentam o mapa no Studio, em Partilhar, Incorporar, Domínios específicos.

• Um domínio permitido inclui os seus subdomínios.
• A verificação compara a lista com o nome do anfitrião do referente enviado pelo navegador para o iframe. Sem referente, a verificação falha.
• Uma falha mostra a mensagem «não permitido» e publica domain_not_allowed.
• Uma vista que falha esta verificação não conta como carregamento de mapa.

Contabilização

• Cada visualização conta um carregamento de mapa para a organização proprietária.
• O mesmo visitante que volta a ver o mesmo mapa num período de 24 horas não é contado outra vez.
• As visualizações nos próprios sites da Kaleidr não contam.
• Quando a quota se esgota, o iframe mostra a mensagem de limite até ser reposta. Consulta Quotas e limites de frequência.

Mensagens da consola

Mensagem	Significado
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	O elemento não tem um product válido e não é montado.
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$.	O ID está vazio ou malformado.
[kaleidr:viewer] mount target not found: <selector>	Kaleidr.mount não encontrou o elemento do seletor.
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js	Não foi possível carregar o pacote Viewer devido a falha de rede, bloqueador ou política script-src.
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. …	Foi chamado um método não suportado pelo Viewer.

Não disponível

• Eventos de cliques, movimentos de câmara ou seleções, incluindo cartões e ações de local.
• Ler a câmara, as camadas ou os dados do mapa.
• Adicionar marcadores ou camadas próprias ao mapa incorporado, exceto uma camada de veículos.
• Alterar o mapa de base ou o tema a partir do embed.

Relacionado

• Incorporar um mapa publicado
• O elemento <kaleidr-map>
• O carregador, kaleidr.js
• Chat num mapa publicado