Firebase Cloud Messaging: o que é, princípio de funcionamento e notificações push

O que é Firebase Cloud Messaging

Firebase Cloud Messaging é um serviço de nuvem do Google que garante a entrega de notificações push e mensagens de dados entre o servidor do aplicativo e os dispositivos cliente. O serviço substituiu o antigo Google Cloud Messaging (GCM) e se tornou a solução padrão para entrega de push no ecossistema Firebase. O FCM suporta Android, iOS, Web e Unity, fornecendo uma interface de envio unificada independentemente da plataforma de destino.

Recursos principais do FCM

O serviço oferece vários mecanismos de entrega de mensagens, cada um resolvendo uma tarefa específica. As mensagens notification são exibidas automaticamente pelo sistema ao serem recebidas — o desenvolvedor não precisa escrever código para mostrar a notificação. As mensagens data transmitem payload arbitrário na forma de pares chave-valor e são processadas dentro do aplicativo. As mensagens combinadas contêm partes visíveis e ocultas para máxima flexibilidade.

Vantagens sobre uma solução própria

Implementar um servidor push próprio requer manter uma conexão TCP constante com cada dispositivo, o que é ineficiente e inseguro. O FCM utiliza a infraestrutura unificada do Google que mantém conexões com bilhões de dispositivos simultaneamente. O serviço gerencia automaticamente as tentativas de reenvio, filas de mensagens e balanceamento de carga, liberando o desenvolvedor de resolver essas tarefas por conta própria.

Como funciona o Firebase Cloud Messaging

A arquitetura do FCM consiste em três componentes principais: o servidor do provedor (seu backend), o servidor Firebase Cloud Messaging e o aplicativo cliente no dispositivo. Quando o servidor envia uma mensagem, ela primeiro chega à infraestrutura do FCM, que a roteia para o dispositivo de destino. Se o dispositivo estiver offline, o FCM armazena a mensagem em uma fila e a entrega quando a conexão for restabelecida.

Registro do dispositivo e obtenção do token

Na primeira inicialização, o aplicativo chama o Firebase SDK, que registra o dispositivo no serviço FCM e recebe um Registration Token único. Este token é uma string de cerca de 150 caracteres que identifica uma instância específica do aplicativo em um dispositivo específico. O token pode mudar ao reinstalar o aplicativo, limpar dados ou restaurar de um backup — o desenvolvedor deve lidar com a atualização do token através do delegado onNewToken.

Ciclo de vida da mensagem

Quando o servidor envia uma requisição através da API FCM, a mensagem passa por várias etapas. Recepção e validação — o FCM verifica a correção da requisição e a existência do dispositivo de destino. Fila — se o dispositivo estiver indisponível, a mensagem entra em uma fila de armazenamento. Roteamento — o FCM determina o canal de entrega ideal (WiFi ou dados móveis). Entrega — o sistema transmite a mensagem ao aplicativo de destino. Após a entrega bem-sucedida, o FCM retorna um identificador de mensagem ao servidor.

Tipos de mensagens no FCM

Firebase Cloud Messaging suporta três tipos de mensagens, cada um com suas particularidades de processamento no lado do cliente. As mensagens notification são gerenciadas pelo serviço de sistema Google Play Services no Android e APNs no iOS, e são exibidas automaticamente como banners push. As mensagens data são entregues diretamente ao aplicativo e processadas através do callback onMessageReceived no Android e application(_:didReceiveRemoteNotification:) no iOS.

Mensagens notification

Uma mensagem notification contém campos predefinidos: title, body, URL da imagem e som da notificação. O sistema cria e exibe automaticamente a notificação na bandeja do sistema, mesmo se o aplicativo estiver em segundo plano ou encerrado. O usuário vê um banner padrão com título e texto e, ao tocar, o aplicativo abre com os dados enviados no payload. Se o aplicativo estiver ativo, a mensagem notification pode ser interceptada e processada em código.

Mensagens data

Uma mensagem data é um conjunto personalizado de pares chave-valor sem campos predefinidos. O payload não é processado pelo sistema automaticamente — o aplicativo recebe os dados brutos e pode interpretá-los de forma arbitrária. As mensagens data são usadas para sincronização em segundo plano, atualização de cache local, acionamento de sincronização ou envio de comandos sem exibir uma notificação. No Android, a mensagem data é sempre entregue, mesmo se o aplicativo estiver encerrado ou em segundo plano.

Mensagens combinadas

O FCM permite enviar uma mensagem que contém tanto uma parte notification (para exibição) quanto uma parte data (para processamento). O payload combinado inclui tanto os campos predefinidos de notification quanto as chaves arbitrárias de data. O sistema exibe a notificação da parte notification, enquanto a parte data é transmitida nos extras da intent do aplicativo ao abrir. Isso é útil para cenários onde é necessário mostrar uma notificação ao usuário e ao mesmo tempo passar contexto para navegar para uma tela específica.

Configuração do FCM no Android

A integração do FCM no Android começa conectando o Firebase SDK através do arquivo build.gradle no nível do aplicativo. Após adicionar as dependências e o arquivo google-services.json, o aplicativo recebe automaticamente um Registration Token, que é transmitido através do callback FirebaseMessagingService. Para receber notificações, é necessário criar um serviço que estenda FirebaseMessagingService e registrá-lo no AndroidManifest.xml.

Inicialização e obtenção do token

Após conectar o Firebase SDK, o token do dispositivo é gerado automaticamente sem código adicional. O token está disponível através de FirebaseMessaging.getInstance().token, que retorna um Task<String>. Para rastrear atualizações do token, sobrescreva o método onNewToken no serviço. O token deve ser enviado ao servidor do provedor para que o servidor possa enviar notificações push para este dispositivo.

class MyFirebaseMessagingService :
    FirebaseMessagingService() {

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

    override fun onMessageReceived(
        message: RemoteMessage
    ) {
        val data = message.data
        val title = "Nova mensagem"
        val body = data["body"] ?: ""
        showNotification(title, body)
    }
}

Registro do serviço no manifesto

O serviço para receber mensagens FCM deve ser registrado no AndroidManifest.xml com os intent-filter apropriados. Adicione a tag service com a permissão INTERNET e a ação especificada. Sem o registro do serviço, as mensagens não serão entregues ao aplicativo em segundo plano. Para exibir notificações no Android 13+, é necessária a permissão de tempo de execução POST_NOTIFICATIONS.

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name=
    "android.permission.POST_NOTIFICATIONS" />

<service
    android:name=".MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name=
            "com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Configuração do FCM no iOS

A integração do FCM no iOS requer configuração tanto no Apple Push Notification Service (APNs) quanto no Firebase Console. Ao contrário do Android, onde o FCM gerencia a conexão diretamente, no iOS o FCM utiliza o APNs como camada de transporte. O aplicativo se registra para receber notificações push através de UIApplication.shared.registerForRemoteNotifications, e o Firebase SDK intercepta o token de dispositivo recebido e o vincula ao Registration Token do FCM.

Configuração do APNs e registro de notificações

Para o FCM funcionar no iOS, é necessário carregar uma chave ou certificado APNs no Firebase Console. A chave APNs é um método de autenticação moderno sem certificados (recomendado pela Apple). A chave é criada no Apple Developer Portal na seção Keys e carregada nas configurações de Cloud Messaging no Firebase Console. Após configurar o APNs, o aplicativo solicita permissão para notificações através do UNUserNotificationCenter e se registra via APNs.

import Firebase
import UserNotifications

class AppDelegate: NSObject, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions
        launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        FirebaseApp.configure()
        UNUserNotificationCenter.current()
            .requestAuthorization(options: [.alert, .sound, .badge])
        application.registerForRemoteNotifications()
        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken
        deviceToken: Data
    ) {
        Messaging.messaging()
            .apnsToken = deviceToken
    }
}

Gerenciamento de notificações recebidas

Para gerenciar notificações recebidas, implemente o delegado UNUserNotificationCenter. O método willPresent é chamado quando uma notificação é recebida com o aplicativo ativo — aqui você pode mostrar uma notificação personalizada in-app ou ignorar o banner do sistema. O método didReceive é chamado quando o usuário toca na notificação — aqui você navega para a tela correspondente. Para mensagens data, é usado o delegado MessagingDelegate, que recebe o payload ao receber uma mensagem FCM em segundo plano.

Envio de mensagens pelo servidor

O envio pelo servidor de mensagens FCM é realizado através da API HTTP v1 do Firebase Cloud Messaging ou da API legada. A API HTTP v1 é o método recomendado, utiliza autenticação OAuth 2.0 através de Service Account e suporta todos os recursos modernos do FCM, incluindo análise de entrega e testes A/B de notificações. A requisição é enviada pelo método POST para o endpoint https://fcm.googleapis.com/v1/projects/{project_id}/messages:send.

Formato de requisição HTTP v1

O corpo da requisição contém um objeto JSON com as informações da mensagem: target (token, tópico ou condição), notification (para exibição) e data (payload personalizado). A autenticação é feita através de uma chave JSON de Service Account carregada nas variáveis de ambiente do servidor. O token de acesso é gerado usando a biblioteca google-auth-library. O Google recomenda usar o Firebase Admin SDK para gerenciamento automático de autenticação e tentativas de reenvio.

const admin = require("firebase-admin")

const serviceAccount = require("./serviceAccountKey.json")

admin.initializeApp({ credential: admin.credential.cert(serviceAccount) })

const message = {
    token: "device_registration_token",
    notification: { title: "20% de desconto", body: "Em todos os serviços hoje" },
    data: { screen: "promo", promoId: "324" },
    android: { priority: "high" },
    apns: { payload: { aps: { sound: "default" } } }
}

admin.messaging().send(message)
    .then(response => {
        console.log("Enviado com sucesso:", response)
    })
    .catch(error => {
        console.log("Erro de envio:", error)
    })

Tópicos e envio em massa

Para enviar notificações a um grupo de usuários, o FCM suporta assinaturas de tópicos. Um tópico (topic) é um canal nomeado ao qual o aplicativo cliente se inscreve através de FirebaseMessaging.getInstance().subscribeToTopic(). O servidor pode enviar uma mensagem para um tópico e ela será entregue a todos os dispositivos inscritos. Os tópicos são adequados para newsletters, notificações promocionais e push baseados em eventos. Para segmentação mais precisa, são usadas condições baseadas em múltiplos tópicos com operadores lógicos.