Il service worker spiegato semplice: il motore delle web push

Ogni guida sulle web push, a un certo punto, ti chiede di caricare un file nella root del dominio. Si chiama service worker, di solito ha un nome tipo natom-sw.js, e la maggior parte dei tutorial lo liquida in una riga: "caricalo e vai avanti". Poi le notifiche non arrivano, e nessuno sa dove guardare.

Questo articolo spiega cosa fa quel file, perché deve stare proprio lì, e quali sono i tre o quattro modi in cui va storto. Non serve saper programmare: serve capire il meccanismo, perché è il meccanismo che decide se le tue push arrivano oppure no.

Il problema che il service worker risolve

Una pagina web vive finché è aperta. Chiudi la scheda, e tutto il codice di quella pagina smette di esistere. È il modello del web da trent'anni, ed è anche il motivo per cui, per molto tempo, un sito non poteva "chiamarti" quando non eri lì.

Le notifiche push hanno bisogno esattamente dell'opposto: qualcosa che resti in ascolto anche quando il sito è chiuso, il browser è in secondo piano, o il telefono è in tasca. Quel qualcosa è il service worker.

Un service worker è un piccolo programma JavaScript che il browser installa per il tuo dominio e tiene da parte. Non ha una finestra, non ha una pagina, non lo vedi. Il browser lo sveglia solo quando succede qualcosa che lo riguarda, per esempio l'arrivo di una notifica, gli fa fare il suo lavoro, e lo rimette a dormire.

Dal punto di vista di chi gestisce un sito, questa è la parte importante: il service worker è l'unico pezzo del tuo sito che esiste anche quando nessuno lo sta guardando.

Cosa succede quando parte una push

Vale la pena seguire il percorso completo di una notifica, perché il service worker sta esattamente nel mezzo.

1. Tu, dalla dashboard di Natom, scrivi titolo e testo e premi invia.
2. Natom consegna il messaggio al servizio push del browser (Google per Chrome, Apple per Safari, Mozilla per Firefox). Ogni iscritto ha un "indirizzo" presso quel servizio, creato al momento dell'iscrizione.
3. Il servizio push recapita il messaggio al dispositivo del lettore.
4. Il browser del lettore, anche se è chiuso, sveglia il service worker del tuo dominio e gli passa il messaggio.
5. Il service worker legge titolo, testo, immagine e link, e chiede al sistema operativo di mostrare la notifica.
6. Il lettore clicca: il service worker si sveglia di nuovo, apre il link, e registra il click.

Se il passo 4 fallisce, cioè se il browser non trova un service worker valido per il tuo dominio, la notifica muore lì. Non c'è errore visibile, non c'è avviso, non c'è nulla. È il motivo per cui "le push non arrivano" è quasi sempre un problema di service worker, e quasi mai un problema di invio.

Perché deve stare nella root

Qui c'è la regola che confonde più persone. Un service worker può controllare solo le pagine che stanno sotto il percorso da cui è stato caricato. Se lo carichi da tuosito.it/js/sw.js, controlla solo tuosito.it/js/ e le sue sottocartelle. Se lo carichi da tuosito.it/sw.js, controlla tutto il sito.

Per questo ogni piattaforma di push ti chiede di metterlo nella root del dominio. Non è una preferenza, è una regola del browser: un service worker in una sottocartella non riceverà le notifiche per la home, per gli articoli, per nulla che stia fuori da quella cartella.

È anche il motivo per cui una CDN o un plugin non possono "ospitare" il service worker per te: deve rispondere dal tuo dominio, all'indirizzo tuosito.it/natom-sw.js. Il plugin WordPress di Natom, per esempio, lo scrive fisicamente nella cartella principale del sito proprio per questo.

Cosa contiene, davvero

Aprire il file spaventa meno di quanto sembri. Un service worker per le push fa tre cose, e il codice di Natom fa esattamente queste tre e nient'altro:

Ascolta l'evento "push". Quando arriva un messaggio, lo legge (è un piccolo pacchetto con titolo, testo, icona, immagine e link) e chiama la funzione del browser che mostra la notifica.

Ascolta il click. Quando il lettore tocca la notifica, la chiude, apre il link nel browser e manda un segnale a Natom per contare il click. È così che nascono le statistiche di CTR.

Conta le consegne. In una piccola percentuale di casi, scelta a caso, manda un segnale "questa notifica è stata mostrata". Da quel campione Natom stima le impressioni senza registrare miliardi di eventi. Su questo torniamo in un altro articolo, ma è il motivo per cui le statistiche restano leggere anche su siti da centinaia di migliaia di iscritti.

Tutto qui. Nessuna libreria, nessun framework, una quarantina di righe. Questo è voluto: ogni riga in più nel service worker è un punto in più dove qualcosa può rompersi in silenzio.

I quattro modi in cui va storto

In ordine di frequenza, da quello che vediamo sui siti che si iscrivono a Natom.

1. Il file non c'è, o non è nella root

Il caso più comune. Il tecnico lo carica in una sottocartella, oppure lo carica nella root del server ma il dominio punta a un'altra cartella. Verifica: apri tuosito.it/natom-sw.js nel browser. Devi vedere del codice JavaScript. Se vedi una pagina 404, o la home del sito, il file non è dove deve stare.

2. Viene servito come pagina, non come script

Alcuni CMS intercettano ogni indirizzo e rispondono con una pagina HTML, anche per i file. Il browser chiede il service worker, riceve HTML, e rifiuta di registrarlo. Verifica: sempre aprendo l'indirizzo, se vedi il layout del sito attorno al codice, o il codice non compare affatto, è questo. Serve una regola sul server che lasci passare quel file così com'è.

3. Un vecchio service worker occupa il posto

Se il sito usava un altro servizio di notifiche, il suo service worker è ancora registrato nei browser dei lettori. Due service worker sullo stesso dominio si contendono le notifiche, e di solito vince quello sbagliato. Lo snippet di Natom rimuove le vecchie sottoscrizioni prima di crearne una nuova, ma il vecchio file va tolto dal server, altrimenti continua a farsi registrare. Ne parliamo in dettaglio nella guida alla migrazione.

4. Il sito non è in HTTPS

I service worker funzionano solo su connessioni sicure. Un sito in HTTP non può registrarne uno, punto. Se il tuo sito ha ancora pagine servite in HTTP, quelle pagine non potranno mai iscrivere nessuno.

Una nota sul cambiare il file

Il browser tiene una copia del service worker e la aggiorna da solo, controllando periodicamente se il file sul server è cambiato. Questo significa due cose pratiche. Primo: quando aggiorni il file, i lettori lo ricevono nel giro di un giorno, non all'istante. Secondo: non devi mai fare in modo che il server metta quel file in cache per lunghi periodi, altrimenti gli aggiornamenti non arrivano mai. Una cache breve, o nessuna, è la scelta giusta.

La verifica in trenta secondi

Prima di scrivere a chiunque, fai questi quattro controlli nell'ordine. Coprono il 95% dei casi che vediamo.

1. Apri tuosito.it/natom-sw.js nel browser. Se vedi codice JavaScript che inizia con un commento e contiene la parola push, il file c'è ed è servito bene. Se vedi una pagina del sito o un errore, fermati qui: è il problema.
2. Controlla il lucchetto. L'indirizzo deve iniziare con https://. Se il browser segnala contenuti misti o la pagina è in http://, i service worker non partono.
3. Apri gli strumenti per sviluppatori (F12 in Chrome), scheda Application, voce Service Workers. Devi vedere un solo service worker registrato per il tuo dominio, con stato "activated". Se ne vedi due, uno è del vecchio fornitore e va rimosso. Se non ne vedi nessuno, torna al punto 1.
4. Manda una push di prova dalla dashboard di Natom al tuo dispositivo di test (quello marcato con ?natom_test=1). Se arriva, il percorso completo funziona; se non arriva ma i tre punti sopra sono a posto, il problema è nel permesso del browser, non nel service worker.

Trenta secondi, nessuno strumento da installare, e sai esattamente a chi chiedere cosa.

Cosa portarsi via

Il service worker è il pezzo del tuo sito che vive anche quando il sito è chiuso, ed è l'unico che può ricevere una notifica. Deve stare nella root del dominio, deve essere servito come JavaScript, deve essere l'unico, e il sito deve essere in HTTPS. Se una di queste quattro condizioni manca, le push non arrivano, e non ti viene detto.

La buona notizia è che si verifica in dieci secondi: apri tuosito.it/natom-sw.js e guarda cosa risponde. Se hai un sito WordPress, il plugin di Natom fa tutto questo da solo e ti dice nella pagina impostazioni se il file risponde correttamente.

Se invece vuoi partire dalle basi, il nostro articolo su cosa sono le web push e come funzionano mette il service worker nel quadro completo. E quando sei pronto, l'account gratuito include tutto quello che serve per provare, service worker compreso.