APNS: cos’è, come funziona Apple Push Notification Service e la sua architettura

Cos’è APNS?

Apple Push Notification Service (APNS) è il servizio proprietario di Apple per instradare le notifiche push dal server applicativo ai dispositivi degli utenti. A differenza di FCM, APNS non supporta Android o altre piattaforme — è completamente legato all’ecosistema Apple.

Il servizio opera attraverso una connessione TLS persistente che ogni dispositivo Apple stabilisce con i server APNS all’avvio. Questa connessione viene mantenuta in background e utilizzata per consegnare le notifiche con latenza minima.

APNS gestisce l’intera infrastruttura di consegna: crittografia, autenticazione, prioritizzazione e ritrasmissione quando il dispositivo non è disponibile. Lo sviluppatore deve solo fornire un payload correttamente formattato e un token push valido.

Evoluzione di APNS

Originariamente, APNS funzionava tramite un protocollo binario sulle porte 2195–2196. Dal 2015, Apple ha migrato il servizio al moderno protocollo HTTP/2, che supporta multiplexing, compressione degli header e notifiche push dal server. HTTP/2 è diventato obbligatorio nel giugno 2020.

Come funziona Apple Push Notification Service?

Il processo di consegna delle notifiche push tramite APNS si compone di cinque fasi: registrazione del dispositivo, ottenimento del token push, invio della richiesta dal server, routing APNS e consegna al dispositivo.

• Registrazione — all’avvio, l’app chiama registerForRemoteNotifications, il sistema contatta APNS
• Token — APNS restituisce un token push al dispositivo — una stringa univoca che identifica l’app sul dispositivo
• Invio — il server applicativo invia una richiesta POST a https://api.push.apple.com con token e payload
• Routing — APNS trova il dispositivo tramite il token e consegna il messaggio attraverso la connessione TLS
• Elaborazione — iOS/macOS mostra la notifica o la passa all’app in base allo stato

Se il dispositivo è non disponibile (spento o senza rete), APNS memorizza l’ultimo messaggio per ciascuna app e lo consegna al ripristino della connessione. La durata massima di memorizzazione è di 4 settimane, dopo le quali il messaggio viene eliminato.

Autenticazione APNS: Token e Certificato

Apple supporta due metodi per autenticare il server applicativo durante l’invio di notifiche push. Ogni metodo ha le proprie caratteristiche in termini di periodo di validità, gestione e facilità d’uso.

L’autenticazione basata su Token è il metodo raccomandato da Apple dal 2019. Crei un’unica chiave p8 nella Apple Developer Console, la carichi sul tuo server e firmi ogni richiesta APNS con essa. La chiave non scade mai e funziona per tutte le app del tuo account.

Quale metodo di autenticazione scegliere

Per i nuovi progetti, l’autenticazione basata su Token è chiaramente preferibile: una chiave p8 per l’intero account, illimitata, senza vincoli di ambiente. Il metodo basato su Certificato (.p12) è ancora utilizzato in progetti legacy ma richiede sostituzione annuale e certificati separati per Sandbox e Production. Considera la scadenza del certificato quando pianifichi CI/CD.

Tipi di notifiche push APNS

APNS supporta tre tipi di notifiche push, che differiscono per comportamento sul dispositivo e requisiti degli attributi della richiesta. La scelta del tipo dipende dallo scenario UX e dall’urgenza del messaggio.

• Alert — notifica standard con titolo, testo e pulsanti di azione opzionali
• Background — consegna silenziosa di dati (push silenzioso) senza mostrare all’utente, gestito in application:didReceiveRemoteNotification
• VOIP — tipo speciale per app VoIP (PushKit), consegnato immediatamente anche quando l’app è chiusa

Per le notifiche Background, devi specificare la chiave content-available: 1 e impostare la priorità su 5 (consegna efficiente dal punto di vista energetico). Il sistema può limitare il numero di notifiche in background se l’app non le elabora tempestivamente.

Configurazione della priorità di consegna

APNS supporta due valori di priorità: 10 (consegna immediata) e 5 (efficiente dal punto di vista energetico). Per le notifiche alert, usa 10 — l’utente deve riceverle immediatamente. Per le notifiche background, usa 5 — il sistema può ritardare la consegna per risparmiare batteria. Una priorità errata per background può portare al rifiuto di APNS.

Formato del payload APNS

APNS accetta payload in formato JSON con dimensione massima di 4 KB per le notifiche regolari e 5 KB per VOIP. Il payload contiene il dizionario aps obbligatorio con le impostazioni di visualizzazione e campi personalizzati opzionali.

{
    "aps": {
        "alert": {
            "title": "Nuovo messaggio",
            "body": "Hai 3 chat non lette"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

La chiave thread-id raggruppa le notifiche nel Centro Notifiche iOS. La chiave category collega la notifica a una UNNotificationCategory per mostrare i pulsanti di azione. Senza queste chiavi, tutte le notifiche vengono visualizzate singolarmente.

Campi personalizzati nel payload APNS

Oltre al dizionario aps obbligatorio, il payload APNS può contenere qualsiasi campo personalizzato al livello superiore. Questi campi sono accessibili all’app tramite il dizionario userInfo durante l’elaborazione della notifica. I dati personalizzati sono utili per passare identificatori di entità, schermate o collegamenti. La dimensione massima del payload è di 4 KB, quindi evita di trasferire grandi volumi di dati tramite push; caricali tramite API dopo aver aperto la notifica.

Esempio di invio tramite API HTTP/2

Per inviare una notifica push dal server, devi eseguire una richiesta POST all’endpoint APNS con gli header di autenticazione corretti. Di seguito un esempio in Node.js che utilizza l’autenticazione basata su Token.

const http2 = require("http2")
const fs = require("fs")
const jwt = require("jsonwebtoken")

const token = jwt.sign(
    { iss: "TEAM_ID", iat: Math.floor(Date.now() / 1000) },
    fs.readFileSync("AuthKey.p8"),
    { algorithm: "ES256", keyid: "KEY_ID" }
)

const payload = JSON.stringify({
    aps: { alert: { title: "Ciao!", body: "Push di test" } }
})

const client = http2.connect(
    "https://api.push.apple.com"
)

const req = client.request({
    ":method": "POST",
    ":path": "/3/device/DEVICE_PUSH_TOKEN",
    "authorization": "bearer " + token,
    "apns-push-type": "alert",
    "apns-topic": "com.example.app",
    "apns-priority": "10"
})
req.end(payload)

req.on("response", (headers) => {
    if (headers[":status"] === 200) {
        console.log("Push inviato con successo")
    }
})

Dopo l’invio, APNS restituisce lo stato HTTP 200 in caso di consegna riuscita o un codice di errore con descrizione nel corpo della risposta. È importante gestire gli errori token-unregistered (410) — questi token devono essere rimossi dal server, poiché l’app è stata eliminata dal dispositivo.

Errori APNS e loro gestione

APNS restituisce codici di stato HTTP per ogni richiesta di invio. La consegna riuscita restituisce lo stato 200. Gli errori richiedono diverse strategie di gestione. BadDeviceToken (400) o Unregistered (410) — il token del dispositivo è obsoleto e deve essere rimosso dal server. PayloadTooLarge (413) — il limite di 4 KB è stato superato, riduci il payload.

TooManyRequests (429) — limite di richieste superato. APNS imposta una quota sul numero di invii al secondo. Quando ricevi 429, implementa un backoff esponenziale (exponential backoff) e riprova. Si raccomanda di non superare 100 richieste al secondo per connessione HTTP/2.

Errori lato APNS — 500 e 503 (Errore Interno del Server / Servizio Non Disponibile). Sono guasti temporanei dell’infrastruttura Apple. In questi casi, riprova con un ritardo di 1–5 secondi, non più di 3 tentativi. Errori 5xx persistenti con un server completamente operativo sono rari e solitamente legati a problemi di connessione TLS.

Per gli ambienti di Production, assicurati di implementare la registrazione di tutti gli errori APNS con token, codice di errore e ora. Ciò aiuterà a identificare rapidamente problemi con certificati, quote o token di dispositivi specifici. Controlla regolarmente le date di scadenza dei certificati se utilizzi l’autenticazione basata su Certificato.