Liens profonds

Certains emplacements peuvent afficher un iframe mais ne peuvent pas exécuter votre JavaScript : une page SharePoint, une macro Confluence, un lien dans un e-mail. Dans ces cas, l'URL de la carte peut porter l'état dans lequel elle doit s'ouvrir. Aucun SDK n'intervient.

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

Ce qu'un lien peut porter

Lorsque plusieurs paramètres sont présents, ils sont appliqués dans cet ordre : c'est donc la scène qui a le dernier mot.

Valeurs de filtre

Une valeur simple est interprétée comme du texte. Toute autre valeur s'écrit en JSON, encodée pour l'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 nom que l'auteur n'a pas déclaré est ignoré, exactement comme il serait rejeté par l'API : un lien ne peut jamais filtrer sur une colonne que l'auteur n'a pas proposée.

Pourquoi la scène se trouve dans le fragment

Tout ce qui suit # reste dans le navigateur : rien n'est envoyé au serveur, et cela n'apparaît donc jamais dans les journaux d'accès, les proxys ou les outils d'analyse d'audience. Une scène peut contenir une sélection et des valeurs de filtre, ce qui suffit à justifier de l'en tenir à l'écart.

Créer des liens

Depuis la boîte de dialogue de publication

Après la publication, la boîte de dialogue propose Copy link to this view à côté de l'URL d'incorporation. Cette option capture la caméra actuelle de l'éditeur, la visibilité des couches et les sélections des segments sous forme de scène, puis copie un lien qui ouvre la carte publiée exactement à cet endroit.

Depuis votre page

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",
});

Chaque partie est facultative. deepLinkFromUrl(url) effectue l'opération inverse, si vous voulez relire un lien :

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

À la main

Une scène est du JSON encodé en base64url : un lien peut donc être produit par tout ce qui sait le faire, qu'il s'agisse d'un serveur, d'un rapport ou d'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 et camera sont obligatoires ; tout le reste d'une scène est facultatif.

Bon à savoir

• Les liens survivent à une republication des mêmes couches. Les id que la carte n'a plus sont ignorés ; le reste s'applique. Une republication génère toutefois un nouvel identifiant de publication : les liens vers l'ancienne publication continuent donc d'ouvrir l'ancienne jusqu'à ce que l'auteur la révoque.
• Un lien profond ne nécessite aucune origine autorisée. Les origines autorisées déterminent qui peut piloter une carte par script. Un lien ne fait que définir l'état d'ouverture de la carte, avec des actions que n'importe quel lecteur pourrait effectuer à la main.
• Longueur. Une scène contenant une sélection importante produit une URL longue. Les navigateurs acceptent plusieurs milliers de caractères, mais certains outils de messagerie instantanée et d'e-mail tronquent les liens. Ne capturez que ce dont vous avez besoin : captureScene({ include: ["camera", "visibility"] }).
• Aussi avec le SDK. Si votre page utilise le SDK, préférez les options scene, bookmarkId, filters et language : elles font la même chose et sont typées.