Entwickler-Dokumentation

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.

1. 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.

<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.

2. JavaScript-Embed-API

Das Paket @sovatlas/embed kapselt das postMessage-Protokoll hinter einer Promise-API. Es ist framework-frei und hat keine Abhängigkeiten.

import { connectSovatlasEmbed } from "@sovatlas/embed";

const iframe = document.querySelector("iframe#sovatlas");

const map = await connectSovatlasEmbed(iframe, {
  viewerOrigin: "https://viewer.sovatlas.com",
});

// Kamera-Flug (WGS84 / EPSG:4326)
await map.flyTo({ lon: 11.0328, lat: 50.9787, height: 2500 });

// Aktuelle Kamera-Position lesen
const cam = await map.getCamera();
console.log(cam.lon, cam.lat, cam.height, cam.sceneMode2D);

// 2D-Lagekarte ein-/ausschalten
await map.setSceneMode2D(true);

// Screenshot als Data-URL (PNG)
const dataUrl = await map.screenshot();

// Kamera-Ereignisse abonnieren
const off = map.onCameraMoveEnd((cam) => {
  console.log("Kamera steht:", cam.lon, cam.lat);
});

// Aufräumen
off();
map.destroy();

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.

3. 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.

// 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}.

4. 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 (eigene Module, Single Sign-on, On-Premise)? Sprechen Sie uns an.