Registration Token nelle notifiche push: cos'è, metodi di ottenimento e aggiornamento

Cos'è un Registration Token

Registration Token è una stringa univoca lunga fino a 4096 caratteri che Firebase Cloud Messaging assegna a ogni istanza dell'applicazione. Il token è formato in base all'ID dell'applicazione, all'ID del dispositivo e all'account Google sul dispositivo.

Struttura e scopo del token

Un Registration Token consiste in una sequenza casuale di caratteri codificati in formato Base64. FCM utilizza questo token come indirizzo di consegna — il server invia una notifica al token e FCM la instrada al dispositivo specifico. Senza un token, è impossibile indirizzare una notifica push a un utente specifico.

Differenze dagli altri identificatori

Un Registration Token non va confuso con il Device ID (IMEI) o l'Advertising ID. Il Device ID è un identificatore hardware del dispositivo, mentre l'Advertising ID viene utilizzato per scopi pubblicitari. Il Registration Token è legato alla combinazione di applicazione e dispositivo, e un singolo dispositivo può avere più token per diverse applicazioni.

Quando il token è considerato non valido

FCM può considerare un Registration Token non valido in diverse situazioni. Se l'applicazione viene rimossa dal dispositivo, il token viene automaticamente revocato. Quando si ripristinano i dati da un backup su un nuovo dispositivo, il vecchio token smette di funzionare. Firebase restituisce anche uno stato UNREGISTERED quando si tenta di inviare una notifica a un token obsoleto.

Come FCM assegna un Registration Token

Firebase Cloud Messaging genera un Registration Token quando l'applicazione viene avviata per la prima volta e viene chiamato il metodo getToken(). Il processo include la verifica delle credenziali di Google Play Services e la registrazione dell'applicazione nell'infrastruttura Firebase.

Processo di registrazione del dispositivo

Quando un dispositivo esegue per la prima volta un'applicazione con FCM SDK integrato, accade quanto segue. Firebase SDK verifica la presenza di Google Play Services sul dispositivo. Quindi, SDK invia una richiesta ai server Firebase, trasmettendo l'ID dell'applicazione e le informazioni del dispositivo. Il server Firebase crea un nuovo token e lo restituisce all'applicazione.

Meccanica interna di FCM

FCM utilizza un'architettura basata su connessioni a lunga durata. Dopo aver ricevuto un Registration Token, il dispositivo stabilisce una connessione persistente con i server Firebase tramite il protocollo STOMP su Android o il canale APNs su iOS. Quando il server invia una notifica al token, FCM trova il dispositivo tramite il token e consegna il payload.

Condizioni di rigenerazione del token

Un Registration Token può essere rigenerato da FCM nei seguenti casi. Quando si ripristina un'applicazione da un backup su un nuovo dispositivo. Quando si elimina e re-installa l'applicazione. Quando si cancellano i dati dell'applicazione tramite le impostazioni di sistema. Quando si accede con un account Google diverso sul dispositivo. Firebase raccomanda di gestire sempre il callback onNewToken per tracciare le modifiche.

Ottenere un Registration Token su Android

Su Android, il Registration Token si ottiene tramite Firebase Messaging SDK. Il processo differisce a seconda della versione dell'SDK — le versioni più recenti utilizzano l'API FirebaseInstallations invece del deprecato FirebaseInstanceId.

Metodo moderno tramite FirebaseInstallations

A partire dalla versione 21.0.0 di Firebase SDK, il metodo getToken() viene chiamato tramite FirebaseMessaging. Questo approccio gestisce automaticamente il ciclo di vita del token e si iscrive ai suoi aggiornamenti.

class MyFirebaseMessagingService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        sendRegistrationToServer(token)
    }

    private fun sendRegistrationToServer(token: String) {
        // Invio del token al server
        Log.d("FCM", "New token: $token")
    }

    init {
        FirebaseMessaging.getInstance()
            .getToken()
            .addOnCompleteListener { task ->
                if (!task.isSuccessful) {
                    Log.w("FCM", "Recupero del token FCM fallito")
                    return@addOnCompleteListener
                }
                val token = task.result
                sendRegistrationToServer(token)
            }
    }
}

Gestione del token in Activity o ViewModel

In alcuni scenari, il token è necessario non nel servizio ma direttamente in un'Activity o ViewModel. Per questo, getToken() può essere chiamato in un punto conveniente del ciclo di vita dell'applicazione. È importante non chiamare questo metodo dal thread principale senza gestire l'asincronia.

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        getFCMToken()
    }

    private fun getFCMToken() {
        FirebaseMessaging.getInstance().getToken()
            .addOnCompleteListener { task ->
                if (task.isSuccessful) {
                    val token = task.result
                    Log.d("FCM", "Token: $token")
                }
            }
    }
}

Metodo legacy FirebaseInstanceId

Nelle versioni precedenti di Firebase SDK (prima della 20.x), il token veniva ottenuto tramite FirebaseInstanceId.getInstance().getToken(). Questo metodo è contrassegnato come deprecato e non è raccomandato per l'uso in nuovi progetti. Gli sviluppatori che mantengono codice legacy dovrebbero migrare all'API FirebaseInstallations.

Ottenere un Registration Token su iOS

Su iOS, il processo di ottenimento del Registration Token differisce architetturalmente — FCM funziona tramite Apple Push Notification service (APNs). Firebase SDK riceve un token dispositivo univoco da APNs, lo converte in formato FCM e lo passa all'applicazione.

Configurazione APNs e ottenimento del token

Per utilizzare FCM su iOS, è necessario configurare un certificato o una chiave APNs nella console Firebase. L'applicazione deve richiedere il permesso per le notifiche tramite UNUserNotificationCenter. Dopo aver ricevuto il token APNs, Firebase SDK genera automaticamente il Registration Token.

import FirebaseMessaging
import UserNotifications

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        application: UIApplication,
        didFinishLaunchingWithOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        FirebaseApp.configure()
        Messaging.messaging().delegate = self
        requestNotificationAuthorization()
        return true
    }

    private func requestNotificationAuthorization() {
        let center = UNUserNotificationCenter.current()
        center.requestAuthorization(options: [.alert, .sound, .badge])
    }
}

extension AppDelegate: MessagingDelegate {
    func messaging(
        messaging: Messaging,
        didReceiveRegistrationToken fcmToken: String?
    ) {
        Log.d("FCM", "Token: \(fcmToken ?? "")")
        sendTokenToServer(token: fcmToken)
    }
}

Differenze tra token iOS e Android

Il Registration Token su iOS ha dimensioni inferiori rispetto al token Android, poiché si basa sul token dispositivo APNs. Firebase SDK aggiorna automaticamente il token FCM quando cambia il token APNs, cosa che accade quando si ripristina un dispositivo da un backup o si re-installa l'applicazione.

Aggiornamento e gestione del Registration Token

La gestione del ciclo di vita del Registration Token è un compito critico per la consegna affidabile delle notifiche push. Se il server memorizza un token obsoleto, le notifiche non verranno consegnate e Firebase restituirà un errore UNREGISTERED.

Monitoraggio delle modifiche del token

Firebase SDK fornisce due meccanismi per tracciare le modifiche del token. Su Android, viene utilizzato il callback onNewToken in FirebaseMessagingService. Su iOS, viene utilizzato il delegato messaging:didReceiveRegistrationToken. Entrambi vengono chiamati ogni volta che il token viene aggiornato.

// Salvataggio del token in SharedPreferences e invio al server
class TokenManager(private val context: Context) {

    companion object {
        private const val PREFS_TOKEN_KEY = "fcm_registration_token"
    }

    fun saveToken(token: String) {
        val prefs = PreferenceManager
            .getDefaultSharedPreferences(context)
        prefs.edit().putString(PREFS_TOKEN_KEY, token).apply()
    }

    fun getSavedToken(): String? {
        val prefs = PreferenceManager
            .getDefaultSharedPreferences(context)
        return prefs.getString(PREFS_TOKEN_KEY, null)
    }
}

Strategia di memorizzazione dei token sul server

Il server deve memorizzare il Registration Token in associazione con l'identificatore utente. Quando il token viene aggiornato, il client invia il nuovo token al server e il server sostituisce il vecchio. Si consiglia di mantenere una cronologia dei token: se una notifica non viene consegnata al nuovo token, si può provare con il vecchio.

Gestione degli errori durante il lavoro con i token

Firebase può restituire un errore di ottenimento del token in diversi casi. Assenza di Google Play Services sul dispositivo — il token non verrà ottenuto. Superamento della quota di richieste a FCM — è necessario implementare un backoff esponenziale nei tentativi. Scadenza del token — SDK richiede automaticamente un nuovo token.