Zum Inhalt springen

Alle Entwicklerdokumente

Das einbettbare Changelog-Widget

Zwei Zeilen HTML bringen Ihr Changelog, Ihre Roadmap und ein Feedback-Feld in Ihr Produkt. Diese Seite behandelt die Attribute, das Theming, die Beschränkung auf einige Repositories, die Versionierung und die gehostete Seite, auf die das Widget zurückfällt.

Das einbettbare Widget

Wenn Sie lieber nichts bauen möchten, fügen Sie diese zwei Zeilen ein. Das Widget ist ein Custom Element, das in einen Shadow Root rendert und dadurch weder Ihre Styles erbt noch in sie hineinwirkt.

<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
  data-public-id="YOUR_PUBLIC_ID"
  data-api="https://api.changeloop.dev"></changelogapp-widget>

Beide Attribute sind erforderlich. data-public-id ist Ihre Feed-ID, data-api ist der Ursprung, von dem das Widget lädt. Fehlt eines von beiden, schreibt das Element einen Fehler in die Konsole und rendert gar nichts, was das Erste ist, das Sie prüfen sollten, wenn Sie eine leere Stelle sehen, wo es stehen müsste.

Fügen Sie dem Element data-theme="dark" hinzu, um es dunkel zu rendern; Ihre Seite kann das zur Laufzeit umschalten. Für tiefergehendes Styling stellt das Widget CSS Custom Properties (--changelogapp-text, --changelogapp-bg, --changelogapp-accent und weitere) sowie ::part()-Namen bereit, die Sie in Ihrem eigenen Stylesheet setzen. Die App zeigt beide Designs live unter Einstellungen, Öffentlicher Feed.

Fügen Sie data-repos hinzu, um nur einige Ihrer Repositories anzuzeigen, zum Beispiel das Changelog eines Produkts auf der Website dieses Produkts, wenn sich mehrere Produkte ein Konto teilen. Der Wert ist eine kommagetrennte Liste vollständiger Namen, owner/repo; ein Name ohne Besitzer passt auf nichts und rendert einen leeren Feed ohne Fehler. Bis zu zehn Repositories werden berücksichtigt. Ein so eingegrenztes Widget zeigt nur Updates und Feedback, weil die Roadmap keine Ansicht pro Repository hat, und Feedback wird weiterhin dort abgelegt, wohin das Feedback-Ziel Ihres Teams zeigt. Unter Einstellungen, Öffentlicher Feed gibt es eine Auswahl, die das Attribut für Sie schreibt.

Es rendert drei Tabs in dieser Reihenfolge: Updates, Roadmap und Feedback. Die ersten beiden lesen die Feeds von oben. Der dritte sendet an den Endpunkt unten und legt jede Submission-ID im localStorage ab, sodass Besucherinnen und Besucher zurückkommen und sehen können, was aus ihrer Meldung geworden ist.

Das Skript wird versioniert ausgeliefert. /widget.js liefert immer den neuesten Build und wird eine Stunde lang gecacht, sodass ein Release Ihre Besucher erreicht, ohne dass Sie etwas anfassen. /widget-vN.js pinnt einen Build: Sobald eine Versionsnummer ausgeliefert wurde, ändern sich ihre Bytes nie wieder, und sie wird ein Jahr lang gecacht. Pinnen Sie sie, wenn Sie Änderungen lieber bewusst übernehmen.

Laden Sie genau ein Widget-Skript pro Seite

Die beiden URLs sind Alternativen, keine Schichten. Beide registrieren denselben Namen für das Custom Element, und ein Browser lässt einen Namen pro Dokument nur einmal registrieren: Welches Skript zuerst ausgeführt wird, gewinnt für die Lebensdauer der Seite, das zweite bleibt wirkungslos. Eine Seite, die sowohl /widget.js als auch /widget-v5.js trägt, rendert also das, was der Browser zufällig zuerst ausgeführt hat, und das haben Sie nicht in der Hand; /widget-v5.js neben ein vorhandenes /widget.js zu setzen, um die Version zu pinnen, bewirkt gar nichts. Meist gewinnt der ältere Build, weil er schon im Cache liegt.

Wenn das passiert, schreibt das Widget eine Warnung mit beiden Build-Namen in die Konsole, damit Sie nicht raten müssen. Mehr als warnen kann es nicht: Wenn die zweite Kopie läuft, hat die erste den Namen längst beansprucht. Die Lösung ist immer, das Skript-Tag zu ersetzen statt ein weiteres hinzuzufügen, und dasselbe gilt, wenn ein Tag-Manager oder ein Partial eines für Sie einfügt. Um vom rollierenden auf einen gepinnten Build zu wechseln, ändern Sie das src.

Release-Pop-up

Fügen Sie data-mode="popup" hinzu, und das Element rendert keine Tabs. Hat ein Besucher etwas Neues zu sehen, zeigt es eine kleine Karte mit Ihrem neuesten Release, sonst nichts. Bei data-mode spielt die Groß- und Kleinschreibung keine Rolle.

<script src="https://api.changeloop.dev/widget.js" defer></script>
<changelogapp-widget
  data-public-id="YOUR_PUBLIC_ID"
  data-api="https://api.changeloop.dev"
  data-mode="popup"
  data-changelog-url="https://feed.changeloop.dev/feed/YOUR_PUBLIC_ID"></changelogapp-widget>

Auf breiten Bildschirmen sitzt die Karte unten links, weil unten rechts meist ein Chat-Launcher steht. Auf Bildschirmen unter 480px Breite nimmt sie die volle Breite ein und verdeckt einen Chat-Launcher, bis sie geschlossen wird. Sie öffnet sich im Top Layer des Browsers, sodass Overflow, Transform oder z-index eines übergeordneten Elements sie weder abschneiden noch überdecken können. Um sie zu verschieben, gestalten Sie ::part(popup).

Jedes Release wird nur einmal gezeigt. Die Karte erscheint, wenn der Besucher Einträge hat, die er noch nicht gesehen hat. Sie zeigt den neuesten davon, bei mehreren mit einer Anzahl, und zählt sie in dem Moment als gesehen, in dem sie erscheint. Beim nächsten Seitenaufruf erscheint nichts, bis Sie wieder etwas veröffentlichen.

Ein erster Besuch zeigt gar nichts: Das Widget merkt sich nur, wie weit Ihr Changelog reicht, damit bestehende Nutzer an dem Tag, an dem Sie es einbauen, nicht mit alten Nachrichten begrüßt werden. Die Karte startet mit Ihrem nächsten Release. Wer ein Release schon im Inline-Widget gelesen hat, bekommt es nicht noch einmal gezeigt.

Was ein Besucher gesehen hat, wird im localStorage gespeichert, nicht in einem Cookie, und gilt daher nur für einen Browser und einen Seiten-Origin. Dieselbe Person auf einer anderen Ihrer Domains beginnt wieder mit einem ersten Besuch. Blockiert der Browser den Speicher, zählt jeder Besuch als erster Besuch, und die Karte erscheint nie.

data-changelog-url ist optional. Mit einer http- oder https-Adresse erhält die Karte einen Link "See all updates" dorthin, meist auf Ihre gehostete Seite oder Ihre eigene Changelog-Seite. Bei allem anderen wird kein Link angezeigt. data-theme und data-repos funktionieren genau wie beim Inline-Widget.

Die Karte nimmt nie den Fokus und blockiert die Seite nie: Sie ist eine beschriftete Region, kein Dialog. Sie schließt sich mit ihrem Schließen-Button oder mit Escape, solange der Fokus in der Karte liegt. Escape an jeder anderen Stelle Ihrer Seite bleibt Ihrem eigenen Code überlassen.

Die Regel "ein Widget-Skript pro Seite" gilt weiterhin. Pop-up und Inline-Widget können sich eine Seite teilen: Laden Sie das Skript einmal und fügen Sie beide Elemente hinzu, dann stimmen sie darin überein, was der Besucher schon gesehen hat.

Gepinnte Builds bis einschließlich /widget-v18.js sind älter als das Pop-up. Sie ignorieren data-mode und rendern stattdessen die Inline-Tabs. Verwenden Sie daher /widget.js oder einen neueren gepinnten Build.

In der App finden Sie unter Einstellungen, Öffentlicher Feed dieses Snippet zum Kopieren, mit Ihrer Feed-ID, Ihrem Design und Ihrem Repository-Umfang bereits eingetragen. Aufrufe der Karte und Klicks auf ihren Link "Learn more" erscheinen unter Analytics als eigene Zahlen.

Emoji-Reaktionen

Leserinnen und Leser können auf einen Eintrag reagieren, ohne etwas zu schreiben. Sind Reaktionen aktiv, endet jeder Eintrag mit einer Reihe aus fünf Emojis, 👍 🎉 ❤️ 🚀 👀, jeweils mit ihrer Anzahl. Die Reihe erscheint im Inline-Widget, auf der Karte des Release-Pop-ups und auf der gehosteten Feed-Seite.

Reaktionen sind aus, bis Sie sie in der App unter Einstellungen, Öffentlicher Feed einschalten. Ihr Embed-Code ändert sich dabei nicht: Das Widget liest den Schalter aus Ihrem Feed, die Reihe erscheint und verschwindet also mit ihm. Schalten Sie Reaktionen aus, wird die Reihe ausgeblendet, die Zähler bleiben aber erhalten und sind wieder da, sobald Sie sie erneut einschalten. Gepinnte Builds aus der Zeit vor den Reaktionen zeigen die Reihe nie.

Jede Person kann jeden Eintrag mit jeder Reaktion einmal versehen, und ein erneuter Klick nimmt sie zurück. Das Widget unterscheidet Leser an einer zufälligen ID, die es beim ersten Klick im Browser erzeugt, nicht an einem Konto oder einer E-Mail-Adresse. Wir speichern nur einen Hash dieser ID in Kombination mit Ihrem Team, sodass derselbe Browser auf zwei verschiedenen Changelogs unzusammenhängende Hashes hinterlässt.

Die Zähler sind nur eine Annäherung: ein freundliches Signal, keine Abstimmung. Wer den Browser-Speicher leert oder ein privates Fenster öffnet, kann erneut reagieren, stützen Sie daher keine wichtige Entscheidung darauf. Die Zähler in Ihrem Feed können außerdem einige Minuten nachgehen, weil der Feed zwischengespeichert wird, die Person, die klickt, sieht ihre eigene Reaktion aber sofort mitgezählt. In der App zeigt der Tab Veröffentlicht des Review-Postfachs die Gesamtzahl pro Eintrag.

Beim Reagieren werden zwei Dinge im localStorage des Besuchers abgelegt, nie in einem Cookie. changelogapp-widget:reader-id enthält die zufällige ID, eine pro Browser und Seiten-Origin. changelogapp-widget:reactions: gefolgt von Ihrer Feed-ID enthält die Reaktionen, die dieser Browser gewählt hat, für bis zu 200 Einträge, nämlich die, auf die zuletzt reagiert wurde. Die gehostete Seite legt dieselben beiden unter ihrer eigenen Adresse ab. Blockiert der Browser den Speicher, funktioniert das Reagieren für diesen Seitenaufruf trotzdem und wird danach nicht gemerkt.

Um die Reihe zu gestalten, verwenden Sie ::part(reactions), ::part(reaction) für jeden Button und ::part(reaction-count) für dessen Zahl, alle weiter unten unter Gestaltung aufgeführt. Bei einem Zähler von null wird keine Zahl angezeigt. Ein gedrückter Button trägt aria-pressed="true" und wird mit einem Ring in Ihrer --changelogapp-accent-Farbe und fettem Text dargestellt. ::part() kann nicht nach diesem Attribut auswählen, setzen Sie daher --changelogapp-accent, um das Aussehen eines gedrückten Buttons zu ändern.

Öffentliches Feedback-Board

Mit dem Board sehen Leserinnen und Leser, was sich andere wünschen, und können dafür abstimmen. Ist das Board aktiv, öffnet sich der Tab Feedback mit Ihren meistgewählten Wünschen samt Status, und das gewohnte Formular steht darunter.

Das Board ist aus, bis Sie es in der App unter Einstellungen, Öffentlicher Feed einschalten. Ihr Embed-Code ändert sich dabei nicht: Das Widget liest den Schalter aus Ihrem Feed. Schalten Sie das Board aus, wird es ausgeblendet, Ihre Wünsche und deren Stimmen bleiben aber erhalten. Es liegt im Tab Feedback, ein Widget ohne Tab Feedback zeigt also auch kein Board.

Das Board zeigt nur, was Sie selbst schreiben. Das Feedback eines Besuchers landet nie von allein darauf: Sie entscheiden, welche Wünsche aufs Board kommen, und verfassen Titel und Beschreibung jedes Wunsches selbst, auf der Seite Feedback-Board in der App. Sie können einen Wunsch aus einer Nachricht eines Besuchers heraus anlegen oder eine eigene Idee eintragen, und das Board zeigt weder die Nachricht des Besuchers noch seine E-Mail-Adresse. Das Board zeigt Ihre 100 wichtigsten Wünsche, ein Team kann bis zu 500 führen.

Jeder Wunsch hat einen von fünf Status: In Prüfung, Geplant, In Arbeit, Ausgeliefert oder Abgelehnt. Verknüpfen Sie einen Wunsch mit einem Update, wechselt er von selbst auf Ausgeliefert, sobald dieses Update veröffentlicht wird, oder sofort, wenn es schon veröffentlicht ist. Auch ein Wunsch, den Sie aus einer Nachricht eines Besuchers angelegt haben, wechselt auf Ausgeliefert, sobald ein Update veröffentlicht wird, das diese Nachricht umsetzt.

Jeder Browser hat pro Wunsch und Website eine Stimme, und ein erneuter Klick nimmt sie zurück. Die Abstimmung endet, sobald ein Wunsch Ausgeliefert oder Abgelehnt ist, wer bereits abgestimmt hat, kann seine Stimme aber weiterhin zurücknehmen. Stimmen sind ein Signal, keine Zählung von Personen: Wer den Browser-Speicher leert oder ein privates Fenster öffnet, kann erneut abstimmen. Nutzen Sie sie daher, um zu sehen, was die Leute bewegt, und nie, um eine wichtige Entscheidung zu treffen. Die Zahlen, die andere Besucher sehen, können etwas nachgehen, während die abstimmende Person sofort die genaue neue Zahl sieht.

Beim Abstimmen werden zwei Dinge im localStorage des Besuchers abgelegt, nie in einem Cookie. changelogapp-widget:votes: gefolgt von Ihrer Feed-ID enthält die Wünsche, für die dieser Browser abgestimmt hat, bis zu den 200 zuletzt gewählten. changelogapp-widget:reader-id ist die zufällige ID, die auch die Reaktionen verwenden, eine pro Browser und Seiten-Origin. Wer bereits reagiert hat, erzeugt durch das Abstimmen also nichts Neues. Wir speichern nur einen Hash dieser ID in Kombination mit Ihrem Team, nie die ID selbst, sodass derselbe Browser auf zwei verschiedenen Changelogs unzusammenhängende Hashes hinterlässt. Die IP-Adresse des Besuchers speichern wir nicht zusammen mit einer Stimme. Blockiert der Browser den Speicher, funktioniert das Abstimmen für diesen Seitenaufruf trotzdem und wird danach nicht gemerkt.

Im Release-Pop-up erscheint das Board nie, und auch nicht in einem Widget mit data-repos, weil es Ihr gesamtes Team abdeckt. Ihre gehostete Changelog-Seite hat einen Tab Requests mit demselben Board, einem Filter nach Status und Stimmen, die genauso zählen. Das Board gibt es außerdem als öffentliches JSON unter GET /v1/public/YOUR_PUBLIC_ID/board.json auf derselben API. Solange das Board aus ist, antwortet der Endpunkt mit 404.

Um das Board zu gestalten, verwenden Sie ::part(board) für den ganzen Block und ::part(board-heading) für seine Überschrift, dazu die Parts jedes Wunsches, alle weiter unten unter Gestaltung aufgeführt. Der Abstimm-Button, ::part(board-vote), trägt aria-pressed="true", sobald dieser Browser abgestimmt hat, und wird dann mit einem Ring in Ihrer --changelogapp-accent-Farbe dargestellt. ::part() kann nicht nach diesem Attribut auswählen, setzen Sie daher --changelogapp-accent, um das Aussehen einer gezählten Stimme zu ändern.

Gestaltung

Das Widget rendert in einen Shadow Root, daher erreicht der Großteil Ihres Stylesheets sein Inneres nicht. Vererbte Eigenschaften fließen trotzdem hinein, wo das Widget keine eigenen setzt, ebenso die folgenden Custom Properties, die Sie am Element oder an einem übergeordneten Element setzen. Für alles andere nutzen Sie die ::part()-Namen weiter unten. Beide Listen sind eine stabile Schnittstelle: Ein einmal ausgelieferter Name wird nie umbenannt.

Custom Properties

  • --changelogapp-font-family
  • --changelogapp-text
  • --changelogapp-text-muted
  • --changelogapp-bg
  • --changelogapp-border
  • --changelogapp-accent
  • --changelogapp-radius
  • --changelogapp-space
  • --changelogapp-timeline-line
  • --changelogapp-pill-bg
  • --changelogapp-pill-text

Tag-Pills. Ein Tag mit Farbe verwendet sie als Hintergrund, und in beiden Designs wird die Textfarbe so gewählt, dass sie auf diesem Hintergrund lesbar ist, mit mindestens 4.5:1. Weiß wird bevorzugt, wann immer es dieses Verhältnis erreicht. Eine Farbe, die das Widget nicht als einfachen RGB-Wert lesen kann, bekommt keine gewählte Textfarbe und behält den Standard des Designs. Wenn Sie die Textfarbe in einem der beiden Designs selbst bestimmen möchten, setzen Sie --changelogapp-pill-text. Eine ::part(entry-tag)-Regel hat Vorrang vor allem anderen: Setzen Sie dort einen Hintergrund, setzen Sie auch color. --changelogapp-pill-bg ist der Hintergrund eines Tags ohne Farbe. Gepinnte Builds bis /widget-v18.js behalten im hellen Design weißen Pilltext.

Parts

  • Changelog-Einträge: month-heading, entry, entry-date, entry-tag, entry-title, entry-body, entry-link, timeline-dot, entry-image, entry-header-image
  • Im Textkörper eines Eintrags: entry-body-heading, entry-body-paragraph, entry-body-list, entry-body-list-item, entry-body-link, entry-body-code
  • Die Anzahl ungelesener Einträge am Tab Updates: unread-badge
  • Das Release-Pop-up: popup, popup-heading, popup-close, popup-link
  • Das Formular "Get updates by email" oben im Tab Updates, wenn E-Mail-Abonnenten aktiviert sind (Team-Plan): subscribe, subscribe-heading, subscribe-input, subscribe-button, subscribe-status
  • Emoji-Reaktionen, wenn sie aktiviert sind: reactions, reaction, reaction-count
  • Das öffentliche Feedback-Board, wenn es eingeschaltet ist: board, board-heading, board-request, board-request-title, board-request-description, board-request-status, board-request-link, board-vote, board-vote-count

Content-Security-Policy

Wenn Ihre Seite einen Content-Security-Policy-Header sendet, braucht das Widget den API-Origin in zwei Direktiven. script-src lässt das Skript laden. connect-src lässt es Ihren Changelog lesen, Feedback senden und Aufrufe erfassen. Mit nur der ersten erscheint das Element und bleibt dann leer, was eher nach einem kaputten Feed aussieht als nach einer blockierten Anfrage. Das Pop-up braucht dieselben zwei.

script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;

Ab Widget 0.16.0, das /widget.js ausliefert, brauchen aktuelle Browser keine style-src-Änderung: Das Widget übergibt seine Styles als Constructed Stylesheet, das style-src nicht regelt. Ältere Builds, darunter gepinnte Builds bis /widget-v18.js, und Browser ohne Constructable Stylesheets verwenden stattdessen ein style-Element, und das braucht style-src 'unsafe-inline'.

img-src brauchen Sie nur, wenn Sie Bilder in der App unter Einstellungen, Öffentlicher Feed, Bilder eingeschaltet haben. Das Widget lädt Grafiken dann direkt von Ihren Bild-Hosts, und eine Policy, die diese nicht aufführt, blockiert jede einzelne. Die Einstellungen zeigen die genaue Zeile mit img-src, ausgefüllt aus Ihrer Liste, kopieren Sie sie also erneut, wann immer Sie die Liste ändern. Die Screenshot-Hosts von GitHub brauchen außerdem https://github-production-user-asset-6210df.s3.amazonaws.com in img-src, weil ein GitHub-Screenshot-Link dorthin weiterleitet und der Browser auch diese Adresse prüft.

Wenn Ihre Policy nur default-src setzt, fügen Sie beide Direktiven hinzu und wiederholen Sie Ihre default-src-Quellen in jeder davon. Ein script-src oder connect-src ersetzt default-src für Skripte bzw. Verbindungen, sodass Ihre eigenen Quellen blockiert würden, wenn Sie sie weglassen.

Ergänzen Sie den Origin in Ihren bestehenden Direktiven, statt sie zu ersetzen. Unter Einstellungen, Öffentlicher Feed in der App sehen Sie diese Zeile mit dem richtigen Origin für Ihr Konto. Wenn Sie diesen Header nicht senden, ist nichts zu tun.

Die gehostete Feed-Seite

Unter dieser Adresse hosten wir auch eine schlichte Seite: Ihr Changelog und Ihr Roadmap-Board, gerendert aus denselben beiden Feeds von oben. Sie braucht keine Anmeldung und auf Ihrer Seite keine Einrichtung. Dorthin schicken wir auch Menschen zurück, sobald sich eine Schleife schließt: Der Shipped-Kommentar, den wir an einem GitHub-Issue hinterlassen, verlinkt hierher, ebenso shippedEntry.link aus der Statusabfrage oben, und beide landen auf dem ausgelieferten Eintrag mit eigenem #entry-ID-Anker, der den Eintrag auch dann noch findet, wenn er inzwischen auf eine spätere Seite gerutscht ist.

Betrachten Sie sie als Rückfalloption, nicht als die Integration. Der Changelog-Feed und das Widget bleiben der Weg, das in Ihre eigene Website zu bringen, sodass es nach Ihrem Produkt aussieht und nicht nach unserem; diese Seite ist für die Zeit davor da und für Loop-Close-Links, die unabhängig davon hierher zeigen, was Sie sonst gebaut haben.

Ihr Changelog, in Ihrem Produkt

Changeloop entwirft jeden Eintrag aus einem gemergten Pull Request, hält ihn für Ihre Prüfung zurück und liefert ihn an dieses Widget und an einen JSON-Feed. Kostenlos für ein Repository, ohne Karte.

Kostenlos starten

Zur Entwicklerdokumentation