Für Entwickler · EinbettungStand 28.09.2026

SovAtlas einbetten & steuern

SovAtlas-Karten lassen sich per iFrame in eigene Portale, Intranets und Leitstellen-Dashboards einbetten und über eine JavaScript-API (postMessage) aus der einbettenden Seite heraus steuern: Kamera-Flüge, 2D/3D-Umschaltung, Screenshots und Kamera-Ereignisse.

iFrame-Einbettung

Jede Projekt-URL hat einen Zugriffsmodus, der in der Admin-Konsole unter Projekt › Embed konfiguriert wird. Dort wird auch das fertige Embed-Snippet erzeugt.

HTML

<iframe
  src="https://viewer.sovatlas.com/p/IHR-TENANT/IHRE-KARTE"
  width="100%"
  height="600"
  style="border:0"
  allow="fullscreen"
  loading="lazy"
></iframe>

Zugriffsmodi

public: frei abrufbar, auf jeder Domain einbettbar.
iframe: nur auf den von Ihnen freigegebenen Domains einbettbar (Allowlist). Die Einschränkung wird serverseitig per frame-ancestors-CSP durchgesetzt; auf anderen Domains verweigert der Browser das Laden.
password: Aufruf nur nach Passwort-Eingabe; nicht extern einbettbar.
magic_link: Aufruf nur mit gültigem signiertem Link-Token; nicht extern einbettbar.

JavaScript-Embed-API

Das Hilfspaket ist nicht öffentlich veröffentlicht. Nutzen Sie das postMessage-Protokoll direkt, wie im Beispiel unten, oder fragen Sie das Paket bei uns an.

API-Referenz

Methode	Beschreibung
`flyTo({lon, lat, height?, durationSec?})`	Kamera-Flug zu einer Position. `durationSec: 0` springt ohne Animation.
`getCamera()`	Liefert `{lon, lat, height, sceneMode2D}`.
`setSceneMode2D(enabled)`	Schaltet zwischen 3D-Globus und 2D-Lagekarte um.
`screenshot({mimeType?, quality?})`	Screenshot der Szene als Data-URL. `image/png` (Default) oder `image/jpeg` mit Qualität 0–1.
`onCameraMoveEnd(handler)`	Abonniert das Ende jeder Kamera-Bewegung; Rückgabewert meldet wieder ab.
`destroy()`	Entfernt alle Listener; offene Requests werden rejected.

Roh-Protokoll (ohne SDK)

Die API basiert auf window.postMessage mit Nachrichten im Namespace sovatlas:* und kann auch ohne das SDK genutzt werden — z. B. aus nicht-JavaScript-Umgebungen, die ein WebView steuern. Jeder Command trägt eine requestId, die in der Antwort (sovatlas:result) zur Korrelation zurückkommt.

JavaScript

// Command an das iframe senden
iframe.contentWindow.postMessage(
  { type: "sovatlas:flyTo", requestId: "req-1",
    lon: 11.0328, lat: 50.9787, height: 2500 },
  "https://viewer.sovatlas.com",
);

// Antwort empfangen
window.addEventListener("message", (event) => {
  if (event.origin !== "https://viewer.sovatlas.com") return;
  const msg = event.data;
  if (msg?.type === "sovatlas:result" && msg.requestId === "req-1") {
    console.log(msg.ok ? "OK" : msg.error);
  }
});

Verfügbare Commands: sovatlas:hello, sovatlas:flyTo, sovatlas:getCamera, sovatlas:setSceneMode2D, sovatlas:screenshot. Nach dem Boot sendet der Viewer sovatlas:ready (mit protocolVersion) an die einbettende Seite; sovatlas:hello kann den Handshake jederzeit wiederholen. Kamera-Ereignisse kommen als {type: "sovatlas:event", event: "cameraMoveEnd", camera}.

Sicherheit

Die Embed-API respektiert den Zugriffsmodus der Projekt-URL: Bei iframe beantwortet der Viewer postMessage-Commands nur von den freigegebenen Domains; bei password und magic_link nur von der eigenen Origin.
Antworten werden immer gezielt an die Absender-Origin gesendet (kein "*"-Broadcast mit Nutzdaten).
Prüfen Sie in eigenen Listenern immer event.origin gegen die Viewer-Domain — das SDK tut das automatisch.

Fragen oder weitergehende Anforderungen? Sprechen Sie uns an.