Registration Token în notificările push: ce este, metode de obținere și actualizare

Ce este Registration Token

Registration Token — un șir unic de până la 4096 de caractere pe care Firebase Cloud Messaging îl atribuie fiecărei instanțe de aplicație. Tokenul este format pe baza identificatorului aplicației, al dispozitivului și al contului Google de pe dispozitiv.

Structura și scopul tokenului

Registration Token constă dintr-o secvență aleatoare de caractere codificate în format Base64. FCM folosește acest token ca adresă de livrare — partea server trimite notificarea către token, iar FCM o direcționează către dispozitivul specific. Fără token, nu se poate adresa o notificare push unui anumit utilizator.

Diferențe față de alte identificatoare

Registration Token nu trebuie confundat cu Device ID (IMEI) sau Advertising ID. Device ID este un identificator hardware al dispozitivului, iar Advertising ID este folosit în scopuri publicitare. Registration Token este legat de combinația aplicație-dispozitiv, iar un dispozitiv poate avea mai multe tokenuri pentru diferite aplicații.

Când tokenul este considerat invalid

FCM poate considera Registration Token invalid în mai multe situații. Dacă aplicația este ștearsă de pe dispozitiv, tokenul este anulat automat. La restaurarea datelor din backup pe un dispozitiv nou, tokenul vechi încetează să funcționeze. Firebase returnează statusul UNREGISTERED la încercarea de a trimite o notificare pe un token învechit.

Cum atribuie FCM Registration Token

Firebase Cloud Messaging generează Registration Token la prima pornire a aplicației, când este apelată metoda getToken(). Procesul include verificarea datelor de autentificare Google Play Services și înregistrarea aplicației în infrastructura Firebase.

Procesul de înregistrare a dispozitivului

Când dispozitivul rulează pentru prima dată aplicația cu FCM SDK integrat, se întâmplă următoarele. Firebase SDK verifică prezența Google Play Services pe dispozitiv. Apoi SDK trimite o cerere către serverele Firebase, transmițând identificatorul aplicației și informații despre dispozitiv. Serverul Firebase creează un token nou și îl returnează aplicației.

Mecanica internă FCM

FCM folosește o arhitectură bazată pe conexiuni de lungă durată. După primirea Registration Token, dispozitivul stabilește o conexiune permanentă cu serverele Firebase prin protocolul STOMP pe Android sau canalul APNs pe iOS. Când partea server trimite o notificare către token, FCM găsește dispozitivul după token și transmite încărcătura utilă.

Condiții de regenerare a tokenului

Registration Token poate fi regenerat de FCM în următoarele cazuri. La restaurarea aplicației din backup pe un dispozitiv nou. La ștergerea și reinstalarea aplicației. La curățarea datelor aplicației prin setările sistemului. La autentificarea cu un alt cont Google pe dispozitiv. Firebase recomandă să gestionați întotdeauna callback-ul onNewToken pentru a urmări modificările.

Obținerea Registration Token pe Android

Pe Android, Registration Token se obține prin Firebase Messaging SDK. Procesul diferă pentru diferite versiuni SDK — în versiunile noi se folosește FirebaseInstallations API în locul învechitului FirebaseInstanceId.

Metoda modernă prin FirebaseInstallations

Începând cu Firebase SDK versiunea 21.0.0, metoda getToken() este apelată prin FirebaseMessaging. Această abordare gestionează automat ciclul de viață al tokenului și se abonează la actualizările acestuia.

class MyFirebaseMessagingService : FirebaseMessagingService() {

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

    private fun sendRegistrationToServer(token: String) {
        // Trimiterea tokenului către partea server
        Log.d("FCM", "New token: $token")
    }

    init {
        FirebaseMessaging.getInstance()
            .getToken()
            .addOnCompleteListener { task ->
                if (!task.isSuccessful) {
                    Log.w("FCM", "Obținerea tokenului FCM a eșuat")
                    return@addOnCompleteListener
                }
                val token = task.result
                sendRegistrationToServer(token)
            }
    }
}

Gestionarea tokenului în Activity sau ViewModel

În unele scenarii, tokenul este necesar nu în serviciu, ci direct în Activity sau ViewModel. În acest scop, getToken() poate fi apelat în locul potrivit al ciclului de viață al aplicației. Este important să nu apelați această metodă din thread-ul principal fără gestionarea asincronității.

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")
                }
            }
    }
}

Metoda învechită FirebaseInstanceId

În versiunile vechi ale Firebase SDK (înainte de versiunea 20.x), tokenul se obținea prin FirebaseInstanceId.getInstance().getToken(). Această metodă este marcată ca deprecated și nu este recomandată în proiectele noi. Dezvoltatorii care întrețin cod legacy ar trebui să migreze la FirebaseInstallations API.

Obținerea Registration Token pe iOS

Pe iOS, procesul de obținere a Registration Token diferă arhitectural — FCM funcționează prin Apple Push Notification service (APNs). Firebase SDK primește de la APNs un device token unic, îl convertește în format FCM și îl transmite aplicației.

Configurarea APNs și obținerea tokenului

Pentru ca FCM să funcționeze pe iOS, trebuie configurat un certificat APNs sau o cheie în consola Firebase. Aplicația trebuie să solicite permisiunea pentru notificări prin UNUserNotificationCenter. După primirea tokenului APNs, Firebase SDK generează automat 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)
    }
}

Diferențele dintre tokenul iOS și Android

Registration Token pe iOS are o dimensiune mai mică în comparație cu tokenul Android, deoarece se bazează pe APNs device token. Firebase SDK actualizează automat tokenul FCM la modificarea tokenului APNs, ceea ce se întâmplă la restaurarea dispozitivului din backup sau la reinstalarea aplicației.

Actualizarea și gestionarea Registration Token

Gestionarea ciclului de viață Registration Token este o sarcină critică pentru livrarea stabilă a notificărilor push. Dacă partea server stochează un token învechit, notificările nu vor fi livrate, iar Firebase va returna eroarea UNREGISTERED.

Monitorizarea modificărilor tokenului

Firebase SDK oferă două mecanisme pentru urmărirea modificărilor tokenului. Pe Android se folosește callback-ul onNewToken în FirebaseMessagingService. Pe iOS — delegatul messaging:didReceiveRegistrationToken. Ambele sunt apelate la fiecare actualizare a tokenului.

// Salvarea tokenului în SharedPreferences și trimiterea către 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 de stocare a tokenurilor pe server

Partea server trebuie să stocheze Registration Token în asociere cu identificatorul utilizatorului. La actualizarea tokenului, clientul trimite noul token către server, iar serverul îl înlocuiește pe cel vechi. Se recomandă păstrarea istoricului tokenurilor: dacă o notificare nu a fost livrată pe tokenul nou, se poate încerca cel vechi.

Gestionarea erorilor la lucrul cu tokenul

Firebase poate returna o eroare de obținere a tokenului în mai multe cazuri. Absența Google Play Services pe dispozitiv — tokenul nu va fi obținut. Depășirea cotei de cereri către FCM — trebuie implementată o amânare exponențială la reîncercări. Expirarea tokenului — SDK solicită automat unul nou.