Widgetul încorporabil
Dacă preferi să nu construiești nimic, adaugă aceste două linii. Widgetul este un custom element care se randează într-un shadow root, deci nu îți moștenește stilurile și nici nu se scurge în ele.
<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>
Ambele atribute sunt obligatorii. data-public-id este ID-ul feedului tău, data-api este originea de la care widgetul preia date. Dacă lipsește oricare, elementul scrie o eroare în consolă și nu randează nimic, ceea ce este primul lucru de verificat dacă vezi un spațiu gol acolo unde ar trebui să fie.
Adaugă data-theme="dark" pe element pentru o randare întunecată; pagina ta o poate comuta în timpul rulării. Pentru o stilizare mai fină, widgetul expune proprietăți CSS personalizate (--changelogapp-text, --changelogapp-bg, --changelogapp-accent și altele) și nume ::part(), pe care le setezi în propria foaie de stil. Aplicația previzualizează ambele teme în timp real în Setări, Feed public.
Adaugă data-repos ca să afișezi doar o parte dintre repository-uri, de exemplu changelog-ul unui produs pe site-ul acelui produs atunci când mai multe produse împart un singur cont. Valoarea este o listă de nume complete owner/repo separate prin virgulă; un nume fără proprietar nu se potrivește cu nimic și afișează un flux gol, fără eroare. Sunt luate în calcul cel mult zece repository-uri. Un widget restrâns astfel afișează doar Updates și Feedback, pentru că roadmap-ul nu are o vedere per repository, iar feedback-ul se înregistrează în continuare acolo unde indică ținta de feedback a echipei tale. În Setări, Flux public există un selector care scrie atributul pentru tine.
Randează trei file în această ordine: Updates, Roadmap și Feedback. Primele două citesc feedurile de mai sus. A treia trimite către endpointul de mai jos și păstrează ID-ul fiecărei trimiteri în localStorage, deci un vizitator se poate întoarce și vedea ce s-a întâmplat cu ce a trimis.
Scriptul este servit versionat. /widget.js servește mereu cel mai nou build și este pus în cache pentru o oră, deci o lansare ajunge la vizitatorii tăi fără să atingi nimic. /widget-vN.js fixează un build: odată ce un număr de versiune a fost servit, octeții lui nu se mai schimbă niciodată, și este pus în cache pentru un an. Fixează-l dacă preferi să adopți modificările intenționat.
Încarcă exact un script de widget per pagină
Cele două URL-uri sunt alternative, nu straturi. Ambele înregistrează același nume de custom element, iar un browser permite ca un nume să fie înregistrat o singură dată per document: oricare script se execută primul câștigă, pe durata de viață a paginii, iar al doilea devine inert. Deci o pagină care conține atât /widget.js cât și /widget-v5.js randează pe oricare l-a executat browser-ul primul, ceea ce nu este ceva ce controlezi, iar adăugarea /widget-v5.js lângă un /widget.js existent pentru a fixa versiunea nu face nimic.
Când se întâmplă asta, widgetul scrie un avertisment în consolă care numește ambele build-uri, deci nu rămâi să ghicești. Nu poate face mai mult decât să avertizeze: până când a doua copie se execută, prima a revendicat deja numele. Soluția este mereu să înlocuiești tagul de script în loc să adaugi altul, și la fel se aplică dacă un manager de taguri sau un fragment îl inserează pentru tine. Pentru a trece de la build-ul continuu la unul fixat, schimbă src-ul.
Pop-up de lansare
Adaugă data-mode="popup" și elementul nu mai afișează file. Când un vizitator are ceva nou de văzut, apare un singur card mic cu ultima ta lansare, iar altfel nu apare nimic. data-mode nu ține cont de majuscule.
<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>
Pe ecranele late, cardul stă în colțul din stânga jos, pentru că în colțul din dreapta jos se află de obicei un buton de chat. Pe ecranele mai înguste de 480px se întinde pe toată lățimea și acoperă butonul de chat până când este închis. Se deschide în top layer-ul browserului, așa că overflow, transform sau z-index ale unui element părinte nu îl pot tăia sau îngropa. Ca să îl muți, stilizează ::part(popup).
Fiecare lansare este afișată o singură dată. Cardul apare când vizitatorul are intrări pe care nu le-a văzut încă. Îl arată pe cea mai nouă dintre ele, cu un număr când sunt mai multe, și le socotește văzute chiar în clipa în care apare. La următoarea încărcare a paginii nu se afișează nimic până publici din nou.
O primă vizită nu afișează nimic: widgetul doar notează până unde ajunge changelog-ul tău, ca utilizatorii existenți să nu fie întâmpinați cu vești vechi chiar în ziua în care îl adaugi. Cardul începe cu următoarea ta lansare. Un vizitator care a citit deja o lansare în widgetul inline nu o mai vede din nou.
Ce a văzut un vizitator se păstrează în localStorage, nu într-un cookie, deci ține de un singur browser și de o singură origine de site. Aceeași persoană, pe un alt domeniu al tău, o ia de la o primă vizită. Dacă browserul blochează stocarea, fiecare vizită contează ca prima vizită și cardul nu apare niciodată.
data-changelog-url este opțional. Cu o adresă http sau https, cardul primește un link Vezi toate actualizările către ea, de obicei pagina ta găzduită sau propria pagină de changelog. Cu orice altceva, nu se afișează niciun link. data-theme și data-repos funcționează exact ca la widgetul inline.
Cardul nu preia niciodată focusul și nu blochează pagina: este o regiune etichetată, nu un dialog. Se închide cu butonul de închidere sau cu Escape cât timp focusul este în card. Escape în orice alt loc din pagina ta rămâne la îndemâna codului tău.
Regula unui singur script de widget pe pagină rămâne valabilă. Pop-up-ul și widgetul inline pot sta pe aceeași pagină: încarcă scriptul o dată și adaugă ambele elemente, iar ele se înțeleg asupra a ceea ce a văzut deja vizitatorul.
Versiunile fixate până la /widget-v18.js sunt mai vechi decât pop-up-ul. Ignoră data-mode și afișează în loc filele inline, așa că folosește /widget.js sau o versiune fixată mai nouă.
În aplicație, Setări, Feed public are acest fragment gata de copiat, cu id-ul feedului, tema și domeniul repository-urilor completate. Vizualizările cardului și clickurile pe linkul lui Află mai multe apar în Analytics ca cifre separate.
Reacții cu emoji
Cititorii pot reacționa la o intrare fără să scrie nimic. Cu reacțiile activate, fiecare intrare se încheie cu un rând de cinci, 👍 🎉 ❤️ 🚀 👀, fiecare cu numărul lui. Rândul apare în widgetul inline, pe cardul pop-up-ului de lansare și pe pagina găzduită a feedului.
Reacțiile sunt dezactivate până le activezi în aplicație, la Setări, Feed public. Codul tău de embed nu se schimbă: widgetul citește comutatorul din feedul tău, așa că rândul apare și dispare odată cu el. Dacă dezactivezi reacțiile, rândul se ascunde, dar numerele rămân, deci revin când le activezi din nou. Versiunile fixate de dinainte să existe reacțiile nu afișează niciodată rândul.
Fiecare cititor poate da o singură dată fiecare reacție unei intrări, iar dacă apasă din nou, o retrage. Widgetul îi deosebește pe cititori după un id aleatoriu pe care îl creează în browser la primul clic, nu după un cont sau o adresă de e-mail. Păstrăm doar un hash al acelui id, combinat cu echipa ta, așa că același browser lasă hashuri fără legătură între ele pe două changelog-uri diferite.
Numerele sunt orientative: un semnal prietenos, nu un vot. Dacă un cititor își șterge stocarea browserului sau deschide o fereastră privată, cineva poate reacționa din nou, așa că nu baza pe ele nicio decizie importantă. Numerele din feedul tău pot rămâne câteva minute în urmă, pentru că feedul este păstrat în cache, dar cel care dă clic își vede reacția numărată pe loc. În aplicație, fila Published din inbox arată totalul fiecărei intrări.
Când cineva reacționează, în localStorage-ul vizitatorului se păstrează două lucruri, niciodată într-un cookie. changelogapp-widget:reader-id conține id-ul aleatoriu, unul pe browser și pe origine de site. changelogapp-widget:reactions: urmat de id-ul feedului tău conține reacțiile alese de acest browser, pentru cel mult 200 de intrări, cele la care a reacționat cel mai recent. Pagina găzduită păstrează aceleași două sub propria adresă. Dacă browserul blochează stocarea, reacția funcționează în continuare pe durata acelei vizualizări a paginii, dar nu este reținută după ea.
Ca să stilizezi rândul, folosește ::part(reactions), ::part(reaction) pentru fiecare buton și ::part(reaction-count) pentru numărul lui, toate listate mai jos la Stilizare. Un număr zero nu afișează nicio cifră. Un buton apăsat are aria-pressed="true" și este desenat cu un inel în culoarea ta --changelogapp-accent și text îngroșat. ::part() nu poate selecta după acel atribut, așa că setează --changelogapp-accent ca să schimbi aspectul unui buton apăsat.
Tabla publică de feedback
Tabla le arată cititorilor ce au cerut și alți oameni și le permite să voteze. Cu tabla activată, fila Feedback se deschide cu cererile tale cele mai votate, fiecare cu statusul ei, iar formularul obișnuit se află sub ele.
Tabla este dezactivată până o activezi în aplicație, la Setări, Feed public. Codul tău de embed nu se schimbă: widgetul citește comutatorul din feedul tău. Dacă dezactivezi tabla, ea se ascunde, dar cererile și voturile lor rămân. Tabla se află în fila Feedback, deci un widget fără fila Feedback nu afișează nici tabla.
Tabla arată doar ce scrii tu. Feedbackul unui vizitator nu ajunge pe ea de la sine: tu hotărăști ce cereri apar pe tablă și tot tu scrii titlul și descrierea fiecăreia, în pagina Feedback board din aplicație. Poți porni o cerere de la un mesaj trimis de un vizitator sau poți publica o idee proprie, iar tabla nu arată niciodată mesajul sau adresa de e-mail a vizitatorului. Tabla afișează primele 100 de cereri, iar o echipă poate păstra până la 500.
Fiecare cerere are unul dintre cele cinci statusuri: În analiză, Planificat, În lucru, Livrat sau Respins. Dacă legi o cerere de o actualizare, ea trece singură la Livrat când actualizarea este publicată, sau imediat, dacă este deja publicată. O cerere pornită de la mesajul unui vizitator trece tot la Livrat când se publică o actualizare care livrează acel mesaj.
Fiecare browser are un singur vot per cerere pe fiecare site, iar un nou clic îl retrage. Votarea se închide odată ce o cerere este Livrată sau Respinsă, dar cine a votat deja își poate retrage votul. Voturile sunt un semnal, nu o numărătoare de oameni: dacă cineva își șterge stocarea browserului sau deschide o fereastră privată, poate vota din nou, așa că folosește-le ca să vezi ce contează pentru oameni, niciodată ca să iei o decizie importantă. Numerele pe care le văd ceilalți vizitatori pot rămâne puțin în urmă, în timp ce vizitatorul care votează vede numărul nou exact.
Când cineva votează, în localStorage-ul vizitatorului se păstrează două lucruri, niciodată într-un cookie. changelogapp-widget:votes: urmat de id-ul feedului tău listează cererile la care a votat acest browser, cel mult cele mai recente 200. changelogapp-widget:reader-id este id-ul aleatoriu folosit și de reacții, unul pe browser și pe origine de site, deci votul nu creează nimic nou dacă vizitatorul a reacționat deja. Stocăm doar un hash al acelui id, combinat cu echipa ta, niciodată id-ul în sine, așa că același browser lasă hashuri fără legătură între ele pe două changelog-uri diferite. Nu stocăm adresa IP a vizitatorului împreună cu votul. Dacă browserul blochează stocarea, votul funcționează totuși pentru acea vizualizare a paginii și nu este reținut după ea.
Tabla nu apare niciodată în pop-up-ul de lansare și nici într-un widget limitat cu data-repos, pentru că ea acoperă toată echipa ta. Pagina găzduită a changelog-ului tău are o filă Solicitări cu aceeași tablă, un filtru după status și voturi care se numără la fel. Tabla este disponibilă și ca JSON public, la GET /v1/public/YOUR_PUBLIC_ID/board.json pe același API, care răspunde cu 404 cât timp tabla este dezactivată.
Ca să stilizezi tabla, folosește ::part(board) pentru întregul bloc și ::part(board-heading) pentru titlul ei, apoi părțile fiecărei cereri, toate listate mai jos la Stilizare. Butonul de vot, ::part(board-vote), are aria-pressed="true" după ce acest browser a votat și este desenat atunci cu un inel în culoarea ta --changelogapp-accent. ::part() nu poate selecta după acel atribut, așa că setează --changelogapp-accent ca să schimbi aspectul unui vot numărat.
Stilizare
Widgetul se randează într-un shadow root, așa că cea mai mare parte din foaia ta de stil nu ajunge înăuntru. Proprietățile moștenite se propagă totuși acolo unde widgetul nu le setează pe ale lui, la fel și proprietățile personalizate de mai jos, setate pe element sau pe un strămoș. Pentru orice altceva, folosește numele ::part() de mai jos. Ambele liste sunt o interfață stabilă: un nume odată livrat nu este redenumit niciodată.
Proprietăți personalizate
--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
Pilulele de etichetă. O etichetă cu culoare o folosește ca fundal, iar în ambele teme culoarea textului este aleasă să se citească pe acel fundal, la 4.5:1 sau mai bine. Albul este preferat ori de câte ori atinge acest raport. O culoare pe care widgetul nu o poate citi ca valoare RGB solidă nu primește o culoare de text aleasă și păstrează valoarea implicită a temei. Ca să alegi tu culoarea textului, în oricare temă, setează --changelogapp-pill-text. O regulă ::part(entry-tag) are prioritate peste orice, așa că dacă setezi acolo un fundal, setează și color. --changelogapp-pill-bg este fundalul unei etichete fără culoare. Versiunile fixate până la /widget-v18.js păstrează textul alb al pilulelor în tema luminoasă.
Părți
- Intrările din changelog:
month-heading,entry,entry-date,entry-tag,entry-title,entry-body,entry-link,timeline-dot,entry-image,entry-header-image - În corpul unei intrări:
entry-body-heading,entry-body-paragraph,entry-body-list,entry-body-list-item,entry-body-link,entry-body-code - Numărul de necitite de pe fila Updates:
unread-badge - Pop-up-ul de lansare:
popup,popup-heading,popup-close,popup-link - Formularul Primește actualizările pe e-mail, în partea de sus a filei Updates, când abonații prin e-mail sunt activați (planul Team):
subscribe,subscribe-heading,subscribe-input,subscribe-button,subscribe-status - Reacțiile cu emoji, când sunt activate:
reactions,reaction,reaction-count - Tabla publică de feedback, când este activată:
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
Dacă site-ul tău trimite un antet Content-Security-Policy, widgetul are nevoie de originea API în două directive. script-src permite încărcarea scriptului. connect-src îi permite să îți citească changelog-ul, să trimită feedback și să înregistreze vizualizări. Doar cu prima, elementul apare și apoi rămâne gol, ceea ce seamănă cu un feed stricat, nu cu o cerere blocată. Pop-up-ul are nevoie de aceleași două.
script-src https://api.changeloop.dev; connect-src https://api.changeloop.dev;Începând cu widgetul 0.16.0, pe care îl servește /widget.js, browserele actuale nu cer nicio schimbare de style-src: widgetul își predă stilurile ca foaie de stil construită, pe care style-src nu o reglementează. Versiunile mai vechi, inclusiv cele fixate până la /widget-v18.js, și browserele fără foi de stil construibile folosesc în schimb un element style, care cere style-src 'unsafe-inline'.
img-src este necesar doar dacă ai activat imaginile în aplicație, la Setări, Feed public, Imagini. Widgetul încarcă atunci imaginile direct de pe hosturile tale de imagini, iar o politică ce nu le listează le blochează pe toate. Setări afișează linia exactă, cu img-src completat din lista ta, așa că copiaz-o din nou ori de câte ori schimbi lista. Hosturile de capturi de ecran ale GitHub au nevoie și de https://github-production-user-asset-6210df.s3.amazonaws.com în img-src, pentru că un link de captură de ecran GitHub redirecționează acolo, iar browserul verifică și acea adresă.
Dacă politica ta setează doar default-src, adaugă ambele directive și repetă în fiecare sursele din default-src. Un script-src sau connect-src înlocuiește default-src pentru scripturi sau conexiuni, deci dacă îți omiți propriile surse, acestea ar fi blocate.
Adaugă originea la directivele tale existente, nu le înlocui. Setări, Feed public din aplicație îți arată această linie cu originea potrivită pentru contul tău. Dacă nu trimiți acel antet, nu ai nimic de făcut.
Pagina de feed găzduită
Găzduim și noi o pagină simplă la acea adresă: changelog-ul și tabla ta de roadmap, randate din aceleași două feeduri de mai sus. Nu necesită autentificare și nici ceva configurat de partea ta. Este de asemenea locul unde trimitem oamenii înapoi odată ce o buclă se închide: comentariul Shipped pe care îl lăsăm pe un issue GitHub duce aici, la fel și shippedEntry.link din căutarea de trimitere de mai sus, ambele ajungând la intrarea livrată cu propria sa ancoră #entry-ID, care încă găsește intrarea chiar dacă între timp s-a mutat pe o pagină ulterioară.
Tratează-o ca o rezervă, nu ca integrarea. Feedul de changelog și widgetul rămân modul de a pune asta pe propriul tău site ca să arate ca produsul tău, nu al nostru; această pagină este pentru când nu ai făcut încă asta, și pentru linkurile de închidere a buclei, care indică aici indiferent de ce altceva ai construit.
Changelog-ul tău, în produsul tău
Changeloop scrie fiecare intrare dintr-un pull request unit, o ține pentru revizuirea ta și o servește acestui widget și unui feed JSON. Gratuit pentru un repository, fără card.
Începe gratuit