Vai al contenuto

Tutta la documentazione per sviluppatori

Il widget di changelog da incorporare

Due righe di HTML portano il tuo changelog, la tua roadmap e un riquadro di feedback dentro il prodotto. Questa pagina copre gli attributi, i temi, la scelta di mostrare solo alcuni repository, il versionamento e la pagina ospitata su cui ripiega il widget.

Il widget incorporabile

Se preferisci non costruire nulla, aggiungi queste due righe. Il widget è un custom element che renderizza in uno shadow root, così non eredita i tuoi stili né vi si infiltra.

<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>

Entrambi gli attributi sono obbligatori. data-public-id è il tuo id feed, data-api è l'origine da cui il widget carica. Se manca uno dei due, l'elemento scrive un errore in console e non renderizza nulla, che è la prima cosa da controllare se vedi uno spazio vuoto dove dovrebbe stare.

Aggiungi data-theme="dark" all'elemento per una resa scura; la tua pagina può cambiarla a runtime. Per uno stile più profondo, il widget espone proprietà CSS personalizzate (--changelogapp-text, --changelogapp-bg, --changelogapp-accent e altre) e nomi ::part(), che imposti nel tuo foglio di stile. L'app mostra l'anteprima dal vivo di entrambi i temi in Impostazioni, Feed pubblico.

Aggiungi data-repos per mostrare solo alcuni dei tuoi repository, per esempio il changelog di un prodotto sul sito di quel prodotto quando più prodotti condividono un account. Il valore è un elenco di nomi completi owner/repo separati da virgole; un nome senza proprietario non corrisponde a nulla e mostra un feed vuoto senza errori. Vengono considerati al massimo dieci repository. Un widget così limitato mostra solo Updates e Feedback, perché la roadmap non ha una vista per repository, e il feedback viene comunque archiviato dove punta la destinazione feedback del tuo team. In Impostazioni, Feed pubblico c'è un selettore che scrive l'attributo per te.

Renderizza tre schede in quest'ordine: Novità, Roadmap e Feedback. Le prime due leggono i feed di sopra. La terza invia all'endpoint qui sotto e conserva ogni id di invio in localStorage, così chi visita può tornare e vedere cosa è successo a ciò che ha inviato.

Lo script viene servito con versioning. /widget.js serve sempre la build più recente ed è cachato per un'ora, così un rilascio raggiunge i tuoi visitatori senza che tu tocchi nulla. /widget-vN.js fissa una build: una volta servito un numero di versione, i suoi byte non cambiano mai più, ed è cachato per un anno. Fissalo se preferisci adottare i cambiamenti di proposito.

Carica esattamente uno script del widget per pagina

I due URL sono alternative, non livelli. Entrambi registrano lo stesso nome di custom element, e un browser permette di registrare un nome una sola volta per documento: vince lo script che si esegue per primo, per tutta la vita della pagina, e il secondo resta inerte. Quindi una pagina con sia /widget.js sia /widget-v5.js renderizza ciò che il browser ha eseguito per primo per caso, cosa che non controlli; aggiungere /widget-v5.js accanto a un /widget.js esistente per fissare la versione non fa nulla. Di solito vince la build più vecchia, perché è già in cache.

Quando succede, il widget scrive un avviso in console nominando entrambe le build, così non devi indovinare. Non può fare altro che avvisare: quando gira la seconda copia, la prima ha già preso il nome. La soluzione è sempre sostituire il tag script invece di aggiungerne un altro, e lo stesso vale se un tag manager o un parziale te ne inietta uno. Per passare dalla build continua a una fissata, cambia il src.

Pop-up di rilascio

Aggiungi data-mode="popup" e l'elemento non mostra alcuna scheda. Quando un visitatore ha qualcosa di nuovo da vedere, compare una piccola card con il tuo ultimo rilascio, altrimenti non compare niente. data-mode non distingue tra maiuscole e minuscole.

<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>

Sugli schermi larghi la card sta nell'angolo in basso a sinistra, perché quello in basso a destra di solito è occupato dal launcher di una chat. Sugli schermi più stretti di 480px occupa tutta la larghezza e copre il launcher della chat finché non viene chiusa. Si apre nel top layer del browser, quindi overflow, transform o z-index di un elemento genitore non possono ritagliarla o nasconderla. Per spostarla, stila ::part(popup).

Ogni rilascio viene mostrato una sola volta. La card compare quando il visitatore ha voci che non ha ancora visto. Mostra la più recente, con un conteggio se sono più di una, e le segna come viste nel momento in cui compare. Al caricamento successivo della pagina non si vede nulla finché non pubblichi di nuovo.

Una prima visita non mostra proprio nulla: il widget si limita a registrare fin dove arriva il tuo changelog, così chi ti usa già non viene accolto con vecchie notizie il giorno in cui lo aggiungi. La card parte dal tuo prossimo rilascio. Chi ha già letto un rilascio nel widget inline non se lo vede riproporre.

Ciò che un visitatore ha già visto è conservato in localStorage, non in un cookie, quindi appartiene a un solo browser e a una sola origine del sito. La stessa persona su un altro dei tuoi domini riparte da una prima visita. Se il browser blocca lo storage, ogni visita conta come una prima visita e la card non compare mai.

data-changelog-url è facoltativo. Con un indirizzo http o https, la card mostra un link Vedi tutti gli aggiornamenti verso di esso, di solito la tua pagina ospitata o la pagina del tuo changelog. Con qualsiasi altro valore, nessun link viene disegnato. data-theme e data-repos funzionano esattamente come nel widget inline.

La card non prende mai il focus e non blocca mai la pagina: è una regione con etichetta, non una finestra di dialogo. Si chiude con il pulsante di chiusura, oppure con Escape quando il focus è dentro la card. Escape in qualsiasi altro punto della pagina è lasciato al tuo codice.

La regola di un solo script del widget per pagina vale sempre. Il pop-up e il widget inline possono stare nella stessa pagina: carica lo script una volta sola e aggiungi entrambi gli elementi, e si accordano su ciò che il visitatore ha già visto.

Le build fissate fino a /widget-v18.js sono precedenti al pop-up. Ignorano data-mode e mostrano invece le schede inline, quindi usa /widget.js o una build fissata più recente.

Nell'app, Impostazioni, Feed pubblico ha questo snippet pronto da copiare, con il tuo id feed, il tema e l'ambito dei repository già compilati. Le visualizzazioni della card e i clic sul suo link Scopri di più compaiono in Analytics come numeri a parte.

Reazioni con emoji

I lettori possono reagire a una voce senza scrivere nulla. Con le reazioni attive, ogni voce termina con una riga di cinque emoji, 👍 🎉 ❤️ 🚀 👀, ciascuna con il suo conteggio. La riga compare nel widget inline, sulla card del pop-up di rilascio e nella pagina ospitata del feed.

Le reazioni sono disattivate finché non le attivi nell'app, in Impostazioni, Feed pubblico. Il tuo codice di incorporamento non cambia: il widget legge l'interruttore dal tuo feed, quindi la riga compare e scompare insieme a esso. Disattivare le reazioni nasconde la riga e conserva i conteggi, che tornano se le riattivi. Le build fissate precedenti all'arrivo delle reazioni non mostrano mai la riga.

Ogni lettore può dare a una voce ciascuna reazione una sola volta, e premendola di nuovo la ritira. Il widget distingue i lettori da un id casuale che crea nel browser al primo clic, non da un account o da un indirizzo email. Conserviamo solo un hash di quell'id combinato con il tuo team, quindi lo stesso browser lascia hash senza alcun legame su due changelog diversi.

I conteggi sono indicativi: un segnale amichevole, non un voto. Cancellando lo storage del browser o aprendo una finestra privata si può reagire di nuovo, quindi non basare mai su di essi una decisione importante. I conteggi nel tuo feed possono inoltre restare indietro di qualche minuto, perché il feed è in cache, ma chi clicca vede subito contata la propria reazione. Nell'app, la scheda Pubblicate della inbox mostra il totale di ogni voce.

Reagire salva due cose nel localStorage del visitatore, mai in un cookie. changelogapp-widget:reader-id contiene l'id casuale, uno per browser e per origine del sito. changelogapp-widget:reactions: seguito dall'id del tuo feed contiene le reazioni scelte da questo browser, fino a 200 voci, quelle a cui ha reagito più di recente. La pagina ospitata conserva gli stessi due valori sotto il proprio indirizzo. Se il browser blocca lo storage, reagire funziona comunque per quella visualizzazione della pagina e non viene ricordato dopo.

Per stilizzare la riga, usa ::part(reactions), ::part(reaction) per ogni pulsante e ::part(reaction-count) per il suo numero, tutti elencati sotto in Stile. Un conteggio pari a zero non mostra alcun numero. Un pulsante premuto ha aria-pressed="true" e viene disegnato con un anello del colore --changelogapp-accent e testo in grassetto. ::part() non può selezionare in base a quell'attributo, quindi imposta --changelogapp-accent per cambiare l'aspetto di un pulsante premuto.

Bacheca pubblica del feedback

La bacheca permette ai lettori di vedere cosa hanno chiesto gli altri e di votarlo. Con la bacheca attiva, la scheda Feedback si apre con le richieste più votate, ciascuna con il suo stato, e il solito modulo sta sotto di esse.

La bacheca è disattivata finché non la attivi nell'app, in Impostazioni, Feed pubblico. Il tuo codice di incorporamento non cambia: il widget legge l'interruttore dal tuo feed. Disattivare la bacheca la nasconde e conserva le tue richieste e i loro voti. Vive nella scheda Feedback, quindi un widget che non mostra la scheda Feedback non mostra nemmeno la bacheca.

La bacheca mostra solo ciò che scrivi tu. Il feedback di un visitatore non ci finisce mai da solo: decidi tu quali richieste pubblicare e scrivi di persona titolo e descrizione di ciascuna, nella pagina Bacheca del feedback dell'app. Puoi partire dal messaggio di un visitatore oppure pubblicare un'idea tua, e la bacheca non mostra mai il messaggio né l'indirizzo email del visitatore. La bacheca mostra le tue prime 100 richieste e un team può conservarne fino a 500.

Ogni richiesta ha uno di cinque stati: In valutazione, Pianificato, In corso, Rilasciato o Rifiutato. Collega una richiesta a un aggiornamento e passa a Rilasciato da sola quando quell'aggiornamento viene pubblicato, o subito se lo è già. Anche una richiesta nata dal messaggio di un visitatore passa a Rilasciato quando viene pubblicato un aggiornamento che risolve quel messaggio.

Ogni browser ha un voto per richiesta su ciascun sito, e cliccando di nuovo lo ritira. La votazione si chiude quando una richiesta è Rilasciato o Rifiutato, anche se chi ha già votato può ancora ritirare il proprio voto. I voti sono un segnale, non un conteggio di persone: cancellando lo storage del browser o aprendo una finestra privata si può votare di nuovo, quindi usali per capire cosa interessa alle persone, mai per chiudere una decisione importante. I conteggi che vedono gli altri visitatori possono restare un po' indietro, mentre chi vota vede subito il nuovo conteggio esatto.

Votare salva due cose nel localStorage del visitatore, mai in un cookie. changelogapp-widget:votes: seguito dall'id del tuo feed elenca le richieste a cui questo browser ha votato, fino alle 200 più recenti. changelogapp-widget:reader-id è l'id casuale che usano le reazioni, uno per browser e per origine del sito, quindi votare non crea nulla di nuovo se il visitatore ha già reagito. Conserviamo solo un hash di quell'id combinato con il tuo team, mai l'id in sé, quindi lo stesso browser lascia hash senza alcun legame su due changelog diversi. Con un voto non conserviamo l'indirizzo IP del visitatore. Se il browser blocca lo storage, votare funziona comunque per quella visualizzazione della pagina e non viene ricordato dopo.

La bacheca non compare mai nel pop-up di rilascio, né in un widget limitato con data-repos, perché copre tutto il tuo team. La tua pagina ospitata del changelog ha una scheda Richieste con la stessa bacheca, un filtro per stato e voti che contano allo stesso modo. La bacheca è anche JSON pubblico, su GET /v1/public/YOUR_PUBLIC_ID/board.json della stessa API, che risponde 404 finché la bacheca è disattivata.

Per stilizzare la bacheca, usa ::part(board) per l'intero blocco e ::part(board-heading) per il suo titolo, poi le parti di ogni richiesta, tutte elencate sotto in Stile. Il pulsante di voto, ::part(board-vote), ha aria-pressed="true" una volta che questo browser ha votato, e viene allora disegnato con un anello del colore --changelogapp-accent. ::part() non può selezionare in base a quell'attributo, quindi imposta --changelogapp-accent per cambiare l'aspetto di un voto contato.

Stile

Il widget renderizza in uno shadow root, quindi la maggior parte del tuo foglio di stile non arriva al suo interno. Le proprietà ereditate continuano a passare dove il widget non ne imposta di proprie, e lo stesso vale per le proprietà personalizzate qui sotto, impostate sull'elemento o su un suo antenato. Per tutto il resto, usa i nomi ::part() qui sotto. Entrambi gli elenchi sono un'interfaccia stabile: un nome, una volta rilasciato, non viene mai rinominato.

Proprietà personalizzate

  • --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

Pillole dei tag. Un tag con un colore lo usa come sfondo, e in entrambi i temi il colore del testo viene scelto in modo che si legga su quello sfondo, con 4.5:1 o più. Il bianco è preferito ogni volta che raggiunge quel valore. Un colore che il widget non riesce a leggere come valore RGB pieno non riceve un colore del testo scelto e mantiene quello predefinito del tema. Per scegliere tu il colore del testo, in uno qualsiasi dei due temi, imposta --changelogapp-pill-text. Una regola ::part(entry-tag) vince su tutto, quindi se imposti lì uno sfondo, imposta anche color. --changelogapp-pill-bg è lo sfondo di un tag senza colore. Le build fissate fino a /widget-v18.js mantengono il testo bianco nelle pillole del tema chiaro.

Parti

  • Voci del changelog: month-heading, entry, entry-date, entry-tag, entry-title, entry-body, entry-link, timeline-dot, entry-image, entry-header-image
  • Dentro il corpo di una voce: entry-body-heading, entry-body-paragraph, entry-body-list, entry-body-list-item, entry-body-link, entry-body-code
  • Il conteggio dei non letti nella scheda Aggiornamenti: unread-badge
  • Il pop-up di rilascio: popup, popup-heading, popup-close, popup-link
  • Il modulo Ricevi gli aggiornamenti via e-mail, in cima ad Aggiornamenti quando gli iscritti via e-mail sono attivi (piano Team): subscribe, subscribe-heading, subscribe-input, subscribe-button, subscribe-status
  • Le reazioni con emoji, quando sono attive: reactions, reaction, reaction-count
  • La bacheca pubblica del feedback, quando è attiva: 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

Se il tuo sito invia un header Content-Security-Policy, il widget ha bisogno dell'origine dell'API in due direttive. script-src permette di caricare lo script. connect-src gli permette di leggere il tuo changelog, inviare feedback e registrare le visualizzazioni. Con la sola prima, l'elemento compare e poi resta vuoto, e sembra un feed rotto più che una richiesta bloccata. Il pop-up ha bisogno delle stesse due.

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

Dal widget 0.16.0, quello servito da /widget.js, i browser attuali non richiedono alcuna modifica a style-src: il widget consegna i suoi stili come foglio di stile costruito, che style-src non regola. Le build più vecchie, comprese quelle fissate fino a /widget-v18.js, e i browser senza fogli di stile costruibili usano invece un elemento style, che richiede style-src 'unsafe-inline'.

img-src serve solo se hai attivato le immagini nell'app, in Impostazioni, Feed pubblico, Immagini. Il widget carica allora le immagini direttamente dai tuoi host di immagini, e una policy che non li elenca le blocca tutte. Impostazioni mostra la riga esatta con img-src già compilato in base al tuo elenco, quindi copiala di nuovo ogni volta che cambi l'elenco. Gli host degli screenshot di GitHub richiedono anche https://github-production-user-asset-6210df.s3.amazonaws.com in img-src, perché un link a uno screenshot di GitHub reindirizza lì e il browser controlla anche quell'indirizzo.

Se la tua policy imposta solo default-src, aggiungi entrambe le direttive e ripeti in ciascuna le sorgenti del tuo default-src. Uno script-src o un connect-src sostituisce default-src per gli script o per le connessioni, quindi dimenticare le tue sorgenti le bloccherebbe.

Aggiungi l'origine alle direttive che hai già invece di sostituirle. Impostazioni, Feed pubblico nell'app mostra questa riga con l'origine giusta per il tuo account. Se non invii quell'header, non c'è nulla da fare.

La pagina di feed ospitata

A quello stesso indirizzo ospitiamo anche una pagina semplice: il tuo changelog e la tua bacheca roadmap, renderizzati dagli stessi due feed di sopra. Non richiede accesso né alcuna configurazione da parte tua. È anche dove riportiamo le persone quando un ciclo si chiude: il commento Shipped che lasciamo su una issue GitHub rimanda qui, e lo stesso fa shippedEntry.link dalla ricerca di stato sopra, entrambi arrivando alla voce pubblicata con la propria ancora #entry-ID, che trova la voce anche se nel frattempo è passata a una pagina successiva.

Trattala come un'alternativa, non come l'integrazione. Il feed del changelog e il widget restano il modo per portare questo nel tuo sito così che sembri il tuo prodotto e non il nostro; questa pagina serve per il periodo prima che tu l'abbia fatto, e per i link di chiusura ciclo, che puntano qui a prescindere da cos'altro hai costruito.

Il tuo changelog, dentro il tuo prodotto

Changeloop scrive ogni voce a partire da una pull request unita, la tiene per la tua revisione e la serve a questo widget e a un feed JSON. Gratis per un repository, senza carta.

Inizia gratis

Leggi la documentazione per sviluppatori