Vínculos profundos

Algunos lugares pueden mostrar un iframe pero no ejecutar su JavaScript: una página de SharePoint, una macro de Confluence, un vínculo en un correo electrónico. Para ellos, la URL del mapa puede llevar el estado en el que debe abrirse. No interviene ningún SDK.

<iframe src="https://embed.iconmap.ai/v/pub_...?bookmark=bm-north&f.region=EMEA&lang=de"
        style="width: 100%; height: 600px; border: 0"></iframe>

Qué puede llevar un vínculo

Cuando hay varios, se aplican en ese orden, de modo que la escena tiene la última palabra.

Valores de filtro

Un valor simple se toma como texto. Cualquier otra cosa se escribe como JSON 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

Un nombre que el autor no declaró se ignora, igual que se rechazaría a través de la API: un vínculo nunca puede filtrar por una columna que el autor no ofreció.

Por qué la escena va en el fragmento

Todo lo que va después de # se queda en el navegador: no se envía al servidor, así que nunca aparece en registros de acceso, proxies ni herramientas de análisis. Una escena puede contener una selección y valores de filtro, razón suficiente para mantenerla fuera de ellos.

Crear vínculos

Desde el cuadro de diálogo de publicación

Después de publicar, el cuadro de diálogo ofrece Copy link to this view junto a la URL de inserción. Captura como escena la cámara, la visibilidad de las capas y las selecciones de las segmentaciones actuales del editor, y copia un vínculo que abre el mapa publicado exactamente ahí.

Desde su 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 las partes son opcionales. deepLinkFromUrl(url) hace lo contrario, si quiere volver a leer uno:

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

A mano

Una escena es JSON codificado en base64url, así que cualquier cosa capaz de hacerlo puede generar un vínculo: un servidor, un informe, un 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 y camera son obligatorios; todo lo demás de una escena es opcional.

Conviene saber

• Los vínculos sobreviven a una nueva publicación de las mismas capas. Los ids que el mapa ya no tiene se omiten; el resto se aplica. Una nueva publicación sí genera un nuevo id de publicación, por lo que los vínculos a la publicación antigua siguen abriendo la antigua hasta que el autor la revoque.
• Un vínculo profundo no necesita un origen permitido. Los orígenes permitidos determinan quién puede controlar un mapa desde script. Un vínculo solo establece el estado en el que se abre el mapa, con cosas que cualquier lector podría hacer a mano.
• Longitud. Una escena con una selección grande genera una URL larga. Los navegadores admiten varios miles de caracteres, pero algunas herramientas de chat y de correo electrónico la truncan. Capture solo lo que necesite: captureScene({ include: ["camera", "visibility"] }).
• También con el SDK. Si su página usa el SDK, es preferible usar las opciones scene, bookmarkId, filters y language: hacen lo mismo y tienen tipo.