De insluitbare widget
Als je liever niets bouwt, voeg dan deze twee regels toe. De widget is een custom element dat rendert in een shadow root, waardoor het je stijlen niet overneemt en er ook niet in lekt.
<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 attributen zijn verplicht. data-public-id is je feed-id, data-api is de oorsprong waarvandaan de widget laadt. Ontbreekt een van beide, dan schrijft het element een fout naar de console en rendert het helemaal niets, wat het eerste is om te controleren als je een lege ruimte ziet waar het zou moeten staan.
Voeg data-theme="dark" toe aan het element voor een donkere weergave; je pagina kan dit tijdens runtime omschakelen. Voor verdere styling stelt de widget CSS custom properties (--changelogapp-text, --changelogapp-bg, --changelogapp-accent en meer) en ::part()-namen beschikbaar, die je in je eigen stylesheet instelt. De app toont beide thema's live onder Instellingen, Publieke feed.
Voeg data-repos toe om slechts een deel van je repositories te tonen, bijvoorbeeld de changelog van één product op de site van dat product wanneer meerdere producten één account delen. De waarde is een door komma's gescheiden lijst van volledige namen, owner/repo; een naam zonder eigenaar komt nergens mee overeen en toont een lege feed zonder foutmelding. Maximaal tien repositories worden meegenomen. Een zo afgebakende widget toont alleen Updates en Feedback, omdat de roadmap geen weergave per repository heeft, en feedback wordt nog steeds ingediend waar het feedbackdoel van je team naar wijst. Onder Instellingen, Openbare feed staat een kiezer die het attribuut voor je schrijft.
Het rendert drie tabbladen in deze volgorde: Nieuws, Roadmap en Feedback. De eerste twee lezen de feeds hierboven. De derde stuurt naar het endpoint hieronder en bewaart elke verzend-id in localStorage, zodat een bezoeker kan terugkomen en zien wat er is gebeurd met wat hij heeft verzonden.
Het script wordt versied aangeboden. /widget.js levert altijd de nieuwste build en wordt een uur gecachet, zodat een release je bezoekers bereikt zonder dat je iets hoeft aan te raken. /widget-vN.js zet één build vast: zodra een versienummer is aangeboden, veranderen de bytes ervan nooit meer, en het wordt een jaar gecachet. Zet het vast als je wijzigingen liever bewust doorvoert.
Laad precies één widgetscript per pagina
De twee URL's zijn alternatieven, geen lagen. Beide registreren dezelfde naam voor het custom element, en een browser laat een naam maar één keer per document registreren: welk script het eerst wordt uitgevoerd, wint, voor de hele levensduur van de pagina, en het tweede blijft inert. Een pagina met zowel /widget.js als /widget-v5.js rendert dus wat de browser toevallig als eerste heeft uitgevoerd, en dat heb je niet in de hand; /widget-v5.js naast een bestaande /widget.js zetten om de versie vast te leggen doet helemaal niets. Meestal wint de oudere build, omdat die al in de cache zit.
Als dat gebeurt, schrijft de widget een waarschuwing naar de console met beide buildnamen, zodat je niet hoeft te raden. Meer dan waarschuwen kan het niet: tegen de tijd dat de tweede kopie draait, heeft de eerste de naam al in bezit. De oplossing is altijd de scripttag te vervangen in plaats van er nog een toe te voegen, en hetzelfde geldt als een tagmanager of een partial er een voor je injecteert. Om van de doorlopende build naar een vastgezette over te stappen, wijzig je de src.
Release-pop-up
Voeg data-mode="popup" toe en het element rendert geen tabbladen. Als een bezoeker iets nieuws te zien heeft, toont het één kleine kaart met je nieuwste release, en anders helemaal niets. data-mode is niet hoofdlettergevoelig.
<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>
Op brede schermen staat de kaart linksonder, omdat de rechterbenedenhoek meestal van een chatknop is. Op schermen smaller dan 480px beslaat hij de volle breedte en bedekt hij een chatknop totdat hij wordt gesloten. Hij opent in de bovenste laag van de browser (top layer), dus de overflow, transform of z-index van een bovenliggend element kan hem niet afknippen of begraven. Om hem te verplaatsen, style je ::part(popup).
Elke release wordt één keer getoond. De kaart verschijnt als de bezoeker items heeft die hij nog niet heeft gezien. Hij toont het nieuwste daarvan, met een teller als het er meer zijn, en telt ze als gezien zodra hij verschijnt. Bij het volgende laden van de pagina verschijnt er niets totdat je opnieuw publiceert.
Een eerste bezoek toont helemaal niets: de widget noteert alleen hoe ver je changelog reikt, zodat bestaande gebruikers op de dag dat je hem toevoegt niet worden verwelkomd met oud nieuws. De kaart begint bij je volgende release. Een bezoeker die een release al in de inline widget heeft gelezen, krijgt hem niet nog eens te zien.
Wat een bezoeker heeft gezien, wordt bewaard in localStorage en niet in een cookie, dus het hoort bij één browser en één site-origin. Dezelfde persoon op een ander van je domeinen begint weer bij een eerste bezoek. Als de browser opslag blokkeert, telt elk bezoek als een eerste bezoek en verschijnt de kaart nooit.
data-changelog-url is optioneel. Bij een http- of https-adres krijgt de kaart een link "See all updates" naar dat adres, meestal je gehoste pagina of je eigen changelogpagina. Bij iets anders wordt er geen link getoond. data-theme en data-repos werken precies zoals bij de inline widget.
De kaart pakt nooit de focus en blokkeert de pagina nooit: het is een benoemd gebied, geen dialoogvenster. Hij sluit met zijn sluitknop, of met Escape zolang de focus binnen de kaart is. Escape op de rest van je pagina blijft aan je eigen code overgelaten.
De regel van één widgetscript per pagina blijft gelden. De pop-up en de inline widget kunnen samen op een pagina staan: laad het script één keer en voeg beide elementen toe, dan zijn ze het eens over wat de bezoeker al heeft gezien.
Vastgezette builds tot en met /widget-v18.js zijn ouder dan de pop-up. Ze negeren data-mode en renderen in plaats daarvan de inline tabbladen, dus gebruik /widget.js of een nieuwere vastgezette build.
In de app staat onder Instellingen, Publieke feed dit fragment klaar om te kopiëren, met je feed-id, thema en repositoryselectie al ingevuld. Weergaven van de kaart en klikken op de link "Learn more" verschijnen onder Analytics als eigen cijfers.
Emoji-reacties
Lezers kunnen op een item reageren zonder iets te schrijven. Met reacties aan eindigt elk item met een rij van vijf emoji, 👍 🎉 ❤️ 🚀 👀, elk met zijn teller. De rij verschijnt in de inline widget, op de kaart van de release-pop-up en op de gehoste feedpagina.
Reacties staan uit totdat je ze in de app aanzet, onder Instellingen, Publieke feed. Je embedcode verandert niet: de widget leest de schakelaar uit je feed, dus de rij verschijnt en verdwijnt mee. Als je reacties uitzet, verdwijnt de rij maar blijven de tellers bewaard, zodat ze terugkomen als je ze weer aanzet. Vastgezette builds van vóór de reacties tonen de rij nooit.
Elke lezer kan een item elke reactie één keer geven, en door er nog eens op te drukken haal je hem weer weg. De widget onderscheidt lezers aan de hand van een willekeurig id dat hij bij de eerste klik in de browser aanmaakt, niet via een account of e-mailadres. Wij bewaren alleen een hash van dat id in combinatie met je team, dus dezelfde browser laat op twee verschillende changelogs niet aan elkaar te koppelen hashes achter.
De tellers zijn bij benadering: een vriendelijk signaal, geen stemming. Wie de opslag van de browser wist of een privévenster opent, kan opnieuw reageren, dus baseer nooit een belangrijke beslissing erop. De tellers in je feed kunnen ook een paar minuten achterlopen, omdat de feed in de cache staat, maar wie klikt ziet zijn eigen reactie meteen meegeteld. In de app toont het tabblad Gepubliceerd van de inbox het totaal per item.
Reageren bewaart twee dingen in de localStorage van de bezoeker, nooit in een cookie. changelogapp-widget:reader-id bevat het willekeurige id, één per browser en site-origin. changelogapp-widget:reactions: gevolgd door je feed-id bevat de reacties die deze browser heeft gekozen, voor maximaal 200 items, de items waarop het laatst is gereageerd. De gehoste pagina bewaart dezelfde twee onder haar eigen adres. Als de browser opslag blokkeert, werkt reageren nog steeds voor die paginaweergave, maar wordt het daarna niet onthouden.
Om de rij te stylen gebruik je ::part(reactions), ::part(reaction) voor elke knop en ::part(reaction-count) voor het getal, allemaal vermeld onder Styling hieronder. Bij een telling van nul wordt geen getal getoond. Een ingedrukte knop heeft aria-pressed="true" en wordt getekend met een ring in je --changelogapp-accent-kleur en vetgedrukte tekst. ::part() kan niet op dat attribuut selecteren, dus stel --changelogapp-accent in om te veranderen hoe een ingedrukte knop eruitziet.
Openbaar feedbackbord
Met het bord kunnen lezers zien waar anderen om hebben gevraagd en erop stemmen. Als het bord aanstaat, opent het tabblad Feedback met je meest gestemde verzoeken, elk met zijn status, en daaronder staat het gebruikelijke formulier.
Het bord staat uit totdat je het in de app aanzet, onder Instellingen, Publieke feed. Je embedcode verandert niet: de widget leest de schakelaar uit je feed. Als je het bord uitzet, verdwijnt het maar blijven je verzoeken en hun stemmen bewaard. Het zit in het tabblad Feedback, dus een widget zonder tabblad Feedback toont ook geen bord.
Het bord toont alleen wat jij schrijft. De feedback van een bezoeker komt er nooit uit zichzelf op: jij bepaalt welke verzoeken op het bord komen en schrijft van elk zelf de titel en de beschrijving, op de pagina Feedbackbord in de app. Je kunt een verzoek beginnen vanuit een bericht van een bezoeker of zelf een idee plaatsen, en het bord toont nooit het bericht of het e-mailadres van de bezoeker. Het bord toont je top 100 van verzoeken, en een team kan er maximaal 500 bewaren.
Elk verzoek heeft een van vijf statussen: Onder overweging, Gepland, In uitvoering, Uitgebracht of Afgewezen. Koppel je een verzoek aan een update, dan gaat het vanzelf naar Uitgebracht zodra die update wordt gepubliceerd, of meteen als dat al is gebeurd. Een verzoek dat je bent begonnen vanuit het bericht van een bezoeker gaat ook naar Uitgebracht zodra een update wordt gepubliceerd die dat bericht oplevert.
Elke browser heeft per site één stem per verzoek, en nog eens klikken haalt die weer weg. Stemmen sluit zodra een verzoek Uitgebracht of Afgewezen is, al kan wie al heeft gestemd zijn stem nog steeds intrekken. Stemmen zijn een signaal, geen telling van personen: wie de opslag van de browser wist of een privévenster opent, kan opnieuw stemmen. Gebruik ze dus om te zien waar mensen om geven, nooit om een belangrijke beslissing mee te nemen. De aantallen die andere bezoekers zien kunnen iets achterlopen, terwijl de bezoeker die stemt meteen het exacte nieuwe aantal ziet.
Stemmen bewaart twee dingen in de localStorage van de bezoeker, nooit in een cookie. changelogapp-widget:votes: gevolgd door je feed-id somt de verzoeken op waarop deze browser heeft gestemd, tot de 200 meest recente. changelogapp-widget:reader-id is het willekeurige id dat ook de reacties gebruiken, één per browser en site-origin, dus stemmen maakt niets nieuws aan als de bezoeker al heeft gereageerd. Wij bewaren alleen een hash van dat id in combinatie met je team, nooit het id zelf, dus dezelfde browser laat op twee verschillende changelogs niet te koppelen hashes achter. Het IP-adres van de bezoeker bewaren we niet bij een stem. Als de browser opslag blokkeert, werkt stemmen nog wel voor die paginaweergave, maar wordt het daarna niet onthouden.
Het bord verschijnt nooit in de release-pop-up, en ook niet in een widget met data-repos, omdat het je hele team omvat. Je gehoste changelogpagina heeft een tabblad Verzoeken met hetzelfde bord, een filter op status en stemmen die op dezelfde manier tellen. Het bord is ook openbare JSON, op GET /v1/public/YOUR_PUBLIC_ID/board.json van dezelfde API, die 404 antwoordt zolang het bord uitstaat.
Om het bord te stylen gebruik je ::part(board) voor het hele blok en ::part(board-heading) voor de kop, en daarna de parts van elk verzoek, allemaal vermeld onder Styling hieronder. De stemknop, ::part(board-vote), heeft aria-pressed="true" zodra deze browser heeft gestemd en wordt dan getekend met een ring in je --changelogapp-accent-kleur. ::part() kan niet op dat attribuut selecteren, dus stel --changelogapp-accent in om te veranderen hoe een meegeteld stem eruitziet.
Styling
De widget rendert in een shadow root, dus het grootste deel van je stylesheet reikt er niet in. Overgeërfde eigenschappen komen er nog wel in waar de widget er zelf geen instelt, en dat geldt ook voor de onderstaande custom properties, ingesteld op het element of op een voorouder. Gebruik voor al het andere de ::part()-namen hieronder. Beide lijsten vormen een stabiele interface: een naam die eenmaal is uitgebracht, wordt nooit hernoemd.
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. Een tag met een kleur gebruikt die als achtergrond, en in beide thema's wordt de tekstkleur zo gekozen dat hij leesbaar is op die achtergrond, met 4.5:1 of beter. Wit heeft de voorkeur zodra dat wordt gehaald. Een kleur die de widget niet als effen RGB-waarde kan lezen, krijgt geen gekozen tekstkleur en houdt de standaard van het thema. Om de tekstkleur zelf te kiezen, in beide thema's, stel je --changelogapp-pill-text in. Een ::part(entry-tag)-regel wint van alles, dus als je daar een achtergrond instelt, stel dan ook color in. --changelogapp-pill-bg is de achtergrond van een tag zonder kleur. Vastgezette builds tot en met /widget-v18.js houden in het lichte thema witte tekst op de pills.
Parts
- Changelog-items:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - Binnen de tekst van een item:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - De teller met ongelezen items op het tabblad Updates:
unread-badge - De release-pop-up:
popup,popup-heading,popup-close,popup-link - Het formulier "Get updates by email", bovenaan Updates wanneer e-mailabonnees zijn ingeschakeld (Team-pakket):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Emoji-reacties, wanneer ze zijn ingeschakeld:
reactions,reaction,reaction-count - Het openbare feedbackbord, wanneer het is ingeschakeld:
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
Als je site een Content-Security-Policy-header verstuurt, heeft de widget de API-origin nodig in twee directives. script-src laat het script laden. connect-src laat het je changelog lezen, feedback versturen en weergaven registreren. Met alleen de eerste verschijnt het element en blijft het daarna leeg, wat eruitziet als een kapotte feed in plaats van een geblokkeerd verzoek. De pop-up heeft dezelfde twee nodig.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;Vanaf widget 0.16.0, die /widget.js serveert, hebben actuele browsers geen wijziging aan style-src nodig: de widget levert zijn stijlen aan als een constructed stylesheet, waar style-src geen zeggenschap over heeft. Oudere builds, waaronder vastgezette builds tot en met /widget-v18.js, en browsers zonder constructable stylesheets gebruiken in plaats daarvan een style-element, en dat vereist style-src 'unsafe-inline'.
img-src is alleen nodig als je in de app afbeeldingen hebt aangezet, onder Instellingen, Publieke feed, Afbeeldingen. De widget laadt afbeeldingen dan rechtstreeks van je afbeeldingshosts, en een beleid dat die niet vermeldt, blokkeert ze allemaal. Instellingen toont de exacte regel met img-src al ingevuld vanuit je lijst, dus kopieer hem opnieuw telkens als je de lijst wijzigt. De screenshothosts van GitHub hebben ook https://github-production-user-asset-6210df.s3.amazonaws.com in img-src nodig, omdat een screenshotlink van GitHub daarheen doorverwijst en de browser dat adres ook controleert.
Als je beleid alleen default-src instelt, voeg dan beide directives toe en herhaal je default-src-bronnen in elk ervan. Een script-src of connect-src vervangt default-src voor scripts of verbindingen, dus als je je eigen bronnen weglaat, worden ze geblokkeerd.
Voeg de origin toe aan je bestaande directives in plaats van ze te vervangen. Onder Instellingen, Publieke feed in de app staat deze regel met de juiste origin voor jouw account. Als je die header niet verstuurt, hoef je niets te doen.
De gehoste feedpagina
Op datzelfde adres hosten we ook een gewone pagina: je changelog en je roadmap-bord, gerenderd vanuit dezelfde twee feeds hierboven. Er is geen inloggen of instellen aan jouw kant voor nodig. Het is ook waar we mensen naar terugsturen zodra een lus zich sluit: de Shipped-reactie die we op een GitHub-issue plaatsen, linkt hierheen, net als shippedEntry.link uit de statuscontrole hierboven, beide belanden ze op het uitgeleverde item met zijn eigen #entry-ID-anker, dat het item nog steeds vindt zelfs als het inmiddels naar een latere pagina is verplaatst.
Behandel het als een terugvaloptie, niet als de integratie. De changelog-feed en de widget blijven de manier om dit in je eigen site te zetten zodat het aanvoelt als jouw product en niet als het onze; deze pagina is bedoeld voor de periode voordat je dat hebt gedaan, en voor loop-close-links, die hierheen wijzen ongeacht wat je verder hebt gebouwd.
Je changelog, in je product
Changeloop stelt elke entry op uit een gemergede pull request, houdt hem vast voor jouw review en levert hem aan deze widget en aan een JSON-feed. Gratis voor één repository, zonder kaart.
Gratis starten