Incorpora una pagina

Il tuo changelog è già presente nella documentazione. Questa guida aggiunge un'attivazione "What's new?" direttamente nel tuo prodotto: un pulsante o un launcher flottante che apre le stesse voci in un modale, con un indicatore che segnala gli aggiornamenti non letti per ogni visitatore. Incolli un solo tag <script>; Jamdesk ospita e gestisce le versioni del widget.

Gli screenshot mostrano l'interfaccia in inglese.

Il changelog è il caso d'uso più comune e quello attorno a cui è progettato l'indicatore delle novità non lette. Tuttavia, lo stesso widget può aprire qualsiasi pagina della documentazione nel modale. Indica in data-page la pagina in cui è utile un contenuto mirato e contestuale (vedi Indica qualsiasi pagina nel modale).

Provalo dal vivo

Questa pagina esegue il widget reale. Fai clic qui sotto per aprire direttamente lo stesso modale visualizzato dai tuoi visitatori, che carica il changelog di questo sito:

Questo pulsante live è il componente MDX <Widget>, il modo più semplice per incorporare il widget in una pagina della documentazione Jamdesk: è un singolo tag, non richiede script e rileva automaticamente il tuo sito. Lo snippet <script> qui sotto serve invece per incorporare il widget nel tuo prodotto o nella tua app, dove i componenti MDX non vengono eseguiti. Il widget e il modale sono gli stessi in entrambi i casi; il resto della pagina descrive lo script.

Prerequisiti

• Un sito Jamdesk pubblicato sul suo sottodominio *.jamdesk.app (il widget viene sempre caricato da lì, anche se fornisci la documentazione anche su un dominio personalizzato).
• Una pagina di changelog creata con voci <Update> e con rss: true nel frontmatter (vedi Attiva con rss: true).

Avvio rapido

Apri il tuo dashboard, vai a Integrations → What's New widget, configura la pagina e le opzioni del launcher e copia lo snippet generato. È simile a questo:

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

Incollalo nell'HTML della tua app, prima del tag di chiusura </body>. Al caricamento, aggiunge nell'angolo un launcher flottante What's new. Facendo clic, il changelog viene aperto in un modale; un indicatore delle novità non lette appare quando è presente una voce che il visitatore non ha ancora visualizzato.

Blocca una versione o ospita autonomamente

Il widget è open source e lo snippet ospitato qui sopra fornisce sempre la versione più recente, l'impostazione predefinita corretta per la maggior parte dei siti. Se preferisci bloccare una versione nota o fornire direttamente il file, il repository jamdesk-widget offre altri due modi per caricarlo.

Blocca una versione con jsDelivr. Carica una release contrassegnata dal CDN e i byte non cambieranno:

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

Ospita autonomamente. Scarica widget.js dall'ultima release e forniscilo dalla tua origine. È utile quando una policy script-src restrittiva impedisce l'uso di script di terze parti.

In entrambi i casi, imposta data-base sull'origine *.jamdesk.app: lo snippet ospitato lo ricava dall'URL dello script, ma un CDN o il tuo server non possono farlo. Ogni release pubblica un hash Subresource Integrity, così puoi bloccare i byte esatti. Il README del repository descrive tutti e tre i percorsi di installazione.

Attiva con rss: true

Il widget legge la voce più recente dallo stesso feed che alimenta il tuo RSS, quindi una pagina alimenta il widget solo quando il frontmatter imposta 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>

Senza rss: true, il widget viene caricato ma non mostra voci e il launcher rimane nascosto. Una pagina della documentazione che si limita a dimostrare il componente <Update> (senza rss: true) viene correttamente esclusa, quindi una data dimostrativa non attiva mai l'indicatore.

Configura lo snippet

Ogni opzione è un attributo data- del tag script. La scheda del dashboard li inserisce automaticamente, ma puoi anche modificare manualmente lo snippet.

Indica qualsiasi pagina nel modale

data-page apre qualsiasi percorso del tuo sito di documentazione, non solo /changelog. Il modale visualizza la pagina indicata, ad esempio un singolo annuncio o una nota di migrazione, senza gli elementi di navigazione del sito. Indicala ovunque sia utile un contenuto mirato e contestuale:

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

Due comportamenti rimangono legati al feed del changelog, quindi tienili presenti quando la pagina non è un changelog:

• L'indicatore delle novità non lette segue la voce più recente del changelog, non la pagina visualizzata nel modale. Imposta data-unread="off" quando il modale apre altro, altrimenti l'indicatore si attiva per aggiornamenti del changelog che il visitatore non vede in quella pagina.
• Il launcher flottante appare automaticamente solo quando il changelog contiene una voce (vedi Attiva con rss: true). Per incorporare una pagina in un sito senza changelog, collega un tuo elemento con data-trigger. Il tuo elemento verrà visualizzato comunque.

Modalità del launcher

Quando colleghi un tuo elemento, il widget aggiunge l'indicatore delle novità non lette a quell'elemento e non visualizza mai un pulsante flottante (quindi data-position e data-label non vengono più applicati):

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

Dimensiona il modale

Il modale si apre a 560 × 680 px. Imposta data-width e data-height per modificarne le dimensioni. Un numero senza unità viene interpretato come pixel; puoi anche usare qualsiasi valore px, vw, vh, rem, em o %:

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

Entrambe le dimensioni sono limitate in modo responsivo (larghezza 92vw, altezza 86vh), quindi anche una dimensione elevata si adatta a un telefono. Un valore non riconosciuto torna al valore predefinito. Gli angoli hanno per impostazione predefinita un raggio di 12px; imposta data-radius (qualsiasi valore CSS) per renderli squadrati o più arrotondati.

Personalizza il pulsante launcher

Per impostazione predefinita, il launcher flottante è una pillola scura. Cambiane il colore con data-button-color (sfondo) e data-button-text-color (testo), specificando per ciascuno un valore esadecimale o un nome di colore 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>

Questi due attributi definiscono lo stile solo del pulsante flottante del widget. Quando colleghi un tuo elemento con data-trigger, il launcher eredita lo stile dell'elemento, quindi non hanno effetto.

Personalizza l'indicatore delle novità non lette

L'indicatore è rosso (#e5484d) ed è attivo per impostazione predefinita. Cambiane il colore con data-unread-color (un valore esadecimale o un nome di colore CSS), oppure disattivalo con 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>

Disattivare l'indicatore mantiene il launcher e il modale. Rimuove solo l'indicatore. La sezione successiva spiega come viene tracciato lo stato "visualizzato".

Il punto non letto

Il widget conserva un indicatore delle novità non lette per ogni visitatore. Confronta l'ID della voce più recente con un valore nel localStorage del browser (una chiave per progetto). Se sono diversi, sul launcher appare un indicatore; aprendo il modale la voce viene contrassegnata come visualizzata e l'indicatore scompare fino alla pubblicazione del prossimo aggiornamento.

Poiché lo stato risiede in localStorage, è specifico del browser e del visitatore. Non sono presenti account né sistemi di tracciamento e la cancellazione dei dati del sito lo reimposta. Un visitatore che usa un browser nuovo vede l'indicatore una volta, poi non lo vede più finché non pubblichi qualcosa di nuovo.

Esempi

<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

Se il tuo sito invia una Content-Security-Policy restrittiva, consenti l'origine *.jamdesk.app in tre direttive, altrimenti il widget non esegue alcuna operazione senza mostrare errori:

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

• script-src carica widget.js.
• frame-src visualizza l'iframe del modale.
• connect-src recupera i metadati del changelog per l'indicatore delle novità non lette.

Se ne manca una, non viene mostrato alcun banner di errore: il launcher non apparirà oppure il modale resterà vuoto. Se il widget non viene visualizzato, controlla nella console del browser la presenza di violazioni CSP.

Siti protetti da password

Prossimi passi?