Intégrer une page

Votre changelog existe déjà dans vos docs. Ce guide place un déclencheur « Quoi de neuf ? » dans votre propre produit : un bouton ou un lanceur flottant qui ouvre ces mêmes entrées dans une modale, avec un point indiquant les mises à jour non lues par visiteur. Vous collez une seule balise <script> ; Jamdesk héberge et gère les versions du widget.

Les captures d'écran montrent l'interface en anglais.

Le changelog est le cas d'usage principal, celui autour duquel l'indicateur non lu est conçu. Le même widget peut ouvrir n'importe quelle page de docs dans la modale, cependant — pointez data-page là où une page ciblée et contextuelle est utile (voir Pointer la modale vers n'importe quelle page).

Essayez en direct

Cette page fait tourner le vrai widget. Cliquez ci-dessous et la même modale que vos visiteurs obtiennent s'ouvre ici même, chargeant le changelog de ce site :

Ce bouton en direct est le composant MDX <Widget>, la façon la plus simple d'intégrer le widget dans une page de docs Jamdesk : une seule balise, pas de script, et il résout votre site automatiquement. L'extrait <script> ci-dessous est pour l'autre cas, intégrer le widget dans votre propre produit ou application, là où les composants MDX ne s'exécutent pas. Même widget et même modale dans les deux cas ; le reste de cette page couvre le script.

Prérequis

• Un site Jamdesk publié sur son sous-domaine *.jamdesk.app (le widget se charge toujours depuis là, même si vous servez aussi les docs sur un domaine personnalisé).
• Une page de changelog construite à partir d'entrées <Update> avec rss: true dans son frontmatter (voir Activer avec rss: true).

Démarrage rapide

Ouvrez votre dashboard, allez dans Paramètres → Widget Quoi de neuf, définissez la page et les options du lanceur, puis copiez l'extrait généré. Il ressemble à ceci :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-theme="auto"
  async
></script>

Collez-le dans le HTML de votre application, avant la balise fermante </body>. Au chargement, il ajoute un lanceur Quoi de neuf flottant dans le coin. Cliquer dessus ouvre votre changelog dans une modale ; un point non lu apparaît lorsqu'il y a une entrée que le visiteur n'a pas encore vue.

Épingler une version ou auto-héberger

Le widget est open source, et l'extrait hébergé ci-dessus sert toujours la dernière version — le bon choix par défaut pour la plupart des sites. Quand vous préférez figer une version connue ou servir le fichier vous-même, le dépôt jamdesk-widget propose deux autres façons de le charger.

Épingler une version avec jsDelivr. Chargez une version taguée depuis le CDN et les octets ne changent jamais sous vous :

<script
  src="https://cdn.jsdelivr.net/gh/jamdesk/jamdesk-widget@v1.0.0/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  async
></script>

Auto-héberger. Téléchargez widget.js depuis la dernière release et servez-le depuis votre propre origine. Cela aide quand une politique script-src stricte exclut les scripts tiers.

Dans les deux cas, définissez data-base sur votre origine *.jamdesk.app : l'extrait hébergé le lit depuis l'URL du script lui-même, mais un CDN ou votre propre serveur ne peut pas le faire. Chaque release publie un hash d'intégrité de sous-ressource pour que vous puissiez épingler les octets exacts. Le README du dépôt décrit les trois chemins d'installation.

Activer avec rss: true

Le widget lit la dernière entrée depuis le même flux qui alimente votre RSS, donc une page n'alimente le widget que lorsque son frontmatter définit rss: true :

---
title: Changelog
rss: true
---

<Update label="June 2026" date="2026-06-01">

**Spec validation at build time.** Every deploy validates the OpenAPI specs your `docs.json` references.

</Update>

Sans rss: true, le widget se charge mais n'affiche aucune entrée et le lanceur reste masqué. Une page de docs qui démontre simplement le composant <Update> (sans rss: true) est correctement exclue, donc une date de démo n'allume jamais le point.

Configurer l'extrait

Chaque option est un attribut data- sur la balise script. La carte du dashboard les écrit pour vous, mais vous pouvez aussi modifier l'extrait manuellement.

Pointer la modale vers n'importe quelle page

data-page ouvre n'importe quel chemin sur votre site de docs, pas seulement /changelog. La modale affiche la page que vous nommez, dépouillée du chrome du site — une annonce unique, un guide de démarrage, une note de migration. Pointez-la là où une page ciblée et contextuelle est utile :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/announcements/2026-migration"
  data-unread="off"
  async
></script>

Deux comportements restent liés à votre flux de changelog, gardez-les à l'esprit quand la page n'est pas un changelog :

• Le point non lu suit la dernière entrée de votre changelog, pas la page dans la modale. Définissez data-unread="off" quand la modale ouvre autre chose, sinon le point s'allume pour des mises à jour du changelog que le visiteur ne voit jamais là.
• Le lanceur flottant n'apparaît automatiquement qu'une fois que votre changelog a une entrée (voir Activer avec rss: true). Pour intégrer une page sur un site sans changelog, liez-vous à votre propre élément avec data-trigger — votre élément s'affiche quoi qu'il arrive.

Modes du lanceur

Quand vous vous liez à votre propre élément, le widget ajoute le point non lu à cet élément et n'affiche jamais de bouton flottant (donc data-position et data-label ne s'appliquent plus) :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-trigger="#whats-new"
  async
></script>

Dimensionner la modale

La modale s'ouvre à 560 × 680 px. Définissez data-width et data-height pour la modifier. Un nombre seul est lu en pixels, ou utilisez n'importe quelle valeur px, vw, vh, rem, em, ou % :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-width="720px"
  data-height="600px"
  async
></script>

Les deux dimensions sont limitées de façon responsive (92vw de large, 86vh de haut), donc une grande taille s'adapte quand même sur un téléphone. Une valeur non reconnue revient au défaut. Les coins ont par défaut un rayon de 12px ; définissez data-radius (toute longueur CSS) pour les arrondir ou les carrer davantage.

Styliser le bouton du lanceur

Le lanceur flottant est une pilule sombre par défaut. Recolorez-le avec data-button-color (arrière-plan) et data-button-text-color (texte), chacun étant une valeur hex ou un nom de couleur CSS :

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-button-color="#4f46e5"
  data-button-text-color="#ffffff"
  async
></script>

Ces deux attributs ne stylisent que le bouton flottant du widget. Quand vous vous liez à votre propre élément avec data-trigger, le lanceur hérite du style de cet élément, donc ils n'ont aucun effet.

Personnaliser le point non lu

Le point non lu est rouge (#e5484d) et activé par défaut. Recolorez-le avec data-unread-color (une valeur hex ou un nom de couleur CSS), ou désactivez-le avec data-unread="off" :

<!-- Recolor the dot -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread-color="#7c3aed" async></script>

<!-- Turn the dot off -->
<script src="https://acme.jamdesk.app/_jd/widget.js" data-base="https://acme.jamdesk.app" data-unread="off" async></script>

Désactiver le point conserve le lanceur et la modale. Cela ne supprime que l'indicateur. La section suivante explique comment l'état « vu » est suivi.

Le point non lu

Le widget maintient un indicateur non lu par visiteur. Il compare l'identifiant de la dernière entrée à une valeur dans le localStorage du navigateur (une clé par projet). Quand ils diffèrent, un point s'affiche sur le lanceur ; ouvrir la modale marque l'entrée comme vue et efface le point jusqu'à la prochaine mise à jour.

Comme l'état vit dans localStorage, il est par navigateur et par visiteur. Il n'y a pas de compte ni de suivi, et effacer les données du site le réinitialise. Un visiteur dans un navigateur vierge voit le point une fois, puis plus jusqu'à ce que vous publiez quelque chose de nouveau.

Exemples

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-position="bottom-left"
  data-unread-color="#22c55e"
  async
></script>

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-trigger="#whats-new"
  data-width="720px"
  data-height="600px"
  async
></script>

<script
  src="https://acme.jamdesk.app/_jd/widget.js"
  data-base="https://acme.jamdesk.app"
  data-page="/changelog"
  data-label="Release notes"
  data-unread="off"
  async
></script>

Content-Security-Policy

Si votre propre site envoie une Content-Security-Policy stricte, autorisez votre origine *.jamdesk.app dans trois directives, sinon le widget ne fait rien silencieusement :

Content-Security-Policy:
  script-src  https://acme.jamdesk.app;
  frame-src   https://acme.jamdesk.app;
  connect-src https://acme.jamdesk.app;

• script-src charge widget.js.
• frame-src affiche l'iframe de la modale.
• connect-src récupère les métadonnées du changelog pour le point non lu.

Manquez-en un et il n'y a pas de bannière d'erreur : le lanceur n'apparaîtra pas ou la modale restera vide. Vérifiez la console de votre navigateur pour les violations CSP si le widget ne s'affiche pas.

Sites protégés par mot de passe

Et ensuite ?