Device Token: come funziona, ottenimento del token APNS e aggiornamento

Cos’è un Device Token

Device Token (token del dispositivo) è un identificatore univoco sotto forma di stringa hex che APNS (Apple Push Notification Service) genera per ogni app su un dispositivo iOS. Il token è la chiave tramite cui il server invia notifiche push a un dispositivo specifico. Senza un Device Token valido, il server non può consegnare le notifiche push — APNS rifiuta la richiesta con un errore 400 BadRequest.

Come viene formato il token

Il Device Token viene creato dal sistema iOS quando l’app contatta APNS per la prima volta dopo l’installazione. Il processo di generazione include un legame crittografico con il bundle ID dell’app e l’identificatore univoco del dispositivo (UID), dopodiché APNS restituisce all’app un token di 32 byte in formato hex (64 caratteri). Il token non è permanente — il sistema può generarne uno nuovo in determinate condizioni.

Ruolo del token nella consegna delle notifiche push

Quando il server invia una notifica push, include il Device Token nella richiesta HTTP/2 ad APNS. APNS convalida il token: se il token appartiene a un ambiente diverso (sandbox invece di production), è scaduto o è stato revocato, il server Apple restituisce un errore 410 Gone o 400 BadRequest. Solo dopo la convalida riuscita del token, APNS inizia a consegnare la notifica al dispositivo.

Differenza tra Device Token e altri identificatori

Device Token non deve essere confuso con IDFA (Identifier for Advertisers), IDFV (Identifier for Vendor) o UID (Unique Device Identifier). IDFA e IDFV sono utilizzati per pubblicità e analisi, UID è un numero di serie hardware. Device Token esiste esclusivamente per le notifiche push e non rivela informazioni sull’utente o sul dispositivo al di fuori di APNS.

Come il dispositivo ottiene e registra il token

Il processo di ottenimento del Device Token consiste in diversi passaggi obbligatori, dalla richiesta di autorizzazione all’utente all’invio del token al server. Ogni passaggio è critico — saltarne uno rende impossibile l’invio di notifiche push al dispositivo.

Richiesta di autorizzazione alle notifiche

Il primo passo è che l’app richieda all’utente l’autorizzazione a inviare notifiche tramite UNUserNotificationCenter.current().requestAuthorization. L’utente può accettare, rifiutare o selezionare opzioni facoltative (alert, badge, sound). Senza il consenso esplicito dell’utente, il sistema non emetterà un Device Token, anche se l’app chiama registerForRemoteNotifications. Dopo aver ottenuto l’autorizzazione, l’app chiama UIApplication.shared.registerForRemoteNotifications(), che avvia il processo di registrazione presso APNS.

Ottenimento del token da APNS

Dopo la registrazione, APNS restituisce il token tramite il delegato AppDelegate: application(_:didRegisterForRemoteNotificationsWithDeviceToken:). Una chiamata riuscita contiene un oggetto Data con il token, che deve essere convertito in una stringa hex per la trasmissione al server. In caso di errore, il sistema chiama application(_:didFailToRegisterForRemoteNotificationsWithError:) con una descrizione del problema: configurazione errata del certificato, indisponibilità della rete o configurazione errata del progetto.

Invio del token al proprio server

Dopo aver ricevuto il token, l’app dovrebbe inviarlo immediatamente al proprio server per l’archiviazione nel database. La richiesta API include il token, l’identificatore del dispositivo (per il mapping), l’ambiente (sandbox/production) e opzionalmente dati aggiuntivi: versione del sistema operativo, modello del dispositivo, lingua. Si consiglia di reinviare il token a ogni avvio dell’app in modo che il server abbia sempre un token aggiornato.

// Richiedere autorizzazione e registrarsi presso APNS
func registerForPushNotifications() {
    UNUserNotificationCenter.current()
        .requestAuthorization(options: [.alert, .sound, .badge]) {
        [weak self] granted, error in
        guard granted else {
            print("Autorizzazione non concessa")
            return
        }
        DispatchQueue.main.async {
            UIApplication.shared
                .registerForRemoteNotifications()
        }
    }
}

// Ottenere Device Token da APNS
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let tokenString = deviceToken
        .map { String(format: "%02.2hhx", $0) }
        .joined()
    print("Device Token: \(tokenString)")

    // Inviare token al server
    PushTokenService.shared
        .sendTokenToServer(tokenString) { success in
        if success {
            UserDefaults.standard.set(tokenString,
                forKey: "lastDeviceToken")
        }
    }
}

Gestione dei token lato server

Il lato server del sistema push deve memorizzare il Device Token nel database, associato all’utente e all’ambiente. Quando invia una notifica, il server forma una richiesta ad APNS, includendo il token nell’URL e un token JWT (o certificato) per l’autorizzazione. Una corretta gestione dei token influisce criticamente sul tasso di consegna delle notifiche push.

Struttura del database dei token

La tabella dei token sul server dovrebbe contenere almeno: Device Token (univoco), ID utente, ambiente (sandbox/production), data dell’ultimo aggiornamento e stato (attivo/inattivo). Si consiglia di aggiungere un indice sul token per una ricerca rapida durante l’invio e sull’utente per ottenere l’elenco di tutti i dispositivi di un utente. Molte app consentono a un utente di avere più dispositivi — ciascuno con il proprio token.

Autorizzazione delle richieste ad APNS

Per inviare una notifica push, il server deve autorizzare la richiesta ad APNS in due modi. Basato su certificato utilizza un certificato SSL generato in Apple Developer Console. Basato su token utilizza un JWT (JSON Web Token) con una chiave .p8 valida fino a 30 giorni senza necessità di rinnovare il certificato. L’autorizzazione basata su token è considerata più moderna ed è raccomandata da Apple per i nuovi progetti.

Formazione di una richiesta HTTP/2 APNS

La richiesta ad APNS include il metodo HTTP/2 POST, un URL con il percorso /3/device/{device_token}, intestazioni di autorizzazione e un corpo JSON con il payload. L’intestazione apns-topic deve contenere il bundle ID dell’app. apns-priority indica la priorità di consegna (5 — immediatamente, 10 — con risparmio energetico). apns-expiration imposta il tempo in secondi dall’epoca entro cui APNS tenterà di consegnare la notifica.

// Esempio di invio di push su Node.js tramite APNS HTTP/2
const http2 = require('http2');
const client = http2.connect('https://api.push.apple.com');

const deviceToken = 'abcdef0123456789...';
const payload = JSON.stringify({
    "aps": { "alert": "Hello!", "sound": "default" }
});

const req = client.request({
    ':method': 'POST',
    ':path': `/3/device/${deviceToken}`,
    'apns-topic': 'com.example.app',
    'apns-priority': '10',
    'apns-expiration': '0',
    'authorization': `bearer ${jwtToken}`
});
req.write(payload);
req.end();
req.on('response', (headers) => {
    if (headers[':status'] === '200') {
        console.log('Push inviato con successo');
    }
});

Invio batch e limitazione

Quando si inviano notifiche push a un gran numero di dispositivi, utilizzare l’invio batch con controllo della velocità. APNS raccomanda di non superare 1500 richieste al secondo per connessione. Se il limite viene superato, il server Apple restituisce un errore 429 Too Many Requests. Per campagne su larga scala, utilizzare più connessioni e distribuire il carico uniformemente tra i dispositivi.

Aggiornamento e invalidazione dei token

Device Token non è permanente e può cambiare in diversi scenari, richiedendo un meccanismo di aggiornamento sul server. Se il server continua a inviare notifiche push a un token obsoleto, APNS restituisce un errore 410 Gone, indicando che il token non è più valido per l’ambiente specificato.

Quando il token cambia

Apple documenta diversi scenari in cui il Device Token cambia: l’utente reinstalla l’app, ripristina il dispositivo da un backup iCloud, installa una nuova versione di iOS o reimposta le impostazioni di rete o privacy. In ogni caso, l’app riceverà un nuovo token da APNS al successivo avvio. Il server deve aggiornare il token nel database, rimuovendo quello vecchio e salvando quello nuovo.

Gestione dell’errore 410 Gone da APNS

Quando il server invia una notifica push a un token obsoleto, APNS restituisce HTTP 410 con l’intestazione apns-unless-timestamp. Questa intestazione indica l’ora dopo la quale il token è diventato non valido. Il server deve immediatamente eliminare o disattivare questo token nel database per evitare di inviargli nuovamente notifiche. Ignorare l’errore 410 spreca risorse e riduce il tasso di consegnabilità.

Pulizia periodica dei token inattivi

Per mantenere aggiornato il database dei token, si consiglia di eseguire una pulizia periodica. Lo script di pulizia analizza i log APNS degli ultimi N giorni, trova tutti i token che hanno ricevuto un errore 410 e li disattiva nel database. Inoltre, i token senza attività dell’utente per oltre 90 giorni possono essere rimossi — si tratta di record inutili che aumentano solo la dimensione del database.

Convalida dei token prima dell’invio massivo

Prima dell’invio massivo di notifiche push (newsletter, campagne promozionali), si consiglia di pre-convalidare i token. APNS non fornisce un’API diretta per la convalida batch dei token, quindi viene utilizzata la strategia di inviare un push di prova con bassa priorità e analizzare gli errori. I token che restituiscono un errore 410 vengono esclusi dall’invio principale.

Esempio di codice per ottenere Device Token

Esaminiamo il ciclo completo di ottenimento di un Device Token in Swift, inclusa la gestione degli errori e l’invio al server. Il codice copre la richiesta di autorizzazione, la registrazione presso APNS, la conversione di Data in stringa hex, la gestione degli errori e l’invio del token al proprio server con tentativi di ripetizione in caso di fallimento.

import UIKit
import UserNotifications

final class PushNotificationManager: NSObject {

    static let shared = PushNotificationManager()
    private let apiClient = APIClient()
    private var currentToken: String?

    func register() {
        UNUserNotificationCenter.current()
            .requestAuthorization(
                options: [.alert, .badge, .sound]) {
            [weak self] granted, error in
            guard granted else {
                Analytics.log(
                    "Push permission denied")
                return
            }
            DispatchQueue.main.async {
                UIApplication.shared
                    .registerForRemoteNotifications()
            }
        }
    }

    func handleDeviceToken(_ tokenData: Data) {
        let token = tokenData
            .map { String(format: "%02.2hhx", $0) }
            .joined()

        guard token != currentToken else { return }
        currentToken = token
        sendTokenToServer(token)
    }

    func handleRegistrationError(_ error: Error) {
        Analytics.log(
            "Push registration failed: \(error)")

        // Riprovare dopo un ritardo in caso di errori di rete
        if let urlError = error as? URLError,
            urlError.code == .notConnectedToInternet {
            DispatchQueue.main.asyncAfter(
                deadline: .now() + 10) { [weak self] in
                self?.register()
            }
        }
    }

    private func sendTokenToServer(_ token: String) {
        let body = PushTokenRequest(
            token: token,
            environment: Environment.current == .debug
                ? "sandbox" : "production",
            osVersion: UIDevice.current.systemVersion,
            locale: Locale.current.identifier
        )
        apiClient.sendToken(body) { [weak self] result in
            if case .success = result {
                self?.currentToken = token
            }
        }
    }
}

Gestione degli errori durante la registrazione

Gli errori durante la registrazione APNS possono essere causati da vari motivi. I più comuni includono indisponibilità della rete, configurazione errata del certificato in Xcode (ad esempio, capacità Push Notifications disabilitata), utilizzo del simulatore (che non supporta le push) o un profilo di provisioning errato. In produzione, è importante registrare gli errori e, se possibile, ripetere la registrazione al successivo avvio dell’app.

Test del Device Token sul simulatore

Il simulatore iOS non supporta la ricezione di un Device Token reale. Per testare la registrazione sul simulatore, utilizzare controlli dell’architettura i386: in una build di debug, è possibile simulare la ricezione del token o utilizzare test dell’interfaccia utente con oggetti mock. I test reali delle notifiche push vengono sempre eseguiti su un dispositivo fisico connesso a Xcode.