Fehler, Limits und Versionierung

Fehler

Ein fehlgeschlagener Befehl wird mit einem EmbedError abgelehnt. Sein code ist stabil und für Verzweigungen gedacht; message ist für Entwickler geschrieben, die eine Konsole lesen.

const { EmbedError } = IconMapEmbed;

try {
  await map.applyBookmark({ bookmarkId });
} catch (e) {
  if (!(e instanceof EmbedError)) throw e;
  switch (e.code) {
    case "unknown_id":        return forgetBookmark(bookmarkId);
    case "denied_capability": return hideBookmarkMenu();
    default:                  report(e.code, e.message, e.requestId);
  }
}

Welcher Code was bedeutet

Die Codes fallen in vier Familien, und die richtige Reaktion ist jeweils eine andere.

Ihre Seite ist nicht berechtigt: denied_origin, denied_capability. Darüber entscheidet der Autor. denied_origin lehnt bereits ready ab: Es wurde keine Sitzung geöffnet, und nichts funktioniert, bis Ihre Website den zulässigen Ursprüngen der Karte hinzugefügt wird. denied_capability bedeutet, dass eine Gruppe deaktiviert ist (oder bei exportImage und print, dass eine Vertraulichkeitsbezeichnung den Export verweigert). Blenden Sie die Funktion aus; ein erneuter Versuch hilft nicht.

Die Karte hat es nicht: unsupported_command, unknown_id, undeclared_filter. Prüfen Sie capabilities.commands, bevor Sie eine Funktion anbieten, und bauen Sie Auswahllisten aus dem auf, was die Karte meldet (getLayers, getBookmarks, getFilterSchema), statt aus IDs in Ihrem Code.

Der Aufruf war falsch: invalid_args, too_large. Ein Fehler im aufrufenden Code; die Meldung nennt das Argument.

Später erneut versuchen: rate_limited, busy, budget_exceeded, data_error, timeout, not_ready. Warten Sie ab, statt in einer Schleife zu wiederholen.

Zwei Codes kommen vom SDK und nicht von der Karte: timeout (keine Antwort innerhalb von 15 Sekunden; änderbar mit der Option commandTimeoutMs) und destroyed (Sie haben die Karte zerstört oder neu geladen, während ein Befehl unterwegs war).

Fehler beim Start

Kann die Karte gar nicht starten (eine widerrufene Veröffentlichung, ein abgelehntes Token), wird ready abgelehnt und die Option onError aufgerufen. Die Karte zeigt dem Betrachter ihre eigene Meldung an, es sei denn, Sie übergeben hideErrors: true und zeigen Ihre eigene.

Limits

Diese Werte sind fest. Ihre Seite kann sie nicht erhöhen, und ein Autor kann sie nicht senken; sie werden auch als EMBED_LIMITS exportiert.

Capabilities statt Versionen

await map.ready wird mit einer Beschreibung dessen aufgelöst, was diese Karte beantwortet:

{
  protocol: 2,
  commands: ["getView", "setView", ...],
  events:   ["viewChanged", "featureClick", ...],
  policy:   { enabled: true, read: true, camera: true, layers: true, ... },
  map:      { publishId, surface: "published", dataMode: "snapshot", bookmarks: true, locales: ["en-US", "de-DE", ...] }
}

commands ist bereits die Schnittmenge aus drei Dingen: was diese Version der Karte implementiert, was diese Art der Einbettung unterstützt und was der Autor aktiviert hat. Die einzige Prüfung, die Sie je brauchen, ist daher:

if (capabilities.commands.includes("exportImage")) showExportButton();

Neue Befehle kommen hinzu, indem sie in diese Liste aufgenommen werden. Eine heute geschriebene Seite funktioniert weiter; eine Seite, die einen neueren Befehl möchte, fragt danach und kommt ohne ihn aus, wenn er fehlt.

Kompatibilität zwischen Alt und Neu

Die Karte und das SDK werden getrennt veröffentlicht, daher kommt jede Seite damit zurecht, dass die andere älter ist.

Die ausgehandelte Version steht in map.protocol. Sie sollten sie nicht benötigen.

Lebenszyklus

map.reload();      // reload the frame; subscriptions are restored when it is back
map.destroy();     // remove the frame; anything in flight rejects with `destroyed`

getEmbed(element) liefert das Handle, das bereits in einem Element eingebunden ist, und reset(element) zerstört es. Nützlich in Frameworks, in denen der Code, der die Karte einbindet, nicht derselbe ist, der aufräumt.

Sicherheitsmodell

Für ein Sicherheitsreview sind diese Eigenschaften relevant:

• Isolation. Die Karte läuft in einem ursprungsübergreifenden iframe. Sie kann Ihre Seite nicht lesen und Ihre Seite sie nicht; der einzige Kanal ist postMessage.
• Wer sprechen darf. Die Karte akzeptiert Nachrichten nur von dem Fenster, das sie eingebettet hat, und nur, wenn dessen Ursprung unter den zulässigen Ursprüngen des Autors steht. Ein Frame eines Drittanbieters auf Ihrer Seite kann die Karte nicht steuern, selbst von einem zulässigen Ursprung aus. Umgekehrt akzeptiert das SDK Nachrichten nur von dem Frame, den es erstellt hat, auf dem erwarteten Ursprung, und sendet Tokens nirgendwo anders hin.
• Was gesagt werden darf. Eine geschlossene Liste von Befehlen mit validierten Argumenten. Keiner nimmt eine URL, eine Abfrage, einen Stil, HTML oder Skript entgegen.
• Was zurückkommt. Nur, was ein Betrachter ohnehin sehen kann: QuickInfo-Felder, niemals ganze Zeilen; niemals die Konfiguration, Datenquellen oder Abfragen der Karte.
• Wer entscheidet. Zulässige Ursprünge und die Schalter der Befehlsgruppen sind Teil der signierten Veröffentlichung und werden in der Karte durchgesetzt, und wo ein Befehl unsere Server erreicht (refreshData), zusätzlich dort.
• Der Datenzugriff bleibt unverändert. Die API schafft keinen neuen Weg zu Daten. Eine veröffentlichte Karte liest, was die Veröffentlichung eingefroren hat oder was die Sicherheit auf Zeilenebene ihres Tokens erlaubt; eine organisationsinterne Einbettung liest im Namen des angemeldeten Betrachters.
• Vertraulichkeitsbezeichnungen. Über Bildexport und Drucken entscheiden dieselben Regeln für Vertraulichkeitsbezeichnungen wie über jeden anderen Export aus Icon Map.
• Telemetrie. Wir zählen Steuerungssitzungen und welche Befehlsgruppen verwendet werden. Argumentwerte (Filterwerte, Auswahlen, Ihre Menütitel) werden nie erfasst.

Dieselbe Liste zulässiger Ursprünge legt auch die frame-ancestors-Richtlinie fest. Sie bestimmt also, welche Websites die Karte überhaupt in einem Frame einbinden dürfen.