Apple Push Notification Service (APNs): setup
APNs e il servizio nativo Apple per inviare notifiche push a iOS, iPadOS, watchOS, tvOS e macOS. Anche se molti progetti usano un layer come Firebase o OneSignal, conoscere APNs e essenziale per debugging e per scenari avanzati come notifiche silenziose, Live Activities e Critical Alerts.
Chiavi e certificati
Apple raccomanda l'uso di token-based authentication tramite chiave .p8 generata dal portale Developer. La chiave funziona per tutti gli ambienti e non scade. In alternativa puoi usare certificati .p12, separati per sandbox e produzione, ma con scadenza annuale e gestione più complessa.
Payload e topic
Il payload e un JSON contenente la chiave aps (alert, badge, sound, content-available, mutable-content) e campi custom. Il topic e il bundle id dell'app per push standard, ma cambia per Live Activities (.push-type.liveactivity) e Critical Alerts. La priority controlla la consegna immediata o ritardata.
Sandbox vs production
Le build TestFlight e store usano l'ambiente production, mentre le build con development profile usano sandbox. Server URL differenti (api.push.apple.com vs api.sandbox.push.apple.com). Inviare alla URL sbagliata risulta in BadDeviceToken.
HTTP/2 e connessione persistente
APNs usa HTTP/2 multiplex su una connessione persistente. Una singola connessione gestisce migliaia di push concorrenti. Per backend di scala, mantieni un pool di connessioni HTTP/2 persistenti. Token JWT firmato con .p8 ha scadenza 60 minuti: rinnova prima dell'expiration.
Live Activities
iOS 16.1+ supporta Live Activities (timer, score sportivi, ordini). Richiedono push-type=liveactivity e gestiscono ActivityKit. Token diversi dai push standard, scadono dopo che l'attività finisce. Implementazione richiede sia codice swift sia backend con header HTTP specifici.
Push Notification Console
Apple ha introdotto la Push Notifications Console: tool web per inviare push di test senza scrivere codice backend. Utile per QA rapido. Supporta APNs sandbox e production con il tuo team account. Sostituisce in molti casi tool esterni come Pusher.
Best practice di payload
Mantieni il payload sotto 4 KB (4096 byte). Usa thread-id per raggruppare notifiche correlate. Usa interruption-level per "critical" (importante), "time-sensitive" (priorità), "passive" (background). Su Focus mode, solo time-sensitive e critical bypassano i filtri.
Background tasks da push
Per eseguire codice in background da push, usa content-available: 1 nel payload aps. iOS sveglia l'app per max 30 secondi. Usa per sync dati, refresh token, cache update. Non per logica utente critica (puo non essere eseguito se iOS decide diversamente). Combina con BGTaskScheduler per maggiore affidabilità.
Critical Alerts
Per app medicali, di sicurezza, di emergenza, Apple permette Critical Alerts che bypassano Do Not Disturb e Focus mode. Richiede entitlement specifico (com.apple.developer.usernotifications.critical-alerts) approvato manualmente da Apple. Processo lungo (settimane), giustificazione tecnica obbligatoria. Una volta concesso, puoi inviare con interruption-level=critical.
Procedura passo-passo
- Crea una chiave APNs (.p8) nel portale Developer.
- Annota Key ID e Team ID.
- Carica la chiave nel tuo backend o in console Firebase/OneSignal.
- Abilita la capability Push Notifications in Xcode.
- Richiedi il permesso di notifiche tramite UNUserNotificationCenter.
- Ottieni il device token e invialo al server.
- Invia un push di test con curl o tool come Pusher.
Provider servers
Backend che invia APNs deve gestire: connection pool HTTP/2, JWT generation con .p8 key, retry su errori transitori (429, 500), feedback su token invalid (rimuovere dal DB). Librerie consolidate: Pigeon (Node), python-apns2, apns4j (Java). Per scale grandi, considera gateway gestiti (AWS SNS, Pusher Beams, OneSignal) che astraggono APNs e FCM.
Notification Service Extension
Notification Service Extension permette di modificare il payload prima del display: scaricare media, decrypt contenuto E2E, modificare title. Configura come target Xcode separato. Tempo limite 30 secondi. Utile per chat E2E (Signal, Telegram), media-rich notifications, custom badge logic. Implementazione richiede attenzione a memoria e tempo di esecuzione.
Errori comuni e come risolverli
- BadDeviceToken: ambiente sandbox/production non corrispondente.
- InvalidProviderToken: chiave .p8 scaduta o non corretta.
- MissingTopic: il bundle id non e impostato come apns-topic header.
- Push silenziosi non eseguiti: priority deve essere 5, non 10.
- Notifiche duplicate: chiama removeDeliveredNotifications quando necessario.
Domande frequenti
D: Posso inviare APNs direttamente senza Firebase?
R: Si, tramite HTTP/2 verso api.push.apple.com.
D: Le Live Activities richiedono APNs separati?
R: Si, usano un push token diverso e push-type=liveactivity.
D: Le notifiche funzionano in DND?
R: Solo se sono Critical Alerts con entitlement approvato da Apple.
D: I push su watchOS sono separati?
R: Si, watchOS ha proprio device token. Configura entitlement watchOS Push nel target Watch App.
Best practice operative
Mantieni .p8 key in secret management (1Password, AWS Secrets Manager). Rotazione periodica come parte del security review. Monitoring delivery success rate: se cala, indagare causa. Documentare team ownership della chiave e processo di rinnovo. Mai committarla in repo, anche privati.
Per scenari di alta scala, considera servizi gestiti come Amazon SNS, Pusher Beams, OneSignal o Firebase Cloud Messaging che astraggono APNs e FCM dietro una sola API. Riducono complessita di gestione, gestiscono retry e error handling, forniscono dashboard analytics. Free tier sufficiente per molti casi, costi crescono con volume.
Hai bisogno di aiuto?
Se vuoi sviluppare la tua app con G Tech Group, scrivici tramite il modulo di contatto.