Widget-Fehlerbehebung

Fehler erscheinen im Widget als Alert und zusätzlich als Event orbinaut:error mit { code, phase, retryable }. phase ist "load". Bei Fehlern, die einen erneuten Versuch erlauben, zeigt das Widget die Schaltfläche Erneut versuchen. Die Texte kommen aus dem Embed-Vertrag. Kopiere für Support-Anfragen den Code, nie den Widget-Key und keine Teilnehmerdaten.

Achtung

Ein ungültiger, rotierter oder deaktivierter Key sieht für die Host-Seite aus wie ein nicht mehr verfügbares Widget. Das ist Absicht.

Checkliste vor dem Debuggen

1. Script-URL ist YOUR_WEB_ORIGIN/widget/v1/orbinaut-widget.js.
2. api-url ist die API-Origin ohne Pfad.
3. widget-key beginnt mit orb_widget_v1_ und stammt aus dem einmaligen Dialog.
4. Das Widget ist im Dashboard Aktiv.
5. Die Host-Origin steht exakt in Erlaubte Domains, falls die Liste nicht leer ist.
6. CSP erlaubt script-src für die Web-Origin und connect-src für die API-Origin.

Sichtbare Meldungen

Code	Sichtbarer Text	Typische Ursache	Nächster Schritt	Erneut versuchen
CONFIGURATION_ERROR	Das Widget ist nicht vollständig konfiguriert.	Attribut fehlt, api-url ist kein Origin, Key ohne Präfix orb_widget_v1_.	Embed mit Dashboard-Code vergleichen.	nein
WIDGET_KEY_INVALID	Dieses Widget ist nicht mehr verfügbar.	Unbekannter, rotierter oder deaktivierter Key.	Key rotieren oder Widget aktivieren; neuen Embed einsetzen.	nein
ORIGIN_NOT_ALLOWED	Dieses Widget darf auf dieser Website nicht angezeigt werden.	Host-Origin fehlt in Erlaubte Domains oder weicht ab (www, Trailing-Slash, anderes Schema, 127.0.0.1 statt localhost).	Exakte Origin eintragen, z. B. https://www.beispiel.de oder lokal http://localhost:4177.	nein
NETWORK_ERROR	Das Widget konnte nicht geladen werden. Prüfe Netzwerk- und CSP-Einstellungen.	connect-src blockiert, falsche api-url, Offline.	CSP und API-Origin prüfen.	ja
RATE_LIMITED	Das Widget wurde zu häufig aufgerufen. Bitte versuche es später erneut.	Mehr als 120 API-Aufrufe / 60 s je Widget, oder mehr als 120 CORS-Preflights / 60 s je Client. Analyse-Ereignisse zählen in einem eigenen Fenster von 600 Aufrufen / 60 s.	Warten und neu laden; Einbindungen bündeln.	ja
INVALID_REQUEST	Das Widget konnte nicht geladen werden. Bitte versuche es erneut.	Fehlerhafte oder zu große Anfrage, oder Widget-Key gleichzeitig als ?key= und im Header X-Orbinaut-Widget-Key mit unterschiedlichen Werten.	Code im Ereignis orbinaut:error auslesen; Embed mit dem Dashboard-Code vergleichen und den Key nur einmal übergeben.	nein
RESOURCE_NOT_FOUND	Die Widget-Inhalte sind nicht mehr verfügbar.	Scope oder Kurs nicht mehr öffentlich.	Filter und Kursstatus im Dashboard prüfen.	nein
RESPONSE_INVALID	Das Widget konnte nicht geladen werden. Bitte versuche es erneut.	Unerwartete Antwort oder apiVersion ungleich 1.	Netzwerk prüfen; bei dauerhaftem Fehler den Support mit dem Code kontaktieren.	ja

INTERNAL_ERROR und andere unbekannte Codes nutzen denselben Fallback-Text wie RESPONSE_INVALID und gelten als erneut versuchbar, wenn retryable im Event true ist.

Buchungsfehler (Zahlung, Kapazität, Dublette, Checkout) erscheinen nicht im Widget. Sie gehören zur öffentlichen Buchungsseite, die Buchen in einem neuen Tab öffnet.

Häufige Host-Probleme

Widget bleibt leer, kein Alert

script-src blockiert das Modul. Das Custom Element wird nie definiert. Höre auf error am Script-Tag und zeige eigenen Fallback.

Host-CSS färbt Buttons rot / riesige Schrift

Das Widget ist absichtlich isoliert. Wenn interne Knoten die Host-Styles erben, ist das Script nicht das offizielle Modul.

Widget zu schmal oder Karten untereinander

Unter 34 rem Containerbreite wird die Ansicht einspaltig. Gib dem Element genug Breite oder verwende die einspaltige Ansicht in schmalen Spalten.

Lokale Beispiel-Hosts und ORIGIN_NOT_ALLOWED

http://localhost:4177 und http://127.0.0.1:4177 sind verschiedene Origins. Für examples/widget-html trage http://localhost:4177 ein, für examples/widget-angular http://localhost:4178. Die Adresszeile muss mit Erlaubte Domains übereinstimmen.

Buchen öffnet die Kursseite in einem neuen Tab

Das ist der vorgesehene Weg. Die URL ist /b/{slug}/{courseId} mit source=widget. Gastformular, Zahlung und Teilnehmerkonto liegen dort, nicht im Widget. Blockiert die Host-Seite window.open oder entfernt den Link, bleibt die Person auf der Host-Seite.

Leere Kursliste ohne Alert

„Aktuell sind keine buchbaren Kurse freigegeben.“ Prüfe Kursauswahl, Durchführungsart und Filialen im Dashboard. Bei Bestimmte Kurse erscheinen neue Veröffentlichungen nicht automatisch.

Kompatibilität

• Vertrag: apiVersion 1. Inkompatible Änderungen brauchen eine neue Script-/API-Version.
• Browser: aktuelle Chrome-, Firefox-, Safari- und Edge-Versionen. Kein Internet Explorer.
• Shadow DOM, Custom Elements und ES-Module sind Pflicht. Constructable Stylesheets sind bevorzugt; ältere Browser fallen auf ein Style-Element im Shadow Root zurück.
• Mehrere Instanzen auf einer Seite werden unterstützt. Lade das Script nur einmal.

Diagnose ohne Secrets

Du kannst diese Angaben sicher nennen: Event-code, phase ("load"), retryable, Key-Präfix und Key-Version aus dem Dashboard, Host-Origin und ob das Widget aktiv ist.

Teile weder den vollständigen Widget-Key oder Hash noch Namen, E-Mail-Adressen oder andere personenbezogene Daten.