Torna al blog

Come funzionano le notifiche push: APNs e FCM spiegati

Come funzionano le notifiche push: APNs e FCM spiegati

Dall'esterno una notifica push sembra semplice: qualcosa accade su un server e, un secondo dopo, un telefono si illumina. In mezzo ci sono due reti di consegna gestite da Apple e Google, e nessuna notifica raggiunge un telefono senza passare per una delle due.

  • APNs, Apple Push Notification service, consegna ogni push a iPhone, iPad, Mac e Apple Watch.
  • FCM, Firebase Cloud Messaging, consegna ai dispositivi Android con i servizi Google Play, e può anche inviare a iOS inoltrando i messaggi ad APNs.

Questa guida segue una singola notifica dal tuo server alla schermata di blocco su entrambe le piattaforme, con i dettagli che emergono solo quando lo fai girare in produzione. Gestiamo entrambe le pipeline dietro Pocket Alert, quindi gli esempi vengono da ciò che rilasciamo davvero.

Le quattro parti in gioco

  1. Il tuo server, che Apple chiama provider. Decide che qualcosa deve essere inviato.
  2. Il servizio push, APNs o FCM. Accetta la richiesta e la instrada.
  3. Il dispositivo. Il sistema operativo mantiene una connessione cifrata e di lunga durata verso Apple o Google e riceve le push di tutte le app su quella connessione.
  4. L'app. Si è registrata per le notifiche e possiede il token a cui è indirizzata la push.

Il terzo punto spiega perché la push consuma poca batteria. Il telefono non interroga mai il tuo server. Una sola connessione, condivisa da tutte le app, resta aperta, e il servizio push la usa per inviare quando c'è qualcosa da consegnare.

Passo 1: il dispositivo ottiene un token

Quando un'app si registra per le notifiche remote, il sistema operativo le consegna un token: un indirizzo opaco per "questa app su questo dispositivo". L'app invia il token al tuo server, che lo salva.

  • Un token dispositivo APNs è unico per app e dispositivo. Apple consiglia di non memorizzarlo nella cache dell'app: cambia quando un utente ripristina da un backup, passa a un nuovo dispositivo o reinstalla il sistema operativo.
  • Un token di registrazione FCM svolge lo stesso ruolo su Android, e FCM lo aggiorna secondo una propria pianificazione.

I token diventano obsoleti di continuo. Mantenere aggiornati i token salvati è gran parte del lavoro necessario per gestire le push.

Passo 2: il tuo server dimostra la propria identità

APNs

APNs usa HTTP/2 su TLS 1.2 o successivo, all'indirizzo api.push.apple.com per la produzione e api.sandbox.push.apple.com per le build di sviluppo, sulla porta 443 o 2197. Esistono due modi per autenticarsi:

  • Basata su token. Crei una chiave di firma .p8 nel tuo account sviluppatore Apple e firmi un JWT breve con ES256, contenente il tuo Team ID e l'ID della chiave. Apple vuole che il JWT venga rigenerato non più di una volta ogni 20 minuti e non meno di una volta ogni 60. Se invii un JWT più vecchio ottieni 403 ExpiredProviderToken; se lo rigeneri troppo spesso ottieni 429 TooManyProviderTokenUpdates.
  • Basata su certificato. Un certificato client TLS per ogni app, valido per un anno, che va poi rinnovato.

L'autenticazione tramite token è quella da usare. Una sola chiave copre tutte le tue app e non scade ogni anno.

FCM

L'API HTTP v1 di FCM accetta un token di accesso OAuth 2.0 di breve durata ottenuto da un service account Google, con lo scope firebase.messaging. La vecchia API "legacy" con una chiave server statica è stata deprecata nel 2023 e dismessa da luglio 2024, quindi il codice che invia ancora Authorization: key=... non funziona più.

Passo 3: la richiesta

Invio ad APNs

Ogni push è una POST HTTP/2 verso /3/device/<device token>, con alcuni header che ne cambiano la gestione:

curl --http2 \
  -H "authorization: bearer $APNS_JWT" \
  -H "apns-topic: com.example.alerts" \
  -H "apns-push-type: alert" \
  -H "apns-priority: 10" \
  -d '{"aps": {"alert": {"title": "Backup failed", "body": "db-01: pg_dump exited with code 1"}, "sound": "default", "interruption-level": "time-sensitive"}}' \
  "https://api.push.apple.com/3/device/$DEVICE_TOKEN"
  • apns-topic è il bundle ID della tua app.
  • apns-push-type indica il tipo di push: alert per una notifica visibile, background per una push dati silenziosa, e alcuni altri.
  • apns-priority è 10 per consegnare subito, 5 per lasciare che decida lo stato di alimentazione del dispositivo, oppure 1 per privilegiare il risparmio energetico senza svegliare il dispositivo.
  • apns-expiration imposta per quanto tempo APNs deve continuare a riprovare. 0 significa un solo tentativo e nessuna memorizzazione.
  • apns-collapse-id permette a una notifica più recente di sostituire una più vecchia con lo stesso id.

Il payload è JSON con un dizionario aps e ha un limite di 4 KB (5 KB per VoIP).

Invio a FCM

FCM accetta un messaggio JSON per richiesta:

curl -X POST "https://fcm.googleapis.com/v1/projects/$PROJECT_ID/messages:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "token": "DEVICE_REGISTRATION_TOKEN",
      "notification": { "title": "Backup failed", "body": "db-01: pg_dump exited with code 1" },
      "android": { "priority": "high", "notification": { "channel_id": "alerts_high" } }
    }
  }'

Un messaggio notification viene mostrato dal sistema quando l'app è in background. Un messaggio data viene passato all'app perché lo gestisca. In entrambi i casi il limite del payload è di 4.096 byte.

Passo 4: la consegna, o l'attesa

Se il telefono è online, la push scende sulla connessione aperta e appare in pochi istanti. Se non lo è:

  • APNs memorizza la notifica per un massimo di 30 giorni, a seconda di apns-expiration, ma conserva una sola notifica per app e per dispositivo. Se ne invii cinque mentre il telefono è in modalità aereo, di solito vedrà solo l'ultima. Apple non garantisce nemmeno che sia la più recente.
  • FCM conserva i messaggi per il loro time to live, quattro settimane per impostazione predefinita e al massimo 28 giorni. I messaggi raggruppabili si sostituiscono a vicenda, con un massimo di quattro collapse key per dispositivo.

Anche la priorità influisce sui tempi. Su iOS, le push con priorità 5 e 1 possono essere raggruppate, limitate o scartate. Su Android, i messaggi con priorità normal possono attendere che il dispositivo esca dalla modalità Doze, mentre quelli con priorità high vengono consegnati immediatamente. FCM controlla anche come usi questo privilegio: i messaggi ad alta priorità che non producono una notifica visibile possono essere declassati silenziosamente a normali nel tempo.

Quanto suona: livelli di interruzione e canali

La consegna è una cosa. Se il telefono emette un suono è un'altra, e le due piattaforme la gestiscono in modo diverso.

iOS (dalla versione 15) assegna a ogni notifica un livello di interruzione:

  • passive la aggiunge alla lista senza accendere lo schermo né riprodurre un suono.
  • active è il valore predefinito.
  • time-sensitive può superare Full immersion e il riepilogo delle notifiche. Gli utenti possono disattivarlo per singola app.
  • critical suona sempre, anche con Non disturbare attivo e con l'interruttore silenzioso inserito. Richiede un'autorizzazione (entitlement) che Apple concede su richiesta, dopo una verifica.

Android (dalla versione 8) inserisce ogni notifica in un canale, e il canale determina l'importanza: suono, vibrazione, notifica a comparsa, comportamento con Non disturbare. È l'app a creare i canali, ma una volta che un canale esiste, il suo comportamento appartiene all'utente. L'app non può modificarlo in seguito.

Quest'ultima regola ha conseguenze concrete. Quando abbiamo fatto suonare gli avvisi critici di Pocket Alert anche in modalità silenziosa, il canale critico esistente non poteva essere passato a un audio da sveglia a posteriori. La soluzione è stata un secondo canale con un nuovo id, che il server seleziona solo per le build dell'app che lo creano, perché inviare a un canale che l'app non ha mai creato significa che la notifica non viene mostrata affatto.

Su Android 13 e versioni successive c'è un ulteriore vincolo: l'app deve avere il permesso runtime POST_NOTIFICATIONS, e su una installazione nuova le notifiche restano disattivate finché l'utente non lo concede.

Cosa si rompe in produzione

  • Token obsoleti. APNs risponde 410 Unregistered per un token non più valido. Smetti di inviare a quel token e cancellalo.
  • Ambiente sbagliato. Il token di una build di sviluppo inviato all'host di produzione fallisce con 400 BadDeviceToken.
  • Payload troppo grandi. 413 PayloadTooLarge oltre i 4 KB. La causa più comune sono le lunghe righe di log nel corpo di un avviso.
  • Priorità declassata. I messaggi Android ad alta priorità che non mostrano mai nulla perdono la priorità.
  • Notifiche disattivate. La push viene consegnata e l'utente non la vede mai, perché il permesso è stato negato o il canale è silenziato.

La scorciatoia

Tutto questo vale la pena di costruirlo quando l'app è il tuo prodotto e invii agli utenti. Per avvisi destinati a te o al tuo team è molta infrastruttura: un account sviluppatore per piattaforma, chiavi di firma, storage dei token, due formati di richiesta e due modelli di priorità.

Un servizio di notifiche push gestisce entrambe le pipeline al posto tuo. Con Pocket Alert invii una sola richiesta, senza token né certificati propri:

curl -X POST https://api.pocketalert.app/v1/messages \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Backup failed", "message": "db-01: pg_dump exited with code 1", "level": "high"}'

Il campo level viene tradotto per ogni piattaforma:

  • silent è una notifica passiva senza suono su iPhone, e va su un canale silenzioso su Android.
  • low è passiva su iPhone e di importanza bassa su Android.
  • default è una notifica normale su entrambe.
  • high è time-sensitive su iPhone e ad alta priorità su Android.
  • critical ignora Non disturbare su Android. Su iPhone arriva come time-sensitive, e il suono completo degli avvisi critici verrà introdotto man mano che Apple concede l'autorizzazione.

Ne parliamo meglio in avvisi critici, e sull'API in sé in cos'è un'API di notifiche push.

FAQ

APNs garantisce la consegna?

No. APNs e FCM operano entrambi con la modalità best-effort. APNs conserva solo l'ultima notifica per un dispositivo offline, e nessuno dei due servizi garantisce quando un messaggio arriva. La documentazione di Google va oltre e afferma che FCM non andrebbe usato per avvisi di emergenza critici per la vita. Per il paging di reperibilità, considera la push come il canale più veloce, non l'unico.

Perché servono sia APNs sia FCM?

Gli iPhone accettano push solo tramite APNs. I dispositivi Android con i servizi Google Play le ricevono tramite FCM. Se i tuoi utenti usano entrambe le piattaforme, il tuo server parla con entrambe, direttamente o tramite FCM, che può inoltrare ad APNs per tuo conto.

FCM può inviare notifiche a un iPhone?

Sì. Carichi la tua chiave di autenticazione APNs su Firebase, e FCM consegna a iOS inoltrando il messaggio ad APNs. I messaggi dati verso dispositivi Apple devono essere inviati con priorità normale.

Quanto può essere grande una notifica push?

4 KB per un payload APNs (5 KB per le push VoIP) e 4.096 byte per un messaggio FCM. I testi lunghi vanno nella tua app o in un link, non nella push.

Cos'è un token dispositivo?

È un indirizzo per una singola app su un singolo dispositivo, emesso da Apple o Google. Il tuo server invia le push a quell'indirizzo. Può cambiare in qualsiasi momento, quindi i server devono accettare i token aggiornati ed eliminare quelli che APNs o FCM segnalano come non validi.

Crea un account gratuito Pocket Alert per evitare chiavi e token, oppure confronta gli altri servizi nelle alternative.

Condividi questo articolo