Diese Seite richtet sich an Entwickler:innen. Sie beschreibt, wie der Inhaltseditor deine Website als Live-Vorschau einbettet, wo die Preview-URLs konfiguriert werden und was deine Umgebung erfüllen muss, damit die Vorschau zuverlässig funktioniert. Die Browser-Hilfe für Redaktor:innen findest du unter Probleme mit der Live-Vorschau.
Wo Preview-URLs konfiguriert werden
In den Einstellungen der Nitro CMS Integration hinterlegst du unter Vorproduktionsumgebung eine oder mehrere Adressen. Jede Adresse hat einen Token-Typ:
- Development: Diese Adressen erscheinen im Inhaltseditor als Live-Vorschau. Die Umgebung muss den Development-Token verwenden und den Live-Edit-Modus aktiviert haben, damit ungespeicherte Änderungen sichtbar sind und die Vorschau auf den Editor reagiert.
- Production: Diese Adressen erscheinen im Vorschau-Dialog der Integration und zeigen den publizierten Stand.
Der Editor ersetzt beim Aufruf jeweils den Pfad der konfigurierten Adresse durch den Slug der bearbeiteten Seite. Query-Parameter bleiben dabei erhalten: Eine Adresse wie https://preview.example.com?token=abc wird zu https://preview.example.com/ueber-uns?token=abc. Darauf bauen geschützte Vorschau-Umgebungen auf (siehe unten).
Anforderungen an die Live-Edit-Umgebung
Live-Edit aktiviert: Die Umgebung läuft mit dem Development-Token und aktiviertem Live-Edit-Modus (bei
@flyo/nitro-nextzum BeispielFLYO_LIVE_EDIT=true, bei den SDKs dieliveEdit-Option). Eine Produktions-Umgebung wird zwar angezeigt, reagiert aber nicht auf den Editor.Einbettbar: Der Editor bettet die Website in einen iFrame ein. Die Live-Edit-Umgebung darf das nicht verbieten:
- Kein
X-Frame-Options-Header (beziehungsweise nichtDENYoderSAMEORIGIN), oder - per Content-Security-Policy explizit erlauben:
Content-Security-Policy: frame-ancestors 'self' https://flyo.cloud
Typische Stolperfalle: Security-Header-Vorlagen (Next.js
headers(), nginx, Helmet), die pauschalX-Frame-Options: DENYsetzen.- Kein
Bridge aktuell halten: Die Live-Edit-Funktionen (Reload bei Änderungen, Scroll-zu-Block, Klick-zum-Bearbeiten) kommen aus @flyo/nitro-js-bridge. Ab Version 1.4.0 beantwortet die Bridge zusätzlich die Verbindungsprüfung des Editors (siehe nächster Abschnitt). Die offiziellen Adapter binden die Bridge bereits ein; Details pro Adapter stehen im Upgrade-Guide.
Wie der Editor die Verbindung prüft
Der Editor sendet nach dem Laden der Vorschau eine postMessage-Anfrage (liveEditPing) an den iFrame. Die Bridge (ab 1.4.0) antwortet mit liveEditReady. Bleibt die Antwort aus, zeigt der Editor nach wenigen Sekunden den Hinweis «Keine Verbindung zur Live-Vorschau» mit Lösungsvorschlägen an, statt einer stummen weissen Fläche.
Keine Antwort bedeutet einer der folgenden Fälle:
- Die Adresse ist keine Live-Edit-Umgebung (falscher Token-Typ, Live-Edit nicht aktiviert).
- Der iFrame wurde blockiert (
X-Frame-Options,frame-ancestors) oder die Website ist nicht erreichbar. - Eine geschützte Vorschau-Umgebung konnte den Browser nicht anmelden (Drittanbieter-Cookies, siehe unten).
- Die Website verwendet noch eine Bridge-Version vor 1.4.0. Die Vorschau funktioniert dann zwar, der Editor kann es aber nicht erkennen; der Hinweis lässt sich schliessen. Aktualisiere die Bridge, damit er verschwindet.
Geschützte Vorschau-Umgebungen
Schutzsysteme wie Vercel Deployment Protection, Cloudflare Access oder Basic-Auth melden den Browser über ein Cookie an. Im Editor ist deine Website eingebettet, das Anmelde-Cookie ist dort ein Drittanbieter-Cookie. Browser, die Drittanbieter-Cookies blockieren (Safari immer, Inkognito-Fenster, restriktive Einstellungen), verwerfen es: Die Vorschau bleibt weiss, obwohl die Adresse im neuen Tab funktioniert.
Redaktor:innen können das pro Gerät mit einer Browser-Ausnahme umgehen. Nachhaltiger ist, das Problem einmalig pro Projekt zu lösen:
- Vorschau-Domain vom Schutz ausnehmen (empfohlen): Die Live-Edit-Umgebung auf einer eigenen, nicht verlinkten Domain betreiben (zum Beispiel
preview.example.com), diese vom Schutz ausnehmen und mitnoindexversehen. Live-Edit-Inhalte sind Entwürfe, keine Geheimnisse; für die meisten Projekte ist das der beste Kompromiss. - Schutz auf Preview-Deployments beschränken: Nur die automatischen Preview- und Branch-Deployments schützen und die Live-Edit-Umgebung als eigene Production-Domain ausliefern.
- IP-Allowlist statt Cookie-Anmeldung, falls das Team über feste IP-Adressen arbeitet.
Vercel Deployment Protection
Vercel bietet für geschützte Deployments den Protection Bypass for Automation an (Project, Settings, Deployment Protection). Damit die Vorschau im Editor funktioniert, hängst du beide Parameter an die Preview-URL in den Integrations-Einstellungen an:
https://preview.example.com?x-vercel-protection-bypass=DEIN_SECRET&x-vercel-set-bypass-cookie=samesitenoneWert «samesitenone» ist zwingend
x-vercel-set-bypass-cookie muss den Wert samesitenone haben. Mit true setzt Vercel das Cookie mit SameSite=Lax; ein solches Cookie sendet kein Browser in einen eingebetteten Frame, und die Vorschau bleibt in allen Browsern weiss. Der Editor prüft die Adresse beim Erfassen und weist auf diesen Fehler hin.
Technischer Hintergrund: Vercel beantwortet den ersten Aufruf mit einem Redirect und setzt dabei das Bypass-Cookie (_vercel_jwt). Alle Folge-Anfragen (Assets, Skripte, Client-Navigationen) hängen an diesem Cookie, der Query-Parameter allein genügt nicht. Auch mit samesitenone bleibt es ein Drittanbieter-Cookie: In Safari, in Inkognito-Fenstern und bei blockierten Drittanbieter-Cookies wird es verworfen. Für diese Browser gibt es keine URL-seitige Lösung, nur die nachhaltigen Varianten:
- Deployment Protection Exceptions für die Vorschau-Domain (Advanced Deployment Protection im Pro-Plan beziehungsweise Enterprise).
- Deployment Protection auf «Only Preview Deployments» stellen und die Live-Edit-Umgebung über eine eigene Production-Domain ausliefern.
Andere Systeme (Cloudflare Access, Basic-Auth-Stagings) verhalten sich analog: Wenn möglich die Vorschau-Domain vom Schutz ausnehmen.