Seite einbetten
Öffnen Sie das Jamdesk-Changelog in Ihrer App per Schaltfläche in einem Modal, inklusive Ungelesen-Punkt – mit nur einem Skript-Tag und ohne Build-Schritt.
Fügen Sie einen „Was gibt’s Neues?“-Auslöser in Ihr Produkt ein. Eine Schaltfläche oder ein schwebender Launcher öffnet die Changelog-Einträge Ihrer Dokumentation in einem Modal. Ein Punkt kennzeichnet ungelesene Updates pro Besucher. Fügen Sie ein <script>-Tag ein. Jamdesk hostet und versioniert das Widget.
Die Anzeige des Ungelesen-Punkts ist auf das Changelog ausgelegt. Das Widget kann jedoch jede Dokumentationsseite im Modal öffnen. Weitere Informationen finden Sie unter Modal auf beliebige Seite ausrichten.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Live ausprobieren
Auf dieser Seite läuft das echte Widget. Klicken Sie auf die Schaltfläche, um das Modal zu öffnen, das Ihre Besucher sehen – mit dem Changelog dieser Website:
Diese Schaltfläche ist die MDX-Komponente <Widget>. Verwenden Sie sie, um das Widget in einer Jamdesk-Dokumentationsseite einzubetten. Dafür genügt ein Tag, ein Skript ist nicht erforderlich, und die Komponente findet Ihre Website automatisch. Verwenden Sie den <script>-Ausschnitt weiter unten, um das Widget in Ihr eigenes Produkt oder Ihre eigene App einzubetten, wo MDX-Komponenten nicht ausgeführt werden. Widget und Modal sind identisch. Der Rest dieser Seite behandelt das Skript.
Voraussetzungen
- Eine veröffentlichte Jamdesk-Website auf ihrer
*.jamdesk.app-Subdomain. Das Widget wird immer von dort geladen, selbst wenn Sie Ihre Dokumentation zusätzlich unter einer benutzerdefinierten Domain bereitstellen. - Eine Changelog-Seite, die aus
<Update>-Einträgen mitrss: trueim Frontmatter erstellt wurde (siehe Mitrss: trueaktivieren).
Schnellstart
Öffnen Sie Ihr Dashboard und gehen Sie zu Integrations → What's New widget. Legen Sie die Seiten- und Launcher-Optionen fest. Kopieren Sie den generierten Ausschnitt. Er sieht so aus:
<script
src="https://acme.jamdesk.app/_jd/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/changelog"
data-theme="auto"
async
></script>Fügen Sie ihn vor dem schließenden </body>-Tag in den HTML-Code Ihrer App ein. Dadurch wird in einer Ecke ein schwebender What's new-Launcher eingeblendet. Er öffnet Ihr Changelog in einem Modal. Ein Ungelesen-Punkt erscheint, wenn es einen Eintrag gibt, den der Besucher noch nicht gesehen hat.
Ersetzen Sie acme durch Ihre eigene Subdomain. Die Dashboard-Karte trägt diesen Wert ein. Sie setzt data-base auf den richtigen Ursprung, einschließlich des /docs-Pfads, wenn Sie die Dokumentation unter einem Unterpfad hosten.
Eine Version festlegen oder selbst hosten
Das Widget ist Open Source. Der oben gezeigte gehostete Ausschnitt liefert immer die neueste Version. Das Repository jamdesk-widget bietet zwei weitere Möglichkeiten zum Laden: eine bekannte Version fixieren oder die Datei selbst bereitstellen.
Eine Version mit jsDelivr fixieren. Laden Sie ein getaggtes Release vom CDN. Die Bytes ändern sich nicht:
<script
src="https://cdn.jsdelivr.net/gh/jamdesk/jamdesk-widget@v1.0.0/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/changelog"
async
></script>Selbst hosten. Laden Sie widget.js aus dem neuesten Release herunter und stellen Sie die Datei von Ihrem eigenen Ursprung bereit. Verwenden Sie diese Methode, wenn eine strenge script-src-Richtlinie Skripte von Drittanbietern ausschließt.
Setzen Sie data-base für eine fixierte oder selbst gehostete Datei auf Ihren *.jamdesk.app-Ursprung. Der gehostete Ausschnitt liest den Wert aus der URL des Skripts. Ein CDN oder Ihr eigener Server kann das nicht. Zu jedem Release wird ein Subresource-Integrity-Hash veröffentlicht, mit dem sich die exakten Bytes fixieren lassen. Die README des Repositorys beschreibt die drei Installationswege.
Mit rss: true aktivieren
Das Widget liest den neuesten Eintrag aus Ihrem RSS-Feed. Eine Seite speist das Widget nur dann, wenn in ihrem Frontmatter rss: true festgelegt ist:
---
title: Changelog
rss: true
---
<Update label="June 2026" date="2026-06-01">
**Spec validation at build time.** Every deploy validates the OpenAPI specs your `docs.json` references.
</Update>Ohne rss: true wird das Widget zwar geladen, zeigt aber keine Einträge an. Der Launcher bleibt ausgeblendet. Eine Dokumentationsseite, die die <Update>-Komponente nur demonstriert (ohne rss: true), wird nicht berücksichtigt. Ein Demodatum lässt den Punkt nicht aufleuchten.
Jedes <Update>, das in den Widget-Feed eingeht, benötigt ein date (einen Wert, den Date.parse lesen kann, etwa 2026-06-01). rss: true auf der Seite reicht nicht aus. Das Datum sortiert den Feed und kennzeichnet den neuesten Eintrag. Das Widget überspringt Einträge ohne Datum. Gibt es keine datierten Einträge, bleibt der schwebende Launcher ausgeblendet und der Ungelesen-Punkt erscheint nie – auch wenn rss: true gesetzt ist.
Das Snippet konfigurieren
Jede Option wird als data--Attribut im Script-Tag angegeben. Die Dashboard-Karte trägt diese Werte ein. Sie können den Ausschnitt auch manuell bearbeiten.
| Attribut | Werte | Standard | Zweck |
|---|---|---|---|
data-base | URL Ihrer Website | Skriptursprung | Der *.jamdesk.app-Ursprung (plus /docs, wenn Sie die Dokumentation unter einem Unterpfad hosten). |
data-page | Pfad | /changelog | Jeder Dokumentationspfad, der im Modal geöffnet werden soll – nicht nur das Changelog. Siehe Modal auf beliebige Seite ausrichten. |
data-theme | auto, light, dark | auto | Legt das Farbschema des Modals fest oder übernimmt die Systemeinstellung des Besuchers. |
data-position | bottom-right, bottom-left, top-right, top-left | bottom-right | Legt fest, in welcher Ecke der schwebende Launcher erscheint. Wird ignoriert, wenn data-trigger gesetzt ist. |
data-label | Text | What's new | Der Schaltflächentext des schwebenden Launchers. |
data-width | CSS-Längenangabe | 560px | Breite des Modals. Siehe Modalgröße anpassen. |
data-height | CSS-Längenangabe | 680px | Höhe des Modals. |
data-radius | CSS-Längenangabe | 12px | Eckenradius des Modals. Verringern Sie den Wert für eckigere Ecken. |
data-unread | off zum Deaktivieren | an | Legt fest, ob der Ungelesen-Punkt angezeigt wird. |
data-unread-color | Hexadezimalwert oder CSS-Farbname | #e5484d | Farbe des Ungelesen-Punkts. |
data-button-color | Hexadezimalwert oder CSS-Farbname | #111 | Hintergrund des schwebenden Launchers. Wird ignoriert, wenn data-trigger gesetzt ist. |
data-button-text-color | Hexadezimalwert oder CSS-Farbname | #fff | Textfarbe des schwebenden Launchers. |
data-trigger | CSS-Selektor | (none) | Verknüpft das Widget mit einem eigenen Element statt mit dem schwebenden Launcher. |
data-project | Slug | abgeleitet aus data-base | Schlüssel, unter dem der „gesehen“-Status pro Besucher gespeichert wird. Nur überschreiben, wenn ein Ursprung mehr als ein Changelog bereitstellt. |
Das Modal auf eine beliebige Seite richten
Mit data-page lässt sich jeder Pfad Ihrer Dokumentationswebsite öffnen, nicht nur /changelog. Das Modal zeigt die angegebene Seite ohne Website-Rahmen an. Verwenden Sie diese Option für eine Ankündigung oder einen Migrationshinweis:
<script
src="https://acme.jamdesk.app/_jd/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/announcements/2026-migration"
data-unread="off"
async
></script>Zwei Verhaltensweisen bleiben an Ihren Changelog-Feed gebunden:
- Der Ungelesen-Punkt verfolgt den neuesten Eintrag Ihres Changelogs, nicht die Seite im Modal. Setzen Sie
data-unread="off", wenn das Modal eine andere Seite öffnet. Andernfalls leuchtet der Punkt bei Changelog-Updates auf, die Besucher dort nicht sehen. - Der schwebende Launcher erscheint nur, wenn Ihr Changelog einen Eintrag enthält (siehe Mit
rss: trueaktivieren). Wenn Ihre Website kein Changelog hat, verknüpfen Sie das Widget überdata-triggermit einem eigenen Element. Ihr Element wird immer angezeigt.
Launchermodi
Ein verknüpftes Element erhält den Ungelesen-Punkt. Das Widget erstellt keine schwebende Schaltfläche; data-position und data-label haben dann keine Wirkung:
<script
src="https://acme.jamdesk.app/_jd/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/changelog"
data-trigger="#whats-new"
async
></script>Modalgröße festlegen
Das Modal wird mit einer Größe von 560 × 680 px geöffnet. Ändern Sie sie mit data-width und data-height. Eine reine Zahl wird als Pixelwert interpretiert. Zulässig sind auch Werte mit px, vw, vh, rem, em oder %:
<script
src="https://acme.jamdesk.app/_jd/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/changelog"
data-width="720px"
data-height="600px"
async
></script>Das Modal ist auf eine Breite von 92vw und eine Höhe von 86vh begrenzt. Auch eine große Größe passt auf ein Smartphone. Ein nicht erkannter Wert wird durch den Standardwert ersetzt. Der standardmäßige Eckenradius beträgt 12 px. Mit data-radius können Sie die Ecken eckiger oder runder gestalten (beliebige CSS-Längenangabe).
Die Launcher-Schaltfläche gestalten
Der schwebende Launcher ist standardmäßig eine dunkle Pillen-Schaltfläche. Ändern Sie ihre Farbe mit data-button-color (Hintergrund) und data-button-text-color (Text). Verwenden Sie einen Hexadezimalwert oder einen CSS-Farbnamen:
<script
src="https://acme.jamdesk.app/_jd/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/changelog"
data-button-color="#4f46e5"
data-button-text-color="#ffffff"
async
></script>Diese beiden Attribute gestalten nur die eigene schwebende Schaltfläche des Widgets. Auf ein über data-trigger verknüpftes Element haben sie keine Wirkung. Dieses Element behält seine eigene Gestaltung.
Den Unread-Punkt anpassen
Der Ungelesen-Punkt ist rot (#e5484d) und standardmäßig aktiviert. Ändern Sie seine Farbe mit data-unread-color (einem Hexadezimalwert oder CSS-Farbnamen). Deaktivieren Sie ihn mit data-unread="off":
<!-- Recolor the dot -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread-color="#7c3aed" async></script>
<!-- Turn the dot off -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread="off" async></script>Wenn Sie den Punkt deaktivieren, bleiben Launcher und Modal erhalten. Nur die Markierung wird entfernt.
Der Unread-Punkt
Das Widget vergleicht die ID des neuesten Eintrags mit einem Wert im localStorage des Browsers (ein Schlüssel pro Projekt). Weichen die Werte voneinander ab, erscheint ein Punkt am Launcher. Beim Öffnen des Modals wird der Eintrag als gesehen markiert. Der Punkt bleibt ausgeblendet, bis das nächste Update veröffentlicht wird.
Der Status wird in localStorage gespeichert – pro Browser und Besucher. Es gibt weder ein Konto noch Tracking. Beim Löschen der Websitedaten wird der Status zurückgesetzt. Besucher sehen den Punkt einmal, wenn sie einen neuen Browser verwenden. Er erscheint wieder, sobald Sie etwas Neues veröffentlichen.
Beispiele
<script
src="https://acme.jamdesk.app/_jd/widget.js"
data-base="https://acme.jamdesk.app"
data-page="/changelog"
data-position="bottom-left"
data-unread-color="#22c55e"
async
></script>Content-Security-Policy
Wenn Ihre Website eine strenge Content-Security-Policy sendet, erlauben Sie Ihren *.jamdesk.app-Ursprung in drei Direktiven. Andernfalls bleibt das Widget ohne sichtbare Wirkung:
Content-Security-Policy:
script-src https://acme.jamdesk.app;
frame-src https://acme.jamdesk.app;
connect-src https://acme.jamdesk.app;
script-srclädtwidget.js.frame-srcrendert das iframe des Modals.connect-srcruft die Changelog-Metadaten für den Ungelesen-Punkt ab.
Bei einer fehlenden Direktive wird kein Fehlerbanner angezeigt. Der Launcher erscheint nicht oder das Modal bleibt leer. Wenn das Widget nicht angezeigt wird, überprüfen Sie die Browserkonsole auf CSP-Verstöße.
Passwortgeschützte Websites
Binden Sie das Widget nicht ein, wenn Ihre Dokumentationswebsite passwortgeschützt ist. Der Entsperrbildschirm gehört auf Ihre *.jamdesk.app-Website, nicht in ein iframe eines Drittanbieters. Beim Einbetten würden Besucher dazu aufgefordert, Ihr Website-Passwort in einem Frame eines anderen Ursprungs einzugeben. Das sieht wie eine Phishing-Aufforderung aus. Verwenden Sie das Widget nur für öffentliche Changelogs.