Deep Links

Manche Orte können ein iframe anzeigen, aber kein eigenes JavaScript ausführen: eine SharePoint-Seite, ein Confluence-Makro, ein Link in einer E-Mail. Dafür kann die URL der Karte den Zustand enthalten, in dem sie sich öffnen soll. Ein SDK ist nicht beteiligt.

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

Was ein Link enthalten kann

In der URL	Wirkung
`?bookmark=<id>`	Öffnet mit einem der Lesezeichen des Autors
`?f.<name>=<value>`	Setzt einen deklarierten Filter. Für mehrere Filter wiederholen
`?lang=<code>`	Anzeigesprache, zum Beispiel `fr` oder `de-DE`
`#s=<scene>`	Stellt eine vollständig erfasste Szene wieder her: Kamera, Sichtbarkeit, Datenschnitte, Filter, Auswahl, Grundkarte

Sind mehrere vorhanden, werden sie in dieser Reihenfolge angewendet. Eine Szene hat also das letzte Wort.

Filterwerte

Ein einfacher Wert wird als Text interpretiert. Alles andere wird als JSON geschrieben und URL-codiert:

?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

Ein Name, den der Autor nicht deklariert hat, wird ignoriert, genau wie er über die API abgelehnt würde. Ein Link kann nie nach einer Spalte filtern, die der Autor nicht angeboten hat.

Warum die Szene im Fragment steht

Alles nach # bleibt im Browser: Es wird nicht an den Server gesendet und taucht daher nie in Zugriffsprotokollen, Proxys oder Analysen auf. Eine Szene kann eine Auswahl und Filterwerte enthalten, Grund genug, sie dort herauszuhalten.

Links erstellen

Aus dem Veröffentlichungsdialog

Nach dem Veröffentlichen bietet der Dialog neben der Einbettungs-URL Copy link to this view an. Damit werden die aktuelle Kamera, die Ebenensichtbarkeit und die Datenschnittauswahl des Editors als Szene erfasst, und es wird ein Link kopiert, der die veröffentlichte Karte genau dort öffnet.

Von Ihrer Seite aus

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

Jeder Teil ist optional. deepLinkFromUrl(url) ist die Umkehrung, falls Sie einen Link wieder auslesen möchten:

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

Von Hand

Eine Szene ist base64url-codiertes JSON. Ein Link kann also von allem erzeugt werden, was das beherrscht: einem Server, einem Bericht, einem Skript.

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 und camera sind Pflicht; alles andere in einer Szene ist optional.

Gut zu wissen

Links überstehen eine erneute Veröffentlichung derselben Ebenen. IDs, die die Karte nicht mehr hat, werden übersprungen; der Rest wird angewendet. Eine erneute Veröffentlichung erzeugt allerdings eine neue Publish-ID, sodass Links auf die alte Veröffentlichung weiterhin die alte öffnen, bis der Autor sie widerruft.
Ein Deep Link benötigt keinen zulässigen Ursprung. Zulässige Ursprünge regeln, wer eine Karte per Skript steuern darf. Ein Link legt nur den Zustand fest, in dem sich die Karte öffnet, und verwendet dafür nur Dinge, die jeder Betrachter auch von Hand tun könnte.
Länge. Eine Szene mit einer großen Auswahl ergibt eine lange URL. Browser kommen mit mehreren tausend Zeichen zurecht, manche Chat- und E-Mail-Programme kürzen jedoch. Erfassen Sie nur, was Sie brauchen: captureScene({ include: ["camera", "visibility"] }).
Auch mit dem SDK. Wenn Ihre Seite das SDK verwendet, ziehen Sie die Optionen scene, bookmarkId, filters und language vor. Sie bewirken dasselbe und sind typisiert.