Versionamento da CDN

O SDK é distribuído em cinco ficheiros sob um caminho versionado. A sua página referencia o primeiro, que carrega os outros quando um produto é montado.

https://cdn.kaleidr.com/embed/v1/kaleidr.js   the loader: window.Kaleidr and <kaleidr-map>
https://cdn.kaleidr.com/embed/v1/chat.js      the chat panel
https://cdn.kaleidr.com/embed/v1/viewer.js    the viewer's iframe loader
https://cdn.kaleidr.com/embed/v1/tile.js      the tile iframe loader
https://cdn.kaleidr.com/embed/v1/editor.js    the editor

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

O pacote de um produto é pedido na primeira montagem desse produto numa página, no máximo uma vez por página. Uma página que só mostra Viewer nunca descarrega chat.js nem editor.js.

O que significa v1

v1 identifica um contrato, não uma compilação.

• Há um ficheiro em cada URL, que é substituído no mesmo endereço em cada lançamento.
• Não existem versões de correção nem caminhos com hashes de conteúdo. Não pode fixar /embed/v1.2.3/kaleidr.js, pois esse caminho não existe.
• Correções e funcionalidades retrocompatíveis são publicadas em /embed/v1/ e chegam à sua página sem qualquer alteração.

Kaleidr.version é uma cadeia de diagnóstico, não o identificador de uma compilação que possa pedir.

O que permanece estável em v1

Estável	Significado
Os cinco URLs	Continuam disponíveis.
window.Kaleidr	mount, init, enable e version mantêm o comportamento documentado.
Opções de montagem e atributos de elementos	Uma opção documentada mantém o nome e o significado.
O handle	Todos os handles têm setCamera, setTheme, setStyle e destroy. Um método não suportado por um produto regista um aviso e não faz nada; não lança exceção nem é removido.
As duas mensagens de iframe	kaleidr-embed:ready e kaleidr-embed:error mantêm os campos documentados.

O que pode mudar dentro de v1:

• Adições. Podem surgir novas opções, atributos, métodos do handle, campos de mensagem, códigos de erro e eventos de fluxo. Escreva código que ignore aquilo que não conhece: um campo de mensagem, um code ou um evento desconhecido.
• Aparência. O aspeto do painel de chat, do editor e dos controlos de mapa pode mudar.
• Comportamento não documentado. Tudo o que estas páginas não descrevem, incluindo outras mensagens kaleidr-embed: entre o SDK e os iframes, as variáveis globais definidas pelos pacotes e o texto exato das mensagens da consola.

A API HTTP segue a mesma regra em /inference-api/b2b/v1/: v2 só surge com uma alteração incompatível. As novidades constam no registo de alterações.

Como é lançada uma alteração incompatível

Uma alteração que quebraria uma integração v1 funcional não é publicada em /embed/v1/. Surge como uma nova versão principal em paralelo com a anterior:

https://cdn.kaleidr.com/embed/v2/kaleidr.js
https://cdn.kaleidr.com/embed/v2/<product>.js

A sua etiqueta de script v1 continua a carregar ficheiros v1. Quando estiver pronto e depois de ler as alterações, mude o caminho da etiqueta para a nova versão principal. O carregador pede os pacotes de produto da sua própria versão principal.

Armazenamento em cache

Cada ficheiro é servido com

Cache-Control: public, max-age=300

e a cópia na CDN é substituída em cada lançamento.

Pergunta	Resposta
Quanto tempo demora uma versão a chegar a um visitante?	Cerca de cinco minutos. Um navegador que obteve o ficheiro anterior nos últimos cinco minutos continua a usá-lo até a cópia expirar.
O visitante descarrega o SDK de novo em cada página?	Não. Durante cinco minutos após o carregamento, o navegador usa a cópia em cache; depois volta a consultar a CDN.
Posso manter os ficheiros em cache durante mais tempo?	Não. Um proxy, service worker ou etapa de compilação que guarde a cópia por mais tempo servirá código desatualizado após um lançamento.
Posso adicionar integridade de sub-recursos (integrity="sha384-…")?	Não. O hash muda em cada versão e o navegador rejeita um script com hash diferente. As incorporações deixariam de carregar no lançamento seguinte.
Posso copiar kaleidr.js para o meu próprio pacote?	Não, pelo mesmo motivo. Referencie o URL.

Se tiver um service worker que guarda scripts de outras origens, exclua https://cdn.kaleidr.com de regras de prioridade à cache ou utilize uma estratégia de revalidação.

O carregador e os pacotes são lançados separadamente

Os cinco ficheiros são lançados de forma independente. Por pouco tempo, uma página pode usar um kaleidr.js novo com um pacote antigo da cache do navegador, ou o contrário. O SDK está preparado para isso:

• O carregador encaminha opções para o pacote e aceita que ele não reconheça uma opção recente.

• Se chamar um método de handle suportado pelo produto mas ainda ausente do pacote em cache, a chamada não produz efeito e a consola indica-o:

  [kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …

  Recarregar sem usar cache obtém o pacote atual. A situação resolve-se sozinha quando a cópia em cache expira.

As páginas internas dos iframes Viewer e Tile são servidas por https://map-embed.kaleidr.com e lançadas separadamente. A cache do SDK na sua página não as afeta.

Alojamento próprio

Pode servir os cinco ficheiros a partir da sua própria origem, por exemplo para que todos os scripts sejam da mesma entidade. Considere a desvantagem: uma cópia alojada por si deixa de receber correções automáticas. A API e as páginas dos iframes continuam a evoluir do lado do Kaleidr, pelo que uma cópia não atualizada fica desfasada.

Para alojar os ficheiros:

1. Copie os cinco ficheiros para https://your-origin/embed/v1/. O caminho é fixo; só a origem pode mudar.

2. Indique ao carregador onde estão os pacotes antes de ele executar:

   <script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script>
   <script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>

   ou, em cada montagem, pela opção base ou pelo atributo base.

3. Atualize as cópias regularmente e sirva-as com uma duração curta de cache, como faz o Kaleidr.

Origens aceites ao substituir a base

O carregador não descarrega pacotes de qualquer origem. Uma base personalizada (variável global da página, opção base ou atributo base) só é respeitada se a sua origem for:

• a CDN do Kaleidr (https://cdn.kaleidr.com);
• a origem de onde o próprio kaleidr.js foi carregado; ou
• a origem da página.

O alojamento próprio funciona quando o carregador e os pacotes são servidos da mesma origem. É o esquema do passo 2: kaleidr.js vem de https://cdn.example.com, pelo que https://cdn.example.com é aceite como base. Os pacotes servidos da origem da página também são aceites.

Qualquer outro valor é ignorado, incluindo outro anfitrião kaleidr.com. A incorporação continua a montar, mas os pacotes vêm de https://cdn.kaleidr.com, e a consola mostra:

[kaleidr] base "https://other.example.net" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.

Duas configurações não são permitidas:

• kaleidr.js carregado de https://cdn.kaleidr.com com uma base que aponta para uma terceira origem. Carregue também o carregador dessa origem.
• O carregador numa das suas origens e os pacotes noutra, sem que nenhuma seja a origem da página. Sirva os cinco ficheiros da mesma origem.

Se o aviso surgir numa página cuja Política de Segurança de Conteúdo permite apenas a sua origem para scripts, o pedido a https://cdn.kaleidr.com será bloqueado e nada aparece. Corrija a base, não a política.

O que o alojamento próprio altera ou não:

• Não basta alojar kaleidr.js. Sem substituir a base, o carregador continua a obter pacotes de https://cdn.kaleidr.com.
• Só a origem de base é usada. Qualquer caminho é descartado e os pacotes são pedidos em /embed/v1/ nessa origem.
• window.__KALEIDR_EMBED_BASE__ tem de ser uma cadeia de texto; outros valores são ignorados.
• O alojamento próprio só muda os scripts. A troca de sessão continua em https://api.kaleidr.com, os iframes Viewer e Tile em https://map-embed.kaleidr.com e o mapa base do Editor em https://tile.kaleidr.com. A sua Política de Segurança de Conteúdo deve continuar a permiti-los.

Páginas relacionadas

• kaleidr.js, o carregador
• Política de Segurança de Conteúdo
• Registo de alterações
• Lista de verificação de produção