Idioma
Português

Links diretos

Alguns lugares conseguem exibir um iframe, mas não executam o seu JavaScript: uma página do SharePoint, uma macro do Confluence, um link em um e-mail. Nesses casos, a URL do mapa pode levar o estado em que ele deve abrir. Nenhum SDK é envolvido.

<iframe src="https://embed.iconmap.ai/v/pub_...?bookmark=bm-north&f.region=EMEA&lang=de"
        style="width: 100%; height: 600px; border: 0"></iframe>
Na URL Efeito
?bookmark=<id> Abre em um dos indicadores do autor
?f.<name>=<value> Define um filtro declarado. Repita para vários filtros
?lang=<code> Idioma do leitor, por exemplo fr ou de-DE
#s=<scene> Restaura uma cena capturada inteira: câmera, visibilidade, segmentações, filtros, seleção, mapa base

Quando vários estão presentes, eles são aplicados nessa ordem, então a cena tem a palavra final.

Valores de filtro

Um valor simples é tratado como texto. Qualquer outro é escrito como JSON e codificado para URL:

?f.region=EMEA
?f.region=%5B%22EMEA%22%2C%22APAC%22%5D                         ["EMEA","APAC"]
?f.period=%7B%22operator%22%3A%22inLast%22%2C%22count%22%3A30%2C%22unit%22%3A%22days%22%7D

Um nome que o autor não declarou é ignorado, exatamente como seria rejeitado pela API: um link nunca consegue filtrar por uma coluna que o autor não ofereceu.

Por que a cena fica no fragmento

Tudo o que vem depois de # permanece no navegador: não é enviado ao servidor, portanto nunca aparece em logs de acesso, proxies ou ferramentas de análise. Uma cena pode conter uma seleção e valores de filtro, o que já é motivo suficiente para mantê-la fora deles.

Na caixa de diálogo de publicação

Depois de publicar, a caixa de diálogo oferece Copy link to this view ao lado da URL de incorporação. Esse recurso captura a câmera atual do editor, a visibilidade das camadas e as seleções das segmentações como uma cena e copia um link que abre o mapa publicado exatamente ali.

Na sua página

const { sceneToUrl } = IconMapEmbed;

const scene = await map.captureScene();

const link = sceneToUrl("https://embed.iconmap.ai/v/pub_...", {
  scene,
  bookmarkId: "bm-north",
  filters: { region: ["EMEA"] },
  language: "de",
});

Todas as partes são opcionais. deepLinkFromUrl(url) faz o inverso, se você quiser ler um link de volta:

const { deepLinkFromUrl } = IconMapEmbed;
const { scene, bookmarkId, filters, language } = deepLinkFromUrl(location.href);

Manualmente

Uma cena é um JSON codificado em base64url, então um link pode ser produzido por qualquer coisa capaz de fazer isso: um servidor, um relatório, um script:

const scene = { v: 1, camera: { center: [-3.18, 51.48], zoom: 12, bearing: 0, pitch: 0 } };
const s = btoa(JSON.stringify(scene)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const link = `https://embed.iconmap.ai/v/pub_...#s=${s}`;

v e camera são obrigatórios; todo o resto em uma cena é opcional.

Bom saber

  • Os links sobrevivem a uma nova publicação das mesmas camadas. IDs que o mapa não tem mais são ignorados; o restante é aplicado. Uma nova publicação gera um novo ID de publicação, então os links para a publicação antiga continuam abrindo a antiga até que o autor a revogue.
  • Um link direto não precisa de origem permitida. As origens permitidas determinam quem pode controlar um mapa por script. Um link apenas define o estado em que o mapa abre, usando coisas que qualquer leitor poderia fazer manualmente.
  • Comprimento. Uma cena com uma seleção grande gera uma URL longa. Os navegadores suportam vários milhares de caracteres, mas algumas ferramentas de chat e de e-mail truncam. Capture só o que você precisa: captureScene({ include: ["camera", "visibility"] }).
  • Também com o SDK. Se a sua página usa o SDK, prefira as opções scene, bookmarkId, filters e language: elas fazem a mesma coisa e são tipadas.