Widget einbinden

Vorbereitung im Dashboard

Owner und Admins legen Widgets unter Widgets an. Trainer:innen haben keinen Zugriff.

Wähle Widget anlegen und lege Name, Kurse, Filialen und erlaubte Domains fest.
Öffne den Dialog Embed-Code einmalig sichern bewusst.
Kopiere den Code und schließe den Dialog erst, nachdem du bestätigt hast, dass du ihn gespeichert hast oder den Key rotieren kannst.

Kursnaut speichert nur den SHA-256-Hash. Listen zeigen später nur Präfix und Key-Version. Ein verlorener Key lässt sich nicht erneut anzeigen; rotiere ihn stattdessen.

Minimales Embed

Das Script kommt von der Kursnaut-Web-Origin. Die API-Origin steht in api-url.

<script type="module" src="YOUR_WEB_ORIGIN/widget/v1/kursnaut-widget.js"></script>

<kursnaut-booking-widget
  api-url="YOUR_API_URL"
  widget-key="YOUR_WIDGET_KEY"
></kursnaut-booking-widget>

Teil	Vertrag
Script	`YOUR_WEB_ORIGIN/widget/v1/kursnaut-widget.js` als `type="module"`, einmal pro Seite
Custom Element	`kursnaut-booking-widget`
`api-url`	HTTPS-Origin ohne Pfad, Query, Hash oder Zugangsdaten. HTTP nur für `localhost`, `127.0.0.1` und `[::1]`
`widget-key`	vollständiger Key mit Präfix `orb_widget_v1_`
`lang` (optional)	`de`, `en` oder `fr` für die Widget-Texte. Ohne Attribut gilt ein auf der Host-Origin unter `localStorage["kursnaut:locale"]` gespeicherter Wert, sonst `lang` des Host-Dokuments, sonst die Browsersprache. `locale` ist ein Alias.

Ändert sich eines dieser Attribute, lädt nur dieses Element neu. Entfernst du das Element, bricht es laufende Anfragen ab.

Buchen öffnet die gehostete Seite /b/{slug}/{courseId} in einem neuen Tab (source=widget). Die Host-Seite bleibt geöffnet. Es gibt kein Formular, keine Zahlung und keine Anmeldung im Widget.

Eine neutrale HTML-Vorlage mit absichtlich grobem Host-CSS liegt unter /examples/widget-html.html. Das ist die Copy-Paste-Referenz, kein lokaler Server.

Zum Einfügen eines echten Dashboard-Embeds dienen die laufenden Hosts examples/widget-html (http://localhost:4177) und examples/widget-angular (http://localhost:4178). Starte sie mit npm run dev:widget-html und npm run dev:widget-angular. Sie werden nicht von npm run dev gestartet. Trage die exakte Origin in Erlaubte Domains ein. Ablauf und Befehle: Beispiele.

Aktivierung, Vorschau, Rotation

Aktion	Wirkung
Vorschau	zeigt Theme und aktuelle Kursfilter. Die Vorschau erfasst keine Nutzung und legt keine Buchung an.
Key rotieren	ersetzt den Hash, erhöht die Key-Version und macht den bisherigen Embed-Code sofort ungültig. Der neue Key erscheint genau einmal.
Deaktivieren	weist den aktuellen Key ab. Kursfilter und Origins bleiben erhalten.
Aktivieren	erlaubt dem bestehenden Key wieder, Inhalte zu laden.

Nach einer Rotation musst du den neuen Embed-Code auf jeder Host-Seite ersetzen.

Content-Security-Policy

Eine strikte Host-Policy braucht mindestens:

Content-Security-Policy:
  script-src YOUR_WEB_ORIGIN;
  connect-src YOUR_API_URL;
  img-src YOUR_API_URL;
  font-src YOUR_WEB_ORIGIN YOUR_API_URL;

Ergänze diese Quellen in den bereits vorhandenen Direktiven deiner Host-Policy; ersetze die bestehende Policy nicht. img-src erlaubt veröffentlichte Kursbilder. font-src YOUR_WEB_ORIGIN erlaubt die mitgelieferte Geist-Schrift; YOUR_API_URL erlaubt veröffentlichte eigene Schriften.

Das Widget lädt Schriften über die Font Loading API und registriert sie mit eigenen Familiennamen im Dokument. Dadurch funktionieren sie auch im Shadow DOM, ohne die Schriften der Host-Seite zu ersetzen. Mehrere Widgets teilen sich bereits geladene Schriften; eigene Schriften erhalten bei geändertem Inhalt einen neuen Familiennamen. Pro Dokument werden höchstens 64 Schriftdateien registriert. Blockiert die Host-Policy eine Schrift oder schlägt das Laden fehl, bleibt das Widget mit einer Systemschrift bedienbar.

Das Modul verwendet kein eval, keine globalen Host-Styles und keine Inline-Event-Handler. Constructable Stylesheets machen style-src in aktuellen Browsern für das Widget überflüssig. Der Fallback für ältere Browser verwendet ein Style-Element und benötigt deshalb eine passende Inline-Style-Freigabe.

Blockiert script-src das Modul, kann der Browser das Custom Element nicht rendern. Höre in diesem Fall auf das error-Ereignis des Script-Tags aus deinem bereits erlaubten Bundle und zeige eigenen Fallback-Inhalt.

Mehrere Widgets

Das Script nur einmal laden. Danach dürfen beliebig viele kursnaut-booking-widget-Elemente folgen, auch mit unterschiedlichen Keys. Jedes Element lädt Manifest und Kursliste selbst.

Siehe Beispiele und Fehlerbehebung.