Referência do Tile

product="tile" apresenta um mapa de base Kaleidr escolhido por ID de estilo. O SDK troca a tua chave publicável por uma sessão Tile e substitui o conteúdo do destino de montagem por um iframe que carrega https://map-embed.kaleidr.com/?style=<style>. O mapa é desenhado nesse iframe.

A sessão permite à Kaleidr verificar a chave, o respetivo escopo e a origem da página, contabilizar o carregamento do mapa e fornecer o mapa de base predefinido da organização. A sessão não é enviada para o iframe. O URL do iframe contém o ID do estilo e a câmara fornecida (camera, pitch, bearing): não contém a chave publicável nem o token de sessão, e o mapa no iframe não efetua chamadas com nenhum deles.

Chave	Uma chave publicável (kld_pk_live_…). Obrigatória.
Escopo	maps. As chaves novas incluem-no por predefinição.
Plano	Todos os planos, incluindo Free.
Apresentação	Um iframe de https://map-embed.kaleidr.com.
Contabilização	Um carregamento de mapa por sessão Tile.
CSP	script-src https://cdn.kaleidr.com, connect-src https://api.kaleidr.com, frame-src https://map-embed.kaleidr.com.

Para um guia passo a passo, consulta Utilizar um mapa de base Kaleidr.

Montagem

Com o elemento:

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

A partir de JavaScript:

const handle = Kaleidr.mount('#basemap', {
  product: 'tile',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-morning',
  center: [-0.1276, 51.5072],
  zoom: 11,
});

Opções

Opção de montagem	Atributo	Tipo	Predefinição	Obrigatório	Descrição
product	product	'tile'	nenhum	sim	Seleciona Tile.
publishableKey	publishable-key	cadeia de caracteres	nenhum	sim	Chave kld_pk_… com o escopo maps. Uma chave de servidor (kld_sk_…) é recusada pelo navegador antes de qualquer pedido.
styleId	style-id	cadeia de caracteres	mapa de base predefinido da organização, se existir	recomendado	ID da tabela abaixo ou URL https:// completo de um documento de estilo. Deve corresponder a ^[A-Za-z0-9._:/~-]{1,200}$.
center	center	[longitude, latitude]; atributo "longitude,latitude"	vista predefinida do estilo	não	Centro inicial.
zoom	zoom	número	vista predefinida do estilo	não	Zoom inicial; ignorado na montagem sem center.
pitch	pitch	número, graus	vista predefinida do estilo	não	Inclinação inicial.
bearing	bearing	número, graus	vista predefinida do estilo	não	Rotação inicial.
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	não	Destino da troca de sessão. Tem de incluir /inference-api. Não é necessário em produção.
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	não	Origem de carregamento do iframe; só a origem é utilizada. É o anfitrião da página do mapa, não dos dados.
base	base	URL	https://cdn.kaleidr.com	não	Origem de onde o SDK carrega tile.js. Só são aceites as origens indicadas em Substituição da base.
enabled	flag	booleano	nenhum	não	Controlo por montagem do mecanismo de ativação.

shareId, theme, map, mapTarget, contained e tileBase não têm efeito numa montagem Tile.

IDs de estilo

style-id	Aspeto
kaleidr-morning	Claro: fundo branco, água ciano e estradas brancas.
kaleidr-afternoon	Fundo de tom intermédio, vegetação verde e estradas cinzentas.
kaleidr-evening	Hora dourada: tons quentes de areia e azeitona.
kaleidr-night	Azul-marinho escuro e carvão, com autoestradas âmbar.
kaleidr-plain	Tela branca com limites e nomes dos locais. Os edifícios 3D surgem a partir do zoom 15.
kaleidr-editorial	Paleta da tarde sem etiquetas, adequada a mapas pequenos ou decorativos.

Regras:

• Os IDs são exatos e distinguem maiúsculas de minúsculas. Não existem aliases curtos.
• Sem styleId, o embed utiliza o mapa de base predefinido da organização, recebido com a sessão. Se não existir, o iframe apresenta "Couldn't find a map id in the URL.". Define styleId para não depender da configuração da conta.
• Um styleId explícito prevalece sempre sobre a predefinição da organização.
• Um ID inexistente resulta num iframe vazio e numa mensagem kaleidr-embed:error com o código maplibre_error.
• Um valor com um carácter não permitido impede a montagem. A consola apresenta [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.. Por isso, um URL de estilo não pode conter uma cadeia de consulta.

Câmara

A câmara inicial usa a vista predefinida do estilo, com cada campo fornecido a substituir o valor correspondente. Sem vista predefinida, o mapa abre sobre o mundo inteiro: centro [0, 20], zoom 2, sem inclinação nem rotação.

• Em center, a longitude vem primeiro: [-0.1276, 51.5072] corresponde a Londres.
• Na montagem, zoom só é utilizado juntamente com center.
• pitch e bearing são independentes de center.

Dimensões

• O iframe ocupa 100% da largura do destino de montagem, não tem contorno e apresenta cantos arredondados.
• A altura ocupa 100% do destino quando este já tem altura na montagem; caso contrário, fica fixa em 500 píxeis.
• A montagem substitui os elementos filhos do destino e define position:relative (se não houver posição inline) e overflow:hidden.
• <kaleidr-map> tem display:block por predefinição; por isso, height funciona. Define uma altura. Os exemplos também incluem display:block para versões do Safari anteriores à 16.4, nas quais o elemento permanece inline.

Controlador

Kaleidr.mount devolve o controlador de forma síncrona. Consulta a matriz do controlador para todos os produtos.

Membro	Em Tile
handle.product	'tile'
handle.setCamera(camera)	Move o mapa.
handle.setStyle(style)	Substitui o mapa de base no mesmo local.
handle.setTheme(theme)	Não suportado; apresenta um aviso e não faz nada.
handle.destroy()	Remove o iframe e interrompe as renovações da sessão.

setStyle(style)

handle.setStyle('kaleidr-night');

Aceita um ID ou URL completo de estilo, resolvido como styleId na montagem. O iframe não recarrega, a câmara mantém-se e não é contabilizado outro carregamento. Tile é o único produto que suporta setStyle.

setCamera(camera)

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

Campo	Tipo	Descrição
center	[number, number]	Longitude, latitude.
zoom	número	Nível de zoom. Ao contrário da montagem, aqui 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. Sem valor ou com 0, a mudança é imediata.

Todos os campos são opcionais. Os que omitires mantêm os valores atuais.

Momento das chamadas

Podes chamar setCamera e setStyle a qualquer momento após Kaleidr.mount devolver, até na linha seguinte. As chamadas feitas antes de o mapa no iframe estar pronto são guardadas e aplicadas por ordem quando ele estiver pronto. São guardadas as últimas 256 chamadas. Se o mapa não sinalizar prontidão dentro de uma espera limitada, normalmente 10 segundos após o iframe carregar, as chamadas são enviadas na mesma, com um aviso na consola. Não tens de esperar pela mensagem kaleidr-embed:ready. Para definir a vista e o estilo com que o mapa abre, prefere as opções de montagem: assim, o mapa começa diretamente nessa configuração.

Atributos do elemento depois da montagem

Num <kaleidr-map product="tile"> já montado, alterar center, zoom, pitch ou bearing move o mapa sem animação. Alterar style-id, publishable-key ou qualquer outro atributo não tem efeito.

Mensagens do iframe

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id é o ID ou URL de estilo fornecido. Com no_id é null, o iframe mostra "Couldn't find a map id in the URL." e não envia ready.

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

• ready é enviado uma vez quando o mapa é desenhado e não volta a ser enviado após setStyle.
• maplibre_error pode surgir várias vezes, antes ou depois de ready.
• O iframe utiliza loading="lazy", pelo que as mensagens só chegam quando está perto da área visível.
• Uma sessão recusada não gera mensagens, porque não é criado nenhum iframe. Consulta o erro na consola.
• O iframe publica outras mensagens cujo type começa por kaleidr-embed:. O SDK usa-as para ligar Chat ao mapa; não fazem parte do contrato público.

Sessões e contabilização

Em cada montagem Tile, o SDK envia

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

e recebe

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id identifica o mapa de base predefinido da organização e vale null se não existir.

Cada troca bem-sucedida com "product":"tile" contabiliza um carregamento de mapa para a organização. As trocas ocorrem:

Quando	Contagem
Na montagem	1
90 segundos antes de a sessão expirar, enquanto a montagem existir	1 de cada vez
Quando o separador volta a ficar visível e a sessão está a 90 segundos de expirar ou já expirou	1
Numa nova montagem após destroy(), ou ao reinserir um elemento removido	1

Notas:

• Uma renovação falhada é tentada novamente a cada 30 segundos, sem retirar o mapa já visível.
• Se a primeira troca falhar, a montagem falha e não é repetida automaticamente; monta novamente para tentar.
• destroy() interrompe as renovações.
• Movimentos da câmara, mudanças de estilo e interações do visitante nunca contam.

Uma troca de sessão Tile é recusada pela primeira das seguintes causas que se aplique:

Estado	detail	Causa
403	publishable_key_required	A chave não é publicável.
403	origin_required	O pedido não tinha origem.
403	origin_not_allowed	A origem da página não consta das origens permitidas da chave.
403	product_not_allowed	A chave está limitada a outros produtos.
403	tier_capability_not_allowed	O plano não permite o produto.
403	insufficient_scope	A chave não tem o escopo maps.
429	map_load_quota_exceeded	Os carregamentos de mapa da organização esgotaram-se.

Antes destas verificações, a troca devolve 404 sessions_disabled quando as sessões estão desativadas na plataforma, ou 503 sessions_not_configured perante uma falha da plataforma. Nenhuma situação é causada pela chave. Consulta todos os códigos em Erros.

Integração com Chat

Uma montagem Chat pode controlar um elemento Tile. Atribui um id ao elemento Tile e aponta para ele o atributo map-target do Chat (opção mapTarget):

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

Num mapa Tile, o assistente coloca pinos com pop-ups, enquadra locais com a câmara e desenha rotas, contornos de áreas como cidades e posições de veículos em tempo real. O guia está em Utilizar um mapa de base Kaleidr, a disposição em Temas e disposição, e as opções em Referência do Chat.

Mensagens da consola

Mensagem	Significado
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	O elemento não tem um product válido; não é montado.
[kaleidr:tile] kaleidr session exchange failed (<status>)	A troca foi recusada. A causa está na resposta do separador Rede: detail para 403 e map_load_quota_exceeded, ou error para 429 rate_limited.
Erro CORS para …/sdk/sessions, seguido de erro de obtenção [kaleidr:tile]	A chave é desconhecida ou revogada, ou a origem não é permitida. A resposta de uma origem recusada não tem cabeçalhos CORS e o navegador oculta-a do SDK.
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.	Foi passada uma chave de servidor; não é enviado qualquer pedido.
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId contém um carácter não permitido.
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount não encontrou o elemento do seletor.
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	Não foi possível carregar o bundle Tile.
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	Foi chamado um método não suportado pelo Tile.
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	A página usa uma versão antiga de tile.js em cache. Recarrega sem cache.

Não disponível

• Adicionar marcadores, camadas ou pop-ups próprios ao mapa.
• Eventos de cliques, movimentos de câmara ou seleções.
• Consultar a posição atual da câmara.
• Utilizar o mapa sem iframe.

Relacionado

• Utilizar um mapa de base Kaleidr
• O elemento <kaleidr-map>
• O carregador, kaleidr.js
• Quotas e limites de frequência