Aller au contenu

Toute la documentation développeurs

Le widget de changelog à intégrer

Deux lignes de HTML placent ton changelog, ta roadmap et une zone de feedback dans ton produit. Cette page couvre les attributs, les thèmes, l'affichage de seulement certains dépôts, le versionnage et la page hébergée sur laquelle le widget se rabat.

Le widget intégrable

Si tu préfères ne rien construire, ajoute ces deux lignes. Le widget est un custom element qui se rend dans un shadow root, il n'hérite donc ni ne fuit dans tes styles.

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

Les deux attributs sont obligatoires. data-public-id est ton id de flux, data-api est l'origine depuis laquelle le widget charge. Si l'un des deux manque, l'élément écrit une erreur dans la console et ne rend rien du tout, ce qui est la première chose à vérifier si tu vois un espace vide là où il devrait être.

Ajoute data-theme="dark" à l'élément pour un rendu sombre ; ta page peut le basculer à l'exécution. Pour un style plus poussé, le widget expose des propriétés CSS personnalisées (--changelogapp-text, --changelogapp-bg, --changelogapp-accent et d'autres) et des noms ::part(), que tu définis dans ta propre feuille de style. L'application prévisualise les deux thèmes en direct dans Paramètres, Flux public.

Ajoutez data-repos pour n'afficher que certains de vos dépôts, par exemple le changelog d'un produit sur le site de ce produit lorsque plusieurs produits partagent un même compte. La valeur est une liste de noms complets owner/repo séparés par des virgules ; un nom sans propriétaire ne correspond à rien et affiche un flux vide sans erreur. Dix dépôts au maximum sont pris en compte. Un widget ainsi restreint n'affiche que Updates et Feedback, car la roadmap n'a pas de vue par dépôt, et les retours sont toujours déposés là où pointe la cible de feedback de votre équipe. Réglages, Flux public propose un sélecteur qui écrit l'attribut pour vous.

Il rend trois onglets dans cet ordre : Nouveautés, Roadmap et Feedback. Les deux premiers lisent les flux ci-dessus. Le troisième envoie à l'endpoint ci-dessous et conserve chaque id d'envoi dans localStorage, pour que le visiteur puisse revenir voir ce qu'il est advenu de son message.

Le script est servi avec versionnage. /widget.js sert toujours la build la plus récente et est mis en cache une heure, donc une version atteint tes visiteurs sans que tu touches à rien. /widget-vN.js fige une build : une fois un numéro de version servi, ses octets ne changent plus jamais, et il est mis en cache un an. Fige-le si tu préfères adopter les changements délibérément.

Charge exactement un script de widget par page

Les deux URL sont des alternatives, pas des couches. Les deux enregistrent le même nom de custom element, et un navigateur ne permet d'enregistrer un nom qu'une seule fois par document : le script qui s'exécute en premier gagne, pour toute la vie de la page, et le second reste inerte. Donc une page portant à la fois /widget.js et /widget-v5.js rend ce que le navigateur a exécuté en premier par hasard, ce que tu ne contrôles pas ; ajouter /widget-v5.js à côté d'un /widget.js existant pour figer la version ne fait rien du tout. C'est généralement la build la plus ancienne qui gagne, car elle est déjà en cache.

Quand ça arrive, le widget écrit un avertissement dans la console nommant les deux builds, tu n'as donc pas à deviner. Il ne peut rien faire de plus qu'avertir : quand la deuxième copie s'exécute, la première a déjà pris le nom. La solution est toujours de remplacer la balise script au lieu d'en ajouter une autre, et pareil si un gestionnaire de balises ou un partiel t'en injecte une. Pour passer de la build continue à une figée, change le src.

Pop-up de nouveautés

Ajoute data-mode="popup" et l'élément n'affiche plus d'onglets. Quand un visiteur a quelque chose de nouveau à voir, il montre une petite carte avec ta dernière version, et rien du tout sinon. data-mode ne tient pas compte de la casse.

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

Sur grand écran, la carte se place en bas à gauche, car le coin inférieur droit appartient souvent à un lanceur de chat. Sur les écrans de moins de 480px de large, elle occupe toute la largeur et recouvre le lanceur de chat jusqu'à sa fermeture. Elle s'ouvre dans la top layer du navigateur, donc l'overflow, le transform ou le z-index d'un élément parent ne peuvent ni la couper ni l'enfouir. Pour la déplacer, style ::part(popup).

Chaque version n'est montrée qu'une fois. La carte apparaît quand le visiteur a des entrées qu'il n'a pas encore vues. Elle affiche la plus récente, avec un compteur s'il y en a plusieurs, et les compte comme vues dès qu'elle apparaît. Le prochain chargement de page n'affiche rien tant que tu n'as pas publié à nouveau.

Une première visite n'affiche rien du tout : le widget note seulement jusqu'où va ton changelog, pour que les utilisateurs existants ne reçoivent pas de vieilles nouvelles le jour où tu l'ajoutes. La carte démarre avec ta prochaine version. Un visiteur qui a déjà lu une version dans le widget intégré ne la revoit pas.

Ce qu'un visiteur a déjà vu est conservé dans localStorage, pas dans un cookie, donc cela dépend d'un seul navigateur et d'une seule origine de site. La même personne sur un autre de tes domaines repart d'une première visite. Si le navigateur bloque le stockage, chaque visite compte comme une première visite et la carte ne s'affiche jamais.

data-changelog-url est facultatif. Avec une adresse http ou https, la carte reçoit un lien « Voir toutes les mises à jour » vers cette adresse, en général ta page hébergée ou ta propre page de changelog. Avec toute autre valeur, aucun lien n'est affiché. data-theme et data-repos fonctionnent exactement comme sur le widget intégré.

La carte ne prend jamais le focus et ne bloque jamais la page : c'est une région étiquetée, pas une boîte de dialogue. Elle se ferme avec son bouton de fermeture, ou avec Escape tant que le focus est dans la carte. Escape ailleurs sur ta page est laissé à ton propre code.

La règle d'un seul script de widget par page s'applique toujours. Le pop-up et le widget intégré peuvent partager une page : charge le script une fois et ajoute les deux éléments, ils s'accordent sur ce que le visiteur a déjà vu.

Les builds figées jusqu'à /widget-v18.js sont plus anciennes que le pop-up. Elles ignorent data-mode et affichent les onglets intégrés à la place, utilise donc /widget.js ou une build figée plus récente.

Dans l'application, Paramètres, Flux public propose ce snippet prêt à copier, avec ton id de flux, ton thème et ton périmètre de dépôts déjà remplis. Les vues de la carte et les clics sur son lien « En savoir plus » apparaissent dans Analytics comme des chiffres à part.

Réactions emoji

Les lecteurs peuvent réagir à une entrée sans rien écrire. Quand les réactions sont activées, chaque entrée se termine par une rangée de cinq emojis, 👍 🎉 ❤️ 🚀 👀, chacun avec son compteur. La rangée s'affiche dans le widget intégré, sur la carte du pop-up de nouveautés et sur la page de flux hébergée.

Les réactions sont désactivées tant que tu ne les actives pas dans l'application, sous Paramètres, Flux public. Ton code d'intégration ne change pas : le widget lit l'interrupteur depuis ton flux, donc la rangée apparaît et disparaît avec lui. Désactiver les réactions masque la rangée et conserve les compteurs, qui reviennent si tu les réactives. Les builds figées antérieures aux réactions n'affichent jamais la rangée.

Chaque lecteur peut donner une fois chaque réaction à une entrée, et un nouvel appui la retire. Le widget distingue les lecteurs grâce à un id aléatoire qu'il crée dans le navigateur au premier clic, pas grâce à un compte ou à une adresse e-mail. Nous ne stockons qu'un hash de cet id combiné à ton équipe, de sorte que le même navigateur laisse des hashs sans lien entre deux changelogs différents.

Les compteurs sont indicatifs : un signal sympathique, pas un vote. Vider le stockage du navigateur ou ouvrir une fenêtre privée permet de réagir à nouveau, donc ne fonde jamais une décision importante dessus. Les compteurs de ton flux peuvent aussi avoir quelques minutes de retard, car le flux est mis en cache, mais la personne qui clique voit sa propre réaction comptée tout de suite. Dans l'application, l'onglet Publiées de la boîte de relecture affiche le total de chaque entrée.

Réagir conserve deux éléments dans le localStorage du visiteur, jamais dans un cookie. changelogapp-widget:reader-id contient l'id aléatoire, un par navigateur et par origine de site. changelogapp-widget:reactions: suivi de l'id de ton flux contient les réactions choisies par ce navigateur, pour 200 entrées au maximum, celles auxquelles il a réagi le plus récemment. La page hébergée conserve les deux mêmes éléments sous sa propre adresse. Si le navigateur bloque le stockage, réagir fonctionne quand même pour cet affichage de la page, mais ce n'est pas mémorisé ensuite.

Pour styler la rangée, utilise ::part(reactions), ::part(reaction) pour chaque bouton et ::part(reaction-count) pour son nombre, tous listés sous Personnalisation du style plus bas. Un compteur à zéro n'affiche aucun nombre. Un bouton pressé porte aria-pressed="true" et s'affiche avec un anneau de ta couleur --changelogapp-accent et un texte en gras. ::part() ne peut pas sélectionner selon cet attribut, donc définis --changelogapp-accent pour changer l'apparence d'un bouton pressé.

Tableau de feedback public

Le tableau permet aux lecteurs de voir ce que d'autres ont demandé et de voter. Quand il est activé, l'onglet Feedback s'ouvre sur tes demandes les plus votées, chacune avec son statut, et le formulaire habituel se trouve en dessous.

Le tableau est désactivé tant que tu ne l'actives pas dans l'application, sous Paramètres, Flux public. Ton code d'intégration ne change pas : le widget lit l'interrupteur depuis ton flux. Désactiver le tableau le masque et conserve tes demandes et leurs votes. Il vit dans l'onglet Feedback, donc un widget qui n'affiche pas d'onglet Feedback n'affiche pas non plus de tableau.

Le tableau n'affiche que ce que tu écris. Le feedback d'un visiteur n'y arrive jamais tout seul : tu décides quelles demandes y figurent, et tu rédiges toi-même le titre et la description de chacune, sur la page Tableau de feedback de l'application. Tu peux créer une demande à partir d'un message de visiteur ou publier une idée à toi, et le tableau n'affiche jamais le message ni l'adresse e-mail du visiteur. Le tableau montre tes 100 premières demandes, et une équipe peut en conserver jusqu'à 500.

Chaque demande a l'un de cinq statuts : À l'étude, Prévu, En cours, Livré ou Refusé. Lie une demande à une mise à jour et elle passe à Livré toute seule quand cette mise à jour est publiée, ou tout de suite si elle l'est déjà. Une demande créée à partir d'un message de visiteur passe aussi à Livré quand une mise à jour qui répond à ce message est publiée.

Chaque navigateur a une voix par demande et par site, et un nouveau clic la retire. Le vote se ferme dès qu'une demande est Livré ou Refusé, mais ceux qui ont déjà voté peuvent encore retirer leur voix. Les votes sont un signal, pas un recensement : vider le stockage du navigateur ou ouvrir une fenêtre privée permet de voter à nouveau, donc sers-t'en pour voir ce qui compte pour les gens, jamais pour trancher une décision importante. Les compteurs que voient les autres visiteurs peuvent avoir un peu de retard, alors que le visiteur qui vote voit le nouveau compte exact.

Voter conserve deux éléments dans le localStorage du visiteur, jamais dans un cookie. changelogapp-widget:votes: suivi de l'id de ton flux liste les demandes pour lesquelles ce navigateur a voté, jusqu'aux 200 plus récentes. changelogapp-widget:reader-id est l'id aléatoire qu'utilisent les réactions, un par navigateur et par origine de site, donc voter ne crée rien de nouveau si le visiteur a déjà réagi. Nous ne stockons qu'un hash de cet id combiné à ton équipe, jamais l'id lui-même, de sorte que le même navigateur laisse des hashs sans lien entre deux changelogs différents. Nous ne stockons pas l'adresse IP du visiteur avec un vote. Si le navigateur bloque le stockage, voter fonctionne quand même pour cet affichage de la page, mais ce n'est pas mémorisé ensuite.

Le tableau ne s'affiche jamais dans le pop-up de nouveautés, ni dans un widget limité par data-repos, car il couvre toute ton équipe. Ta page hébergée a un onglet Demandes avec le même tableau, un filtre par statut et des votes qui comptent de la même façon. Le tableau est aussi du JSON public, à GET /v1/public/YOUR_PUBLIC_ID/board.json sur la même API, qui répond 404 tant que le tableau est désactivé.

Pour styler le tableau, utilise ::part(board) pour tout le bloc et ::part(board-heading) pour son titre, puis les parts de chaque demande, tous listés sous Personnalisation du style plus bas. Le bouton de vote, ::part(board-vote), porte aria-pressed="true" dès que ce navigateur a voté, et s'affiche alors avec un anneau de ta couleur --changelogapp-accent. ::part() ne peut pas sélectionner selon cet attribut, donc définis --changelogapp-accent pour changer l'apparence d'un vote compté.

Personnalisation du style

Le widget se rend dans un shadow root, donc la plupart de ta feuille de style n'atteint pas l'intérieur. Les propriétés héritées y entrent quand même là où le widget n'a pas défini la sienne, tout comme les propriétés personnalisées ci-dessous, définies sur l'élément ou sur un ancêtre. Pour tout le reste, utilise les noms ::part() ci-dessous. Les deux listes forment une interface stable : un nom qui a été publié n'est jamais renommé.

Propriétés personnalisées

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

Pastilles de tag. Un tag avec une couleur l'utilise comme fond. Dans les deux thèmes, la couleur du texte est choisie pour rester lisible sur ce fond, à 4.5:1 ou mieux. Le blanc est préféré dès qu'il atteint ce seuil. Une couleur que le widget ne peut pas lire comme une valeur RGB pleine n'obtient pas de couleur de texte choisie et garde celle par défaut du thème. Pour choisir toi-même la couleur du texte, dans l'un ou l'autre thème, définis --changelogapp-pill-text. Une règle ::part(entry-tag) l'emporte sur tout, donc si tu y définis un fond, définis aussi color. --changelogapp-pill-bg est le fond d'un tag sans couleur. Les builds figées jusqu'à /widget-v18.js gardent un texte de pastille blanc dans le thème clair.

Parts

  • Entrées du changelog : month-heading, entry, entry-date, entry-tag, entry-title, entry-body, entry-link, timeline-dot, entry-image, entry-header-image
  • Dans le corps d'une entrée : entry-body-heading, entry-body-paragraph, entry-body-list, entry-body-list-item, entry-body-link, entry-body-code
  • Le compteur de non lus sur l'onglet Mises à jour : unread-badge
  • Le pop-up de nouveautés : popup, popup-heading, popup-close, popup-link
  • Le formulaire « Recevoir les mises à jour par e-mail », en haut de Mises à jour quand les abonnés par e-mail sont activés (formule Team) : subscribe, subscribe-heading, subscribe-input, subscribe-button, subscribe-status
  • Les réactions emoji, quand elles sont activées : reactions, reaction, reaction-count
  • Le tableau de feedback public, quand il est activé : 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

Si ton site envoie un en-tête Content-Security-Policy, le widget a besoin de l'origine de l'API dans deux directives. script-src permet de charger le script. connect-src lui permet de lire ton changelog, d'envoyer des retours et d'enregistrer des vues. Avec la première seule, l'élément apparaît puis reste vide, ce qui ressemble à un flux cassé plutôt qu'à une requête bloquée. Le pop-up a besoin des deux aussi.

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

Depuis le widget 0.16.0, que /widget.js sert, les navigateurs récents n'ont besoin d'aucun changement de style-src : le widget transmet ses styles sous forme de feuille de style construite, que style-src ne régit pas. Les anciennes builds, y compris les builds figées jusqu'à /widget-v18.js, et les navigateurs sans feuilles de style constructibles utilisent un élément style à la place, ce qui exige style-src 'unsafe-inline'.

img-src n'est nécessaire que si tu as activé les images dans l'application, sous Paramètres, Flux public, Images. Le widget charge alors les images directement depuis tes hôtes d'images, et une politique qui ne les liste pas les bloque toutes. Paramètres affiche la ligne exacte avec img-src rempli à partir de ta liste, alors copie-la à nouveau chaque fois que tu modifies la liste. Les hôtes de captures d'écran de GitHub ont aussi besoin de https://github-production-user-asset-6210df.s3.amazonaws.com dans img-src, parce qu'un lien de capture GitHub redirige vers cette adresse et que le navigateur la vérifie aussi.

Si ta politique ne définit que default-src, ajoute les deux directives et répète dans chacune les sources de ton default-src. Un script-src ou connect-src remplace default-src pour les scripts ou les connexions, donc oublier tes propres sources les bloquerait.

Ajoute l'origine à tes directives existantes au lieu de les remplacer. Paramètres, Flux public dans l'application affiche cette ligne avec la bonne origine pour ton compte. Si tu n'envoies pas cet en-tête, il n'y a rien à faire.

La page de flux hébergée

À cette même adresse, nous hébergeons aussi une page simple : ton changelog et ton tableau de roadmap, rendus depuis les deux mêmes flux ci-dessus. Elle ne nécessite ni connexion ni aucune configuration de ta part. C'est aussi là que nous renvoyons les gens une fois qu'une boucle se referme : le commentaire Shipped que nous laissons sur une issue GitHub renvoie ici, tout comme shippedEntry.link depuis la vérification de statut ci-dessus, tous deux atterrissant sur l'entrée livrée avec sa propre ancre #entry-ID, qui retrouve l'entrée même si elle est depuis passée à une page ultérieure.

Traite-la comme une solution de repli, pas comme l'intégration. Le flux du changelog et le widget restent la façon d'intégrer ça sur ton propre site pour qu'il ressemble à ton produit et pas au nôtre ; cette page sert pour la période avant que tu l'aies fait, et pour les liens de fermeture de boucle, qui pointent ici quoi que tu aies construit d'autre.

Ton changelog, dans ton produit

Changeloop rédige chaque entrée à partir d'une pull request mergée, la garde pour ta relecture et la sert à ce widget et à un flux JSON. Gratuit pour un dépôt, sans carte.

Commencer gratuitement

Lire la documentation développeurs