Registration Token em notificações push: o que é, formas de obter e atualizar

O que é um Registration Token

Registration Token é uma string única de até 4096 caracteres que o Firebase Cloud Messaging atribui a cada instância de aplicação. O token é formado com base no ID da aplicação, ID do dispositivo e na conta Google no dispositivo.

Estrutura e propósito do token

Um Registration Token consiste numa sequência aleatória de caracteres codificados em formato Base64. O FCM usa este token como endereço de entrega — o servidor envia uma notificação para o token, e o FCM a roteia para o dispositivo específico. Sem um token, é impossível direcionar uma notificação push para um utilizador específico.

Diferenças de outros identificadores

Um Registration Token não deve ser confundido com o Device ID (IMEI) ou Advertising ID. O Device ID é um identificador de hardware do dispositivo, enquanto o Advertising ID é usado para fins publicitários. O Registration Token está vinculado à combinação de aplicação e dispositivo, e um mesmo dispositivo pode ter vários tokens para diferentes aplicações.

Quando o token é considerado inválido

O FCM pode considerar um Registration Token inválido em várias situações. Se a aplicação for removida do dispositivo, o token é automaticamente revogado. Ao restaurar dados de uma cópia de segurança num novo dispositivo, o token antigo deixa de funcionar. O Firebase também retorna um estado UNREGISTERED ao tentar enviar uma notificação para um token desatualizado.

Como o FCM atribui um Registration Token

Firebase Cloud Messaging gera um Registration Token quando a aplicação é iniciada pela primeira vez e o método getToken() é chamado. O processo inclui a verificação das credenciais do Google Play Services e o registo da aplicação na infraestrutura do Firebase.

Processo de registo do dispositivo

Quando um dispositivo executa uma aplicação com o SDK do FCM integrado pela primeira vez, ocorre o seguinte. O SDK do Firebase verifica a presença de Google Play Services no dispositivo. Em seguida, o SDK envia um pedido aos servidores do Firebase, transmitindo o ID da aplicação e as informações do dispositivo. O servidor do Firebase cria um novo token e devolve-o à aplicação.

Mecânica interna do FCM

O FCM usa uma arquitetura baseada em conexões de longa duração. Após receber um Registration Token, o dispositivo estabelece uma conexão persistente com os servidores do Firebase através do protocolo STOMP no Android ou do canal APNs no iOS. Quando o servidor envia uma notificação para o token, o FCM encontra o dispositivo pelo token e entrega a carga útil.

Condições de regeneração do token

Um Registration Token pode ser regenerado pelo FCM nos seguintes casos. Ao restaurar uma aplicação a partir de uma cópia de segurança num novo dispositivo. Ao eliminar e reinstalar a aplicação. Ao limpar os dados da aplicação através das definições do sistema. Ao iniciar sessão com uma conta Google diferente no dispositivo. O Firebase recomenda sempre tratar o callback onNewToken para monitorizar as alterações.

Obter um Registration Token no Android

No Android, o Registration Token é obtido através do SDK do Firebase Messaging. O processo difere conforme a versão do SDK — as versões mais recentes usam a API FirebaseInstallations em vez do obsoleto FirebaseInstanceId.

Método moderno através do FirebaseInstallations

A partir da versão 21.0.0 do SDK do Firebase, o método getToken() é chamado através de FirebaseMessaging. Esta abordagem gere automaticamente o ciclo de vida do token e subscreve as suas atualizações.

class MyFirebaseMessagingService : FirebaseMessagingService() {

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

    private fun sendRegistrationToServer(token: String) {
        // Enviar token para o servidor
        Log.d("FCM", "New token: $token")
    }

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

Manuseamento do token na Activity ou ViewModel

Em alguns cenários, o token é necessário não no serviço mas diretamente numa Activity ou ViewModel. Para tal, o getToken() pode ser chamado num ponto conveniente do ciclo de vida da aplicação. É importante não chamar este método a partir da thread principal sem tratar a assincronia.

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

Método legado FirebaseInstanceId

Em versões anteriores do SDK do Firebase (anteriores à 20.x), o token era obtido através de FirebaseInstanceId.getInstance().getToken(). Este método está marcado como obsoleto e não é recomendado para uso em novos projetos. Os programadores que mantêm código legado devem migrar para a API FirebaseInstallations.

Obter um Registration Token no iOS

No iOS, o processo de obtenção do Registration Token difere arquitetonicamente — o FCM funciona através do Apple Push Notification service (APNs). O SDK do Firebase recebe um token de dispositivo único do APNs, converte-o para o formato FCM e entrega-o à aplicação.

Configuração do APNs e obtenção do token

Para usar o FCM no iOS, é necessário configurar um certificado ou chave APNs na consola do Firebase. A aplicação deve solicitar permissão para notificações através de UNUserNotificationCenter. Após receber o token APNs, o SDK do Firebase gera automaticamente o 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ças entre o token iOS e Android

O Registration Token no iOS tem um tamanho menor em comparação com o token Android, pois baseia-se no token de dispositivo APNs. O SDK do Firebase atualiza automaticamente o token FCM quando o token APNs muda, o que acontece ao restaurar um dispositivo a partir de uma cópia de segurança ou ao reinstalar a aplicação.

Atualização e gestão do Registration Token

Gerir o ciclo de vida do Registration Token é uma tarefa crítica para a entrega fiável de notificações push. Se o servidor armazenar um token desatualizado, as notificações não serão entregues e o Firebase retornará um erro UNREGISTERED.

Monitorização de alterações no token

O SDK do Firebase fornece dois mecanismos para monitorizar alterações no token. No Android, é usado o callback onNewToken no FirebaseMessagingService. No iOS, é usado o delegado messaging:didReceiveRegistrationToken. Ambos são chamados sempre que o token é atualizado.

// Guardar token no SharedPreferences e enviar para o servidor
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)
    }
}

Estratégia de armazenamento de tokens no servidor

O servidor deve armazenar o Registration Token associado ao identificador de utilizador. Quando o token é atualizado, o cliente envia o novo token ao servidor, e o servidor substitui o antigo. Recomenda-se manter um histórico de tokens: se uma notificação não for entregue ao novo token, pode tentar-se o antigo.

Tratamento de erros ao trabalhar com tokens

O Firebase pode retornar um erro ao obter o token em vários casos. Falta de Google Play Services no dispositivo — o token não será obtido. Exceder a cota de pedidos ao FCM — é necessário implementar um backoff exponencial nas tentativas. Expiração do token — o SDK solicita automaticamente um novo.