La Guida Definitiva alle Notifications API di JavaScript

Introduzione alle Notifications API

Le Notifications API consentono a un'applicazione web di visualizzare messaggi a livello di sistema al di fuori della scheda del browser — i piccoli popup che il sistema operativo mostra nell'angolo dello schermo. Poiché appaiono anche quando l'utente è passato a un'altra scheda o applicazione, le notifiche sono un modo diretto per presentare informazioni urgenti: un nuovo messaggio in chat, un upload completato, un promemoria del calendario.

Questa pagina copre l'intero ciclo di vita: verificare la disponibilità dell'API, richiedere il permesso all'utente, creare e personalizzare notifiche, reagire ai clic e mostrare notifiche da un service worker in modo che continuino a funzionare anche dopo la chiusura della pagina. Si conclude con le regole per evitare che le notifiche diventino fastidiose.

Alcuni punti da tenere a mente prima della prima riga di codice:

• Le notifiche richiedono una concessione esplicita del permesso da parte dell'utente. Non è possibile mostrarne una finché il permesso non è granted.
• Funzionano solo in un contesto sicuro (https://, o http://localhost durante lo sviluppo).
• L'aspetto e il comportamento di una notifica sono controllati dal sistema operativo, non dal tuo CSS. Tu fornisci il contenuto; il sistema operativo decide come renderizzarlo.

Verifica del supporto

Esegui sempre il feature-detect prima di usare l'API, in modo che il codice si degradi in modo elegante in ambienti che non la supportano (browser più vecchi, alcune webview incorporate e il rendering lato server):

if ('Notification' in window) {
  // The Notifications API is available
} else {
  console.log('This browser does not support notifications.');
}

Comprendere i permessi

Lo stato del permesso si trova nella proprietà statica Notification.permission e può essere uno di tre valori string:

• 'granted' — l'utente ha consentito le notifiche; puoi mostrarle.
• 'denied' — l'utente le ha bloccate; le chiamate per mostrare una notifica vengono silenziosamente ignorate.
• 'default' — l'utente non ha ancora deciso, il che viene trattato come 'denied' finché non si chiede.

Richiedi il permesso con Notification.requestPermission(). Restituisce una promise che si risolve con il string del permesso risultante:

Notification.requestPermission().then((permission) => {
  console.log('Permission:', permission); // 'granted', 'denied', or 'default'
});

Un pattern robusto controlla prima lo stato attuale e chiede solo quando la decisione è ancora 'default':

async function ensurePermission() {
  if (Notification.permission === 'granted') {
    return true;
  }
  if (Notification.permission === 'denied') {
    return false; // can't re-prompt; the user must change it in browser settings
  }
  const permission = await Notification.requestPermission();
  return permission === 'granted';
}

La forma basata su promise si abbina naturalmente con async/await e le più ampie Promise API.

Creare e visualizzare notifiche

Una volta che il permesso è granted, costruisci una notifica con il costruttore Notification. Il primo argomento è il titolo (obbligatorio); il secondo è un object opzioni facoltativo.

if (Notification.permission === 'granted') {
  new Notification('Hello, world!', {
    body: 'Here is the body of the notification.',
    icon: '/icon-192.png'
  });
}

La notifica appare nel momento in cui l'object viene creato — non è necessario chiamare un metodo "show" separato.

Opzioni comuni

L'object opzioni accetta molti campi. I più utili:

new Notification('New message', {
  body: 'You have 1 unread message from Alex.',
  icon: '/icon-192.png',
  tag: 'chat-alex',          // replacing an earlier "Alex" notification
  data: { conversationId: 42 },
  requireInteraction: true
});

Evitare lo spam di notifiche con tag

L'opzione tag è il modo più semplice per smettere di accumulare duplicati. Se arrivano tre messaggi dalla stessa persona, riutilizzare un unico tag fa sì che l'utente veda una singola notifica aggiornata invece di tre:

function notifyUnread(count) {
  new Notification('Inbox', {
    body: `You have ${count} unread messages.`,
    tag: 'inbox-count' // each call updates the same notification
  });
}

Eventi delle notifiche

Un'istanza di Notification genera eventi a cui puoi ascoltare. Il più importante è click, generato quando l'utente attiva la notifica:

const notification = new Notification('Interactive Notification', {
  body: 'Click me to do something',
  icon: '/icon-192.png'
});

notification.onclick = (event) => {
  event.preventDefault();    // stop the browser's default focus behavior
  window.open('https://example.com', '_blank');
  notification.close();      // remove the notification once handled
};

Gli altri eventi disponibili sono show (visualizzato), error (impossibile visualizzare) e close (chiuso). Puoi aggiungere gestori anche con addEventListener — consulta la gestione degli eventi nel DOM per il pattern generale.

Chiudere le notifiche a livello programmatico

Chiama close() per chiudere una notifica autonomamente — utile per eliminare un avviso "in download…" una volta completato il download:

const note = new Notification('Downloading…', { tag: 'download' });

// later, when the work is done:
setTimeout(() => note.close(), 4000);

Notifiche silenziose

Imposta silent: true per visualizzare una notifica senza suoni né vibrazioni — appropriato per aggiornamenti ambientali a bassa priorità:

new Notification('Silent Notification', {
  body: 'This is a silent notification.',
  silent: true
});

Notifiche da un service worker

Il costruttore Notification semplice funziona solo mentre una pagina è aperta. Per inviare notifiche quando il tuo sito è in background — o in risposta a un messaggio push del server — mostrale da un service worker usando ServiceWorkerRegistration.showNotification():

// In the page: ask the service worker to show a notification
navigator.serviceWorker.ready.then((registration) => {
  registration.showNotification('Background-capable notification', {
    body: 'This can be shown even after the tab is closed.',
    icon: '/icon-192.png',
    actions: [
      { action: 'open', title: 'Open' },
      { action: 'dismiss', title: 'Dismiss' }
    ]
  });
});

Le notifiche del service worker supportano anche i pulsanti di azione (l'array actions), che il costruttore semplice non prevede. Gestisci i clic all'interno del service worker stesso:

// In the service worker (sw.js)
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  if (event.action === 'open') {
    event.waitUntil(clients.openWindow('/inbox'));
  }
});

Questo percorso tramite service worker è ciò che alimenta il vero web push: un server invia un messaggio, la Push API risveglia il service worker e il worker chiama showNotification().

Supporto dei browser e avvertenze

• Solo contesto sicuro. Le notifiche richiedono HTTPS (o localhost). Non funzioneranno su pagine http:// semplici.
• Il permesso è persistente. Una volta che un utente sceglie 'denied', non puoi richiedere di nuovo il permesso tramite JavaScript — deve cambiarlo nelle impostazioni del sito nel browser. Non continuare a richiedere.
• iOS Safari storicamente non supportava le notifiche web; il supporto è arrivato solo per i siti aggiunti alla schermata Home come PWA. Esegui sempre il feature-detect.
• L'aspetto è controllato dal sistema operativo. Non fare affidamento su dimensioni, posizione o stile specifici — concentrati su testi chiari e brevi.

Best practice

Per far sì che le notifiche rimangano una funzionalità gradita agli utenti anziché silenziata:

• Chiedi nel contesto, dopo un gesto. Richiedi il permesso quando l'utente ha appena fatto qualcosa che rende le notifiche ovviamente utili (ad es. l'attivazione degli avvisi), mai al primo caricamento.
• Rispetta un "no". Se il permesso è 'denied', smetti. Ripetute richieste non sono nemmeno tecnicamente possibili, e insistere nell'interfaccia erode la fiducia.
• Sii tempestivo e pertinente. Invia solo notifiche che l'utente vorrebbe davvero ricevere in quel momento.
• Usale con parsimonia. Raggruppa con tag, raggruppa dove puoi e riserva le notifiche a ciò che è davvero importante — un eccesso di notifiche abitua gli utenti a ignorarle o bloccarle.
• Rendi i clic significativi. Un clic dovrebbe portare l'utente direttamente al contenuto pertinente, non semplicemente alla tua homepage.

Conclusione

Le Notifications API di JavaScript consentono alle app web di raggiungere gli utenti con messaggi tempestivi a livello di sistema — sia mentre una pagina è aperta sia, tramite un service worker, dopo che è stata chiusa. Il flusso di lavoro è coerente: esegui il feature-detect, richiedi il permesso in risposta a un gesto dell'utente, poi crea notifiche con il costruttore Notification (o con showNotification() in un worker) e rispondi agli eventi di clic. Combinando questo con un utilizzo disciplinato e parsimonioso, le notifiche diventano una funzionalità che gli utenti mantengono attiva anziché disattivare di corsa.

Pratica