Registration Token w powiadomieniach push: co to jest, sposoby uzyskiwania i aktualizacji

Co to jest Registration Token

Registration Token to unikalny ciąg znaków o długości do 4096 znaków, który Firebase Cloud Messaging przypisuje każdej instancji aplikacji. Token jest tworzony na podstawie identyfikatora aplikacji, urządzenia i konta Google na urządzeniu.

Struktura i przeznaczenie tokena

Registration Token składa się z losowej sekwencji znaków zakodowanych w formacie Base64. FCM używa tego tokena jako adresu dostawy — część serwerowa wysyła powiadomienie na token, a FCM kieruje je na konkretne urządzenie. Bez tokena niemożliwe jest zaadresowanie powiadomienia push do konkretnego użytkownika.

Różnice w stosunku do innych identyfikatorów

Registration Token nie należy mylić z Device ID (IMEI) ani Advertising ID. Device ID to sprzętowy identyfikator urządzenia, a Advertising ID jest używany do celów reklamowych. Registration Token jest powiązany z kombinacją aplikacji i urządzenia, przy czym jedno urządzenie może mieć wiele tokenów dla różnych aplikacji.

Kiedy token jest uważany za nieważny

FCM może uznać Registration Token za nieważny w kilku sytuacjach. Jeśli aplikacja zostanie usunięta z urządzenia, token jest automatycznie unieważniany. Przy przywracaniu danych z kopii zapasowej na nowym urządzeniu stary token przestaje działać. Firebase zwraca status UNREGISTERED przy próbie wysłania powiadomienia na nieaktualny token.

Jak FCM przypisuje Registration Token

Firebase Cloud Messaging generuje Registration Token przy pierwszym uruchomieniu aplikacji, gdy wywoływana jest metoda getToken(). Proces obejmuje sprawdzenie danych uwierzytelniających Google Play Services i rejestrację aplikacji w infrastrukturze Firebase.

Proces rejestracji urządzenia

Kiedy urządzenie po raz pierwszy uruchamia aplikację ze zintegrowanym FCM SDK, dzieje się co następuje. Firebase SDK sprawdza obecność Google Play Services na urządzeniu. Następnie SDK wysyła żądanie do serwerów Firebase, przekazując identyfikator aplikacji i informacje o urządzeniu. Serwer Firebase tworzy nowy token i zwraca go aplikacji.

Wewnętrzna mechanika FCM

FCM wykorzystuje architekturę opartą na długotrwałych połączeniach. Po otrzymaniu Registration Token urządzenie ustanawia stałe połączenie z serwerami Firebase przez protokół STOMP na Androidzie lub kanał APNs na iOS. Gdy część serwerowa wysyła powiadomienie na token, FCM znajduje urządzenie po tokenie i przekazuje ładunek.

Warunki regeneracji tokena

Registration Token może zostać zregenerowany przez FCM w następujących przypadkach. Przy przywracaniu aplikacji z kopii zapasowej na nowym urządzeniu. Przy usunięciu i ponownej instalacji aplikacji. Przy czyszczeniu danych aplikacji przez ustawienia systemowe. Przy logowaniu się na inne konto Google na urządzeniu. Firebase zaleca zawsze obsługiwać callback onNewToken do śledzenia zmian.

Uzyskiwanie Registration Token na Androidzie

Na Androidzie Registration Token jest uzyskiwany przez Firebase Messaging SDK. Proces różni się dla różnych wersji SDK — w nowych wersjach używane jest FirebaseInstallations API zamiast przestarzałego FirebaseInstanceId.

Nowoczesny sposób przez FirebaseInstallations

Począwszy od Firebase SDK w wersji 21.0.0, metoda getToken() jest wywoływana przez FirebaseMessaging. To podejście automatycznie zarządza cyklem życia tokena i subskrybuje jego aktualizacje.

class MyFirebaseMessagingService : FirebaseMessagingService() {

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

    private fun sendRegistrationToServer(token: String) {
        // Wysłanie tokena do części serwerowej
        Log.d("FCM", "Nowy token: $token")
    }

    init {
        FirebaseMessaging.getInstance()
            .getToken()
            .addOnCompleteListener { task ->
                if (!task.isSuccessful) {
                    Log.w("FCM", "Pobranie tokena FCM nie powiodło się")
                    return@addOnCompleteListener
                }
                val token = task.result
                sendRegistrationToServer(token)
            }
    }
}

Obsługa tokena w Activity lub ViewModel

W niektórych scenariuszach token jest potrzebny nie w serwisie, ale bezpośrednio w Activity lub ViewModel. W tym celu można wywołać getToken() w dogodnym miejscu cyklu życia aplikacji. Ważne, aby nie wywoływać tej metody z głównego wątku bez obsługi asynchroniczności.

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

Przestarzała metoda FirebaseInstanceId

W starych wersjach Firebase SDK (przed wersją 20.x) token był uzyskiwany przez FirebaseInstanceId.getInstance().getToken(). Ta metoda jest oznaczona jako deprecated i nie jest zalecana do użytu w nowych projektach. Deweloperzy utrzymujący legacy-kod powinni migrować do FirebaseInstallations API.

Uzyskiwanie Registration Token na iOS

Na iOS proces uzyskiwania Registration Token różni się architektonicznie — FCM działa przez Apple Push Notification service (APNs). Firebase SDK otrzymuje od APNs unikalny device token, konwertuje go do formatu FCM i przekazuje aplikacji.

Konfiguracja APNs i uzyskiwanie tokena

Aby FCM działał na iOS, należy skonfigurować certyfikat APNs lub klucz w konsoli Firebase. Aplikacja musi poprosić o pozwolenie na powiadomienia przez UNUserNotificationCenter. Po otrzymaniu tokena APNs, Firebase SDK automatycznie generuje 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)
    }
}

Różnice między tokenem iOS a Android

Registration Token na iOS ma mniejszy rozmiar w porównaniu do tokena Androida, ponieważ opiera się na APNs device token. Firebase SDK automatycznie aktualizuje token FCM przy zmianie tokena APNs, co ma miejsce przy przywracaniu urządzenia z kopii zapasowej lub ponownej instalacji aplikacji.

Aktualizacja i zarządzanie Registration Token

Zarządzanie cyklem życia Registration Token to krytycznie ważne zadanie dla stabilnego dostarczania powiadomień push. Jeśli część serwerowa przechowuje nieaktualny token, powiadomienia nie zostaną dostarczone, a Firebase zwróci błąd UNREGISTERED.

Monitorowanie zmian tokena

Firebase SDK udostępnia dwa mechanizmy do śledzenia zmian tokena. Na Androidzie używany jest callback onNewToken w FirebaseMessagingService. Na iOS — delegat messaging:didReceiveRegistrationToken. Oba są wywoływane przy każdej aktualizacji tokena.

// Zapisanie tokena w SharedPreferences i wysłanie na serwer
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 przechowywania tokenów na serwerze

Część serwerowa powinna przechowywać Registration Token w powiązaniu z identyfikatorem użytkownika. Przy aktualizacji tokena klient wysyła na serwer nowy token, a serwer zastępuje stary. Zaleca się przechowywanie historii tokenów: jeśli powiadomienie nie zostało dostarczone na nowy token, można spróbować użyć starego.

Obsługa błędów przy pracy z tokenem

Firebase może zwrócić błąd uzyskania tokena w kilku przypadkach. Brak Google Play Services na urządzeniu — token nie zostanie uzyskany. Przekroczenie limitu zapytań do FCM — należy wdrożyć wykładnicze opóźnienie przy ponownych próbach. Wygaśnięcie tokena — SDK automatycznie żąda nowego.