Firebase Cloud Messaging

Guia completo de uso e requisitos do FCM

O Firebase Cloud Messaging (FCM) é a solução multiplataforma do Google para enviar mensagens e notificações de forma confiável para apps Android, iOS, Web, Flutter e Unity. O funcionamento básico envolve um servidor confiável (como o Firebase Admin SDK ou a API HTTP v1) que envia solicitações ao backend do FCM, e este encaminha as mensagens para os dispositivos através das camadas de transporte específicas de cada plataforma (ATL no Android, APNs na Apple e Web Push na Web).

ATL · Android APNs · Apple Web Push · Web

5 Plataformas suportadas

3 Camadas de transporte

4 Credenciais essenciais

4096 Bytes (payload APNs)

Fluxo Geral

🚀 Como usar o FCM

📌

Abaixo estão os passos gerais de uso e todos os requisitos que você precisa atender, de acordo com a documentação oficial do site da Firebase.

Configure um Projeto no Firebase

Crie um projeto no Console do Firebase e registre seu app (Android, iOS, Web, etc.) para obter o arquivo de configuração (google-services.json ou GoogleService-Info.plist).

Adicione o SDK do FCM ao seu App

Android Adicione o SDK do Firebase e edite o AndroidManifest.xml para incluir um serviço que estenda FirebaseMessagingService (necessário para lidar com mensagens em primeiro plano e payloads de dados).

iOS Adicione o SDK e ative Push Notifications e Background Modes (Background fetch e Remote notifications) no Xcode.

Web Adicione o SDK JavaScript do Firebase e inicialize o FCM. É necessário servir a página via HTTPS (obrigatório para Service Workers).

Flutter / Unity Siga os guias específicos de configuração da plataforma, que incluem a inicialização do FlutterFire ou do SDK Unity e a configuração das permissões necessárias.

Obtenha o Token de Registro

Cada instância do app precisa se registrar no FCM para receber um token de registro único, que identifica o dispositivo. No Android/iOS, isso é feito automaticamente pelo SDK; na Web, é necessário chamar getToken() com as chaves VAPID.

O app deve ser aberto pelo menos uma vez para que o registro ocorra. No Android, se o usuário forçar a parada do app, ele precisa ser reaberto manualmente para que as mensagens voltem a funcionar.

Envie Mensagens

Console do Firebase (Notifications Composer) Interface gráfica para criar e enviar notificações de teste ou campanhas.

Servidor Confiável Use o Firebase Admin SDK (Node.js, Java, Python, C#) ou a API HTTP v1 para enviar mensagens programaticamente. O servidor deve ser capaz de enviar requisições formatadas, lidar com retentativas usando recuo exponencial e armazenar credenciais com segurança.

Solicite Permissão ao Usuário

iOS, macOS, Web e Android 13 (ou superior): antes de receber payloads do FCM, é obrigatório solicitar a permissão do usuário. Use a API requestPermission() (Flutter) ou os métodos nativos de cada plataforma.

Compatibilidade

📋 Requisitos por Plataforma

Segundo o site da Firebase.

🤖

Android Google Play Services

Versão mínima: Android 7.0 (API nível 24) ou superior e o app Google Play Store instalado (ou emulador com Google APIs).
Google Analytics: é fortemente recomendado e necessário para relatórios de entrega de mensagens.
Permissão de notificação (Android 13+): o SDK do FCM (versão 23.0.6+) já inclui a permissão POST_NOTIFICATIONS, mas você deve solicitá-la em tempo de execução.

💡 Nota: algumas páginas (como a do Flutter) mencionam Android 4.4+, mas a página oficial de introdução ao Android especifica Android 7.0+.

🍎

iOS / Apple APNs

Versão mínima: para apps Unity, é necessário iOS 15+ ou tvOS 15+. Para apps nativos iOS, a documentação não fixa uma versão mínima explícita, mas exige o uso do APNs e a configuração de push notifications.
Chave de autenticação APNs: você deve criar uma chave de autenticação APNs no Apple Developer Member Center e fazer o upload dela no Console do Firebase (aba Cloud Messaging). Pelo menos uma chave (desenvolvimento ou produção) é obrigatória.
Method Swizzling: o SDK do FCM realiza method swizzling para mapear o token APNs e capturar dados de análise. Se você desabilitar o swizzling, algumas funcionalidades podem não operar corretamente.
Tamanho do payload: é possível receber notificações e payloads de dados de até 4096 bytes pela interface APNs do FCM.

🌐

Web Push API

HTTPS: o SDK do FCM só é suportado em páginas servidas via HTTPS (devido ao uso de Service Workers).
Navegadores com Push API: o app deve rodar em navegadores que suportem a Push API (incluindo as versões listadas na matriz de suporte).
Chaves VAPID: é necessário gerar (ou importar) um par de chaves VAPID no Console do Firebase (aba Cloud Messaging → Web Push certificates) para autorizar o envio de mensagens push.

🎯

Flutter FlutterFire

Pré-requisitos gerais: no iOS, é preciso habilitar Push Notifications e Background Modes no Xcode e fazer o upload da chave APNs. No Android, os dispositivos devem rodar Android 4.4 ou superior com o Google Play Services instalado.
Permissão: em iOS, macOS, Web e Android 13+, é obrigatório solicitar permissão ao usuário antes de receber mensagens.

🎮

Unity Unity 2021 LTS+

Versão do Unity: Unity 2021 LTS ou superior.
iOS/tvOS: requer Xcode 26.2+, CocoaPods 1.12.0+, e o app deve ter como alvo iOS 15+ ou tvOS 15+. É necessário um dispositivo físico para testes e a chave de autenticação APNs.
Android: o app deve ter como alvo API nível 24 (Nougat) ou superior. Emuladores devem usar imagens com Google Play.

Backend

🖥️ Requisitos do Ambiente de Servidor

Se você for enviar mensagens programaticamente (e não apenas pelo console), seu servidor (ou ambiente confiável, como Cloud Functions) deve atender aos seguintes critérios:

📨

Enviar requisições formatadas corretamente para o backend do FCM.

🔁

Gerenciar requisições e reenvios utilizando recuo exponencial (exponential backoff) em caso de falhas.

🔒

Armazenar com segurança as credenciais de autorização do servidor e os tokens de registro dos clientes.

Configuração

🔑 Credenciais Necessárias do Projeto Firebase

Dependendo da funcionalidade, você precisará de uma ou mais destas credenciais:

01 ID do Projeto

Identificador único do projeto Firebase, usado nas requisições ao endpoint HTTP v1.

02 Token de Registro

String única que identifica cada instância do app cliente. Necessário para mensagens direcionadas a dispositivos e grupos.

⚠ Deve ser mantido em segredo.

03 ID do Remetente

Valor numérico único criado com o projeto, que identifica quem pode enviar mensagens para o app cliente.

04 Token de Acesso

Token OAuth 2.0 de curta duração, usado para autorizar requisições à API HTTP v1. Está associado à conta de serviço do projeto.

Atenção

⚠️ Observações Finais

♻

Ciclo de vida do app

No Android, se o usuário forçar a parada do app pelas configurações do dispositivo, ele precisará ser reaberto manualmente para que as mensagens voltem a ser recebidas. No iOS, se o usuário deslizar o app para fora do seletor de apps, ele também precisa ser reaberto manualmente para que as mensagens em segundo plano funcionem.

🔔

Mensagens em primeiro plano vs. segundo plano

O tratamento de mensagens varia conforme o estado do app (aberto, em segundo plano ou finalizado). Para mensagens em primeiro plano, é necessário ouvir o stream onMessage (Flutter) ou implementar o serviço apropriado (Android).

📚

Esses são os requisitos e o fluxo de uso conforme a documentação oficial do Firebase. Para detalhes específicos de implementação, vale a pena consultar os guias passo a passo de cada plataforma no site da Firebase.