Incorpora una pagina

Aggiungi un trigger «What's new?» al tuo prodotto. Un pulsante o un launcher mobile apre le voci del changelog della documentazione in una finestra modale. Un punto segnala gli aggiornamenti non letti per ogni visitatore. Incolla un solo tag <script>. Jamdesk ospita il widget e ne gestisce le versioni.

Gli aggiornamenti non letti sono basati sul changelog. Il widget può però aprire qualsiasi pagina della documentazione nella finestra modale. Vedi Indirizzare la finestra modale a qualsiasi pagina.

Gli screenshot mostrano l'interfaccia in inglese.

Provalo dal vivo

Questa pagina esegue il widget reale. Fai clic sul pulsante per aprire la finestra modale che vedranno i tuoi visitatori, con il changelog di questo sito:

Questo pulsante è il componente MDX <Widget>. Usalo per incorporare il widget in una pagina della documentazione Jamdesk. Basta un tag, non serve uno script e il widget trova autonomamente il tuo sito. Per incorporare il widget nel tuo prodotto o nella tua app, dove i componenti MDX non vengono eseguiti, usa lo snippet <script> qui sotto. Il widget e la finestra modale sono gli stessi. Il resto di questa pagina riguarda lo script.

Prerequisiti

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

Avvio rapido

Apri la dashboard e vai a Integrations → What's New widget. Imposta la pagina e le opzioni del launcher. 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>. Aggiunge nell'angolo un launcher mobile What's new. Il launcher apre il changelog in una finestra modale. Quando c'è una voce che il visitatore non ha ancora visto, appare un punto.

Blocca una versione o ospita autonomamente

Il widget è open source. Lo snippet ospitato qui sopra fornisce sempre la versione più recente. Il repository jamdesk-widget offre altri due modi per caricarlo: fissare una versione nota o servire il file autonomamente.

Fissa una versione con jsDelivr. Carica una release contrassegnata dal CDN. 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>

Ospitalo autonomamente. Scarica widget.js dall'ultima release e servilo dal tuo dominio. Usalo quando una policy script-src rigida esclude gli script di terze parti.

Imposta data-base sull'origine *.jamdesk.app per un file fissato a una versione o ospitato autonomamente. Lo snippet ospitato ricava questo valore dall'URL dello script, ma un CDN o il tuo server non possono farlo. Ogni release pubblica un hash Subresource Integrity per fissare i byte esatti. Il README del repository illustra i tre metodi di installazione.

Attiva con rss: true

Il widget legge la voce più recente del tuo feed RSS. Una pagina alimenta il widget solo se nel 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 si carica ma non mostra alcuna voce. Il launcher rimane nascosto. Una pagina della documentazione che mostra solo il componente <Update> (senza rss: true) non viene inclusa. Una data dimostrativa non attiva il punto.

Configura lo snippet

Ogni opzione è un attributo data- del tag script. La scheda della dashboard li compila. Puoi anche modificare lo snippet manualmente.

Indica qualsiasi pagina nel modale

data-page apre qualsiasi percorso del tuo sito di documentazione, non solo /changelog. La finestra modale mostra la pagina specificata senza gli elementi di navigazione del sito. Puoi usarla per un annuncio o una nota di migrazione:

<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 restano legati al feed del changelog:

• Il punto degli aggiornamenti non letti segue la voce più recente del changelog, non la pagina mostrata nella finestra modale. Imposta data-unread="off" quando la finestra modale apre un'altra pagina. Altrimenti il punto si accende per gli aggiornamenti del changelog che il visitatore non vede lì.
• Il launcher mobile appare solo quando il changelog contiene una voce (vedi Attiva con rss: true). Se il sito non ha un changelog, associa un tuo elemento con data-trigger. Il tuo elemento rimane sempre visibile.

Modalità del launcher

Un elemento associato mostra il punto degli aggiornamenti non letti. Il widget non crea un pulsante mobile e data-position e data-label non si applicano più:

<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

La finestra modale si apre con dimensioni di 560 × 680 px. Modificale con data-width e data-height. Un numero senza unità viene interpretato come pixel. Puoi usare anche valori 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>

La finestra modale è limitata a 92vw di larghezza e 86vh di altezza. Anche con dimensioni grandi, si adatta a uno smartphone. Un valore non riconosciuto viene sostituito con quello predefinito. Il raggio predefinito degli angoli è 12px. Puoi renderli squadrati o più arrotondati con data-radius (qualsiasi lunghezza CSS).

Personalizza il pulsante launcher

Per impostazione predefinita, il launcher mobile è un pulsante scuro a forma di pillola. Cambiane i colori con data-button-color (sfondo) e data-button-text-color (testo). Usa 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 mobile creato dal widget. Non hanno effetto su un elemento associato con data-trigger, che mantiene il proprio stile.

Personalizza l'indicatore delle novità non lette

Per impostazione predefinita, il punto degli aggiornamenti non letti è rosso (#e5484d) e attivo. Cambiane il colore con data-unread-color (un valore esadecimale o un nome di colore CSS). 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>

Disattivando il punto, il launcher e la finestra modale rimangono attivi. Viene rimosso solo l'indicatore.

Il punto non letto

Il widget confronta l'id della voce più recente con un valore in localStorage del browser (una chiave per progetto). Se i valori sono diversi, sul launcher appare un punto. Aprendo la finestra modale, la voce viene contrassegnata come vista. Il punto rimane disattivato fino alla pubblicazione dell'aggiornamento successivo.

Lo stato viene salvato in localStorage, per browser e visitatore. Non sono previsti account né tracciamento. Se si cancellano i dati del sito, lo stato viene reimpostato. Un visitatore che usa un nuovo browser vede il punto una volta. Il punto riappare quando 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>

Content-Security-Policy

Se il tuo sito applica una policy Content-Security-Policy rigida, consenti l'origine *.jamdesk.app in tre direttive. In caso contrario, il widget non farà nulla 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 mostra l'iframe della finestra modale.
• connect-src recupera i metadati del changelog per il punto degli aggiornamenti non letti.

Se manca una direttiva, non viene mostrato alcun messaggio di errore. Il launcher non appare oppure la finestra modale rimane vuota. Se il widget non viene visualizzato, controlla nella console del browser le violazioni CSP.

Siti protetti da password

Prossimi passi?