Enviar e receber notificações sobre um app do Flutter usando o Firebase Cloud Messaging

1. Introdução

Última atualização: 04/04/2022

Este codelab mostra o processo de desenvolvimento de um app multiplataforma com o Firebase Cloud Messaging (FCM) usando o Flutter. Você vai escrever uma parte da implementação do app e, em seguida, criar e executar com perfeição em três plataformas: Android, iOS e Web. Você também vai aprender a integrar o FCM ao Flutter e escrever código para receber e enviar mensagens. Por fim, o codelab apresenta o recurso de bloqueios específicos da plataforma da API FCM HTTP v1, que permite enviar uma mensagem que tem comportamentos diferentes em diferentes plataformas.

Pré-requisito

Noções básicas do Flutter.

O que você aprenderá

• Como configurar e criar um app do Flutter.
• Como adicionar dependências do FCM.
• Como enviar mensagens únicas do FCM para seu app.
• Como enviar mensagens do FCM de tópicos para seu app.

O que é necessário

• Versão estável mais recente do Android Studio, configurada com os plug-ins Dart e Flutter.

É possível executar o codelab usando qualquer um dos seguintes dispositivos:

• Um dispositivo Android físico conectado ao seu computador.
• Um Android Emulator (consulte Executar apps no Android Emulator).
• Um navegador da sua escolha, como o Chrome

Opcionalmente, para executar o codelab usando a plataforma iOS, você precisa de um dispositivo iOS, uma conta de desenvolvedor da Apple e um dispositivo macOS com o XCode instalado.

2. Configuração do Flutter

Se você já tiver um ambiente de desenvolvimento do Flutter configurado, pule esta seção.

Para configurar um ambiente de desenvolvimento do Flutter, siga estas etapas:

1. Faça o download e instale o Flutter no seu sistema operacional: Instalar | Flutter
2. Confira se a ferramenta Flutter foi adicionada ao seu caminho.
3. Configure seu editor para o Flutter conforme mostrado em Configurar um editor | Flutter. Não se esqueça de instalar os plug-ins do Flutter e do Dart para seu editor. No restante do codelab, você vai usar o Android Studio.
4. Na linha de comando, execute flutter doctor, que verifica a configuração e lista todas as dependências ausentes que precisam ser corrigidas. Siga as instruções para corrigir dependências importantes que estão faltando. Algumas dependências podem não ser necessárias. Por exemplo, se você não pretende desenvolver para iOS, uma dependência do CocoaPods ausente não é um problema de bloqueio.
5. Execute este comando para criar seu app do Flutter no diretório fcmflutter flutter create --org com.flutter.fcm --project-name fcmflutter fcmflutter e depois mude para fcmflutter.

6. No Android Studio, acesse File -> Open, encontre o caminho do seu app do Flutter e clique em Open para abrir o projeto no Android Studio. O código do app está no arquivo lib/main.dart.

Na barra de ferramentas do Android Studio, clique na seta para baixo para selecionar um dispositivo Android. Se o seletor estiver vazio, instale dispositivos Android virtuais, o navegador Chrome ou o simulador de iOS, se você preferir iniciar o app em um navegador da Web ou dispositivo iOS. Talvez seja necessário iniciar o dispositivo manualmente e atualizar a lista para encontrar o dispositivo de destino.

Clique em Run para iniciar o app.

Parabéns! Você criou um app do Flutter.

3. Configuração do Firebase e do FlutterFire

Para desenvolver um app que se integre ao Firebase Cloud Messaging usando o Flutter, você precisa de:

• um projeto do Firebase;
• Uma CLI do Firebase funcional
• Uma instalação do FlutterFire.
• Um app configurado e gerado com flutterfire configure.

Criar seu projeto do Firebase

Se você já tiver um projeto do Firebase, pule esta etapa.

1. Se você tem uma Conta do Google, abra o Firebase, faça login com ela e clique em Acesse o console.
2. No Console do Firebase, clique em Adicionar projeto. Siga as instruções para criar um projeto. Não marque a opção Ativar o Google Analytics para este projeto, porque você não o usará neste projeto.
3. Após a criação do projeto, navegue até as Configurações do projeto clicando no ícone de engrenagem ao lado de Visão geral do projeto.

O ID do projeto é usado para identificar o projeto de maneira exclusiva e pode ser diferente do Nome do projeto. O ID do projeto será usado para configurar o FlutterFire mais tarde.

Parabéns! Você criou um projeto do Firebase.

Configurar a CLI do Firebase

Se você tiver a CLI do Firebase configurada, pule esta etapa.

Acesse a referência da CLI do Firebase para fazer o download e instalar a CLI do Firebase. Faça login no Firebase com sua Conta do Google com o seguinte comando:

firebase login

Configurar o FlutterFire

1. Instale o plug-in do FlutterFire usando o comando: flutter pub add firebase_core
2. Instale o plug-in do FCM: flutter pub add firebase_messaging
3. Configure a CLI do FlutterFire: dart pub global activate flutterfire_cli
4. Configure o projeto do Firebase no Flutter: flutterfire configure --project=fcm4flutter. use as teclas de seta e a barra de espaço para selecionar as plataformas ou pressione Enter para usar as plataformas padrão.

Este codelab usa as plataformas padrão (Android, iOS e Web), mas você pode selecionar apenas uma ou duas. Se o ID do pacote iOS for solicitado, insira com.flutter.fcm.fcmflutter ou seu próprio ID do pacote iOS no formato [company domain name].[project name]. Depois que o comando for concluído, atualize a página do Console do Firebase. Você verá que ele criou apps para as plataformas selecionadas no projeto do Firebase.

Esse comando gera um arquivo firebase_options.dart no diretório lib, que contém todas as opções necessárias para a inicialização.

Configurar o Cloud Messaging para iOS

1. Acesse a página do desenvolvedor da Apple e clique em Criar uma chave na guia Chaves.

2. Digite o nome da chave e marque os Serviços de notificações push da Apple (APNs).
3. Faça o download do arquivo de chave, que tem a extensão .p8.
4. No Console do Firebase, acesse as Configurações do projeto e selecione a guia Cloud Messaging.

5. Faça upload do arquivo de chave de APNs do app iOS na guia Cloud Messaging. Digite o ID da chave APNs na guia Cloud Messaging e o ID da equipe, que pode ser encontrado na Central de assinaturas da Apple.

4. Preparação para FCM

Antes de um app receber mensagens do FCM, ele precisa:

• Inicialize o FlutterFire.
• Solicite permissões de notificação.
• Registre-se no FCM para receber um token de registro.

Inicialização

Para inicializar o serviço, substitua a função principal (lib/main.dart) por este código:

// core Flutter primitives
import 'package:flutter/foundation.dart';
// core FlutterFire dependency
import 'package:firebase_core/firebase_core.dart';
// generated by 

flutterfire configure

import 'firebase_options.dart';
// FlutterFire's Firebase Cloud Messaging plugin
import 'package:firebase_messaging/firebase_messaging.dart';

// TODO: Add stream controller
// TODO: Define the background message handler

Future<void> main() async {
 WidgetsFlutterBinding.ensureInitialized();
 await Firebase.initializeApp(
   options: DefaultFirebaseOptions.currentPlatform,
 );

 // TODO: Request permission
 // TODO: Register with FCM
 // TODO: Set up foreground message handler
 // TODO: Set up background message handler

 runApp(MyApp());
}

Em seguida, execute Tools -> Flutter -> Flutter Pub Get no Android Studio para carregar os pacotes adicionados em Configurar FlutterFire e exiba o código com a configuração do Intellisense adequada no Android Studio.

Isso inicializa o FlutterFire para a plataforma atual DefaultFirebaseOptions.currentPlatform, que é importada do arquivo firebase_options.dart gerado. Observe que initializeApp é uma função assíncrona, e a palavra-chave await garante que a inicialização seja concluída antes de executar o aplicativo.

Solicitar permissão

O app precisa pedir a permissão do usuário para receber notificações. O método requestPermission fornecido por firebase_messaging mostra uma caixa de diálogo ou pop-up solicitando que o usuário permita ou negue a permissão.

Primeiro, copie esse código para a função principal no comentário TODO: Request permission. O settings retornado informa se o usuário concedeu permissão. Recomendamos solicitar a permissão somente quando o usuário precisar usar um recurso que exija acesso, por exemplo, quando o usuário ativar as notificações nas configurações do app. Para simplificar, solicitamos permissão na inicialização do app neste codelab.

final messaging = FirebaseMessaging.instance;

final settings = await messaging.requestPermission(
 alert: true,
 announcement: false,
 badge: true,
 carPlay: false,
 criticalAlert: false,
 provisional: false,
 sound: true,
);

 if (kDebugMode) {
   print('Permission granted: ${settings.authorizationStatus}');
 }

Em seguida, na barra de ferramentas do Android Studio, selecione Chrome (web) no seletor de destino e execute o app novamente.

Em seguida, uma guia do Chrome é aberta com um pop-up solicitando permissão. Se você clicar em Allow, um registro vai aparecer no console do Android Studio: Permission granted: AuthorizationStatus.authorized. Depois de permitir ou bloquear a solicitação de permissão, sua resposta será armazenada com o app no navegador e o pop-up não será exibido novamente. Quando você executar o app da Web novamente no Android Studio, a permissão pode ser solicitada mais uma vez.

Inscrição

Copie este código para a função principal abaixo do comentário TODO: Register with FCM para se registrar no FCM. A chamada getToken retorna um token de registro que pode ser usado pelo servidor do app ou pelo ambiente de servidor confiável para enviar mensagens aos usuários.

// It requests a registration token for sending messages to users from your App server or other trusted server environment.
String? token = await messaging.getToken();

if (kDebugMode) {
  print('Registration Token=$token');
}

Na barra de ferramentas do Android Studio, selecione um dispositivo Android e execute o app. No console do Android Studio, o token de registro é mostrado da seguinte forma:

I/flutter ( 3717): Permission granted: AuthorizationStatus.authorized
I/flutter ( 3717): Registration Token=dch. . . D2P:APA9. . .kbb4

Copie-o para um editor de texto, pois você o usará para enviar mensagens mais tarde.

uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:firebase_messaging]

Etapas extras para receber mensagens na Web

Os apps da Web precisam de duas etapas extras para receber o token de registro e detectar mensagens recebidas. A Web precisa transmitir uma chave VAPID para getToken a fim de autorizar solicitações de envio para serviços de push da Web com suporte.

Primeiro, abra a guia Cloud Messaging do projeto do Firebase no console do Firebase e role para baixo até a seção Configuração da Web para encontrar o par de chaves existente ou gerar um novo. Clique no botão destacado para copiar a chave e usá-la como uma vapidKey.

Em seguida, substitua o código de registro na seção "Registration" por este código e atualize o vapidKey:

// TODO: replace with your own VAPID key
 const vapidKey = "<YOUR_PUBLIC_VAPID_KEY_HERE>";

 // use the registration token to send messages to users from your trusted server environment
 String? token;

 if (DefaultFirebaseOptions.currentPlatform == DefaultFirebaseOptions.web) {
   token = await messaging.getToken(
     vapidKey: vapidKey,
   );
 } else {
   token = await messaging.getToken();
 }

 if (kDebugMode) {
   print('Registration Token=$token');
 }

Em seguida, crie um arquivo firebase-messaging-sw.js abaixo do diretório web/ na raiz do projeto. Copie o código a seguir em firebase-messaging-sw.js para permitir que o app da Web receba eventos onMessage. Consulte Como definir opções de notificação no service worker para mais informações.

importScripts("https://www.gstatic.com/firebasejs/9.6.10/firebase-app-compat.js");
importScripts("https://www.gstatic.com/firebasejs/9.6.10/firebase-messaging-compat.js");

// todo Copy/paste firebaseConfig from Firebase Console
const firebaseConfig = {
 apiKey: "...",
 authDomain: "...",
 databaseURL: "...",
 projectId: "...",
 storageBucket: "...",
 messagingSenderId: "...",
 appId: "...",
};

firebase.initializeApp(firebaseConfig);
const messaging = firebase.messaging();

// todo Set up background message handler

Depois disso, em Project Settings -> guia General, role para baixo e encontre o Web App, copie a seção de código firebaseConfig e cole em firebase-messaging-sw.js.

Por fim, na barra de ferramentas do Android Studio, selecione Chrome (web) no seletor de destino e execute o app. No console do Android Studio, o token de registro é mostrado da seguinte forma:

Debug service listening on ws://127.0.0.1:61538/BLQQ3Fg-h7I=/ws
Permission granted: AuthorizationStatus.authorized
Registration Token=fH. . .ue:APA91. . .qwt3chpv

Copie o token de registro em um editor de texto para poder usá-lo no envio de mensagens posteriormente.

Etapas extras para receber mensagens no iOS

Para receber mensagens do FCM, os dispositivos iOS precisam ativar Push Notifications e os Background Modes no Xcode:

1. No Android Studio, clique com o botão direito do mouse no nome do projeto e selecione Flutter -> Open iOS module in Xcode.
2. Depois de lançar o Xcode, ative Push Notifications e Background Modes na guia Signing & Capabilities do projeto em questão. Consulte Configurar seu app para mais informações.
3. Na barra de ferramentas do Android Studio, selecione um dispositivo iOS no seletor de destino e execute o app. Depois que a permissão de notificação for concedida, o token de registro será impresso no console do Android Studio.

Parabéns, você registrou seu app no FCM. Você já pode receber mensagens, conforme descrito na próxima seção.

5. Receber mensagens do FCM

Configurar gerenciadores de mensagens

O app precisa processar eventos onMessage quando as mensagens chegam enquanto está no modo de primeiro plano e os eventos onBackgroundMessage quando está em segundo plano.

Gerenciador de mensagens em primeiro plano

Primeiro, adicione um controlador de stream após o comentário TODO: Add stream controller no arquivo main.dart para transmitir mensagens do manipulador de eventos para a IU.

import 'package:rxdart/rxdart.dart';
// used to pass messages from event handler to the UI
final _messageStreamController = BehaviorSubject<RemoteMessage>();

Para adicionar a dependência rxdart, execute este comando no diretório do projeto: flutter pub add rxdart.

Em seguida, execute Tools -> Flutter -> Flutter Pub Get no Android Studio para carregar o pacote rxdart.dart e exibir o código com as configurações apropriadas do Intellisense no Android Studio.

Em seguida, adicione um manipulador de eventos para detectar mensagens em primeiro plano após o comentário TODO: Set up foreground message handler. Ele imprime registros e publica a mensagem no controlador de stream.

 FirebaseMessaging.onMessage.listen((RemoteMessage message) {
   if (kDebugMode) {
     print('Handling a foreground message: ${message.messageId}');
     print('Message data: ${message.data}');
     print('Message notification: ${message.notification?.title}');
     print('Message notification: ${message.notification?.body}');
   }

   _messageStreamController.sink.add(message);
 });

Depois disso, substitua o widget de estado original no arquivo main.dart por esse código, que adiciona um assinante ao controlador de stream no widget de estado e exibe a última mensagem no widget.

class _MyHomePageState extends State<MyHomePage> {
 String _lastMessage = "";

 _MyHomePageState() {
   _messageStreamController.listen((message) {
     setState(() {
       if (message.notification != null) {
         _lastMessage = 'Received a notification message:'
             '\nTitle=${message.notification?.title},'
             '\nBody=${message.notification?.body},'
             '\nData=${message.data}';
       } else {
         _lastMessage = 'Received a data message: ${message.data}';
       }
     });
   });
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
     appBar: AppBar(
       title: Text(widget.title),
     ),
     body: Center(
       child: Column(
         mainAxisAlignment: MainAxisAlignment.center,
         children: <Widget>[
           Text('Last message from Firebase Messaging:',
               style: Theme.of(context).textTheme.titleLarge),
           Text(_lastMessage, style: Theme.of(context).textTheme.bodyLarge),
         ],
       ),
     ),
   );
 }
}

Gerenciador de mensagens em segundo plano para Android/iOS

As mensagens são processadas pelo gerenciador onBackgroundMessage enquanto o app está em segundo plano. O gerenciador deve ser uma função de nível superior. A interface pode ser atualizada quando o app é colocado em primeiro plano processando as mensagens (consulte Como gerenciar interações) ou sincronizando com o servidor do app.

Crie a função de gerenciador após o comentário TODO: Define the background message handler fora da função principal e a chame na função principal após o comentário TODO: Set up background message handler.

// TODO: Define the background message handler
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
 await Firebase.initializeApp();

 if (kDebugMode) {
   print("Handling a background message: ${message.messageId}");
   print('Message data: ${message.data}');
   print('Message notification: ${message.notification?.title}');
   print('Message notification: ${message.notification?.body}');
 }
}

void main() {
 ...

 // TODO: Set up background message handler
 FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

 runApp(MyApp());
}

Gerenciador de mensagens em segundo plano para a Web

A partir do FlutterFire firebase_messaging versão 11.2.8, processar mensagens em segundo plano em plataformas baseadas na Web requer um fluxo diferente. Portanto, é preciso adicionar um gerenciador de mensagens separado no service worker web/firebase-messaging-sw.js.

messaging.onBackgroundMessage((message) => {
 console.log("onBackgroundMessage", message);
});

Configurar o servidor do app

1. Para importar o código do servidor inicial, abra o projeto https://github.com/FirebaseExtended/firebase_fcm_flutter/tree/main/server no Android Studio. O servidor é um projeto Java baseado em Gradle com uma dependência no SDK firebase-admin, que fornece a funcionalidade de envio de mensagens do FCM.
2. Configure uma conta de serviço do Firebase que permita que o SDK Admin do Firebase autorize chamadas para as APIs do FCM. Abra as Configurações do projeto no Console do Firebase e selecione a guia Contas de serviço. Escolha "Java" e clique em Generate new private key para fazer o download do snippet de configuração.
3. Renomeie o arquivo como service-account.json e copie-o para o caminho src/main/resources do projeto do servidor.

Enviar uma mensagem de teste

No arquivo FcmSender.java, sendMessageToFcmRegistrationToken compõe uma mensagem de notificação com um payload de dados. O token de registro é direcionado à instância do app para a qual a mensagem é enviada.

private static void sendMessageToFcmRegistrationToken() throws Exception {
   String registrationToken = "REPLACE_WITH_FCM_REGISTRATION_TOKEN";
   Message message =
       Message.builder()
           .putData("FCM", "https://firebase.google.com/docs/cloud-messaging")
           .putData("flutter", "https://flutter.dev/")
           .setNotification(
               Notification.builder()
                   .setTitle("Try this new app")
                   .setBody("Learn how FCM works with Flutter")
                   .build())
           .setToken(registrationToken)
           .build();

   FirebaseMessaging.getInstance().send(message);

   System.out.println("Message to FCM Registration Token sent successfully!!");
 }

1. Copie o token de registro do Android copiado da seção "Registro" e cole-o no valor da variável registrationToken.
2. Clique em Run para executar a função principal e enviar a mensagem ao usuário pelo FCM.

Quando o app Android está em segundo plano, a mensagem aparece na bandeja de notificações.

Quando o app Android estiver em primeiro plano, você verá um registro no console do Android Studio: "Processamento de uma mensagem em primeiro plano". O conteúdo da mensagem também é exibido na IU porque ela está inscrita no controlador de stream para novas mensagens.

Se você colar o token de registro e enviar a mensagem do servidor de aplicativos ou de outro ambiente de servidor confiável, o comportamento será semelhante:

• Quando o app da Web está em segundo plano (ou seja, quando está oculto por outra janela ou quando outra guia está ativa), você vê uma notificação da Web.

• Quando o app da Web está em primeiro plano, você pode ver o registro no console do Chrome clicando com o botão direito do mouse na Web e selecionando Inspect. O conteúdo da mensagem também é exibido na interface.

6. Enviar uma mensagem por tópico

O recurso de substituição de plataforma da API FCM HTTP v1 permite que uma solicitação de envio de mensagens tenha comportamentos distintos em diferentes plataformas. Um caso de uso desse recurso é mostrar um conteúdo diferente de mensagens de notificação com base na plataforma. O recurso é mais usado ao segmentar vários dispositivos (que podem abranger várias plataformas) com mensagens de tópico. Esta seção mostra as etapas para fazer com que o app receba uma mensagem de tópico personalizada para cada plataforma.

Assinar um tópico do cliente

Para se inscrever em um tópico, chame o método messaging.subscribeToTopic no final da função principal no arquivo main.dart do app Flutter.

// subscribe to a topic.
const topic = 'app_promotion';
await messaging.subscribeToTopic(topic);

[Opcional] Inscrever-se em um tópico pelo servidor para a Web

Pule esta seção se você não estiver desenvolvendo na plataforma da Web.

No momento, o SDK do FCM para JS não é compatível com a assinatura de tópicos do cliente. Você pode se inscrever usando a API de gerenciamento de tópicos do lado do servidor do SDK Admin. Este código ilustra a assinatura do tópico do lado do servidor com o SDK Admin para Java.

 private static void subscribeFcmRegistrationTokensToTopic() throws Exception {
   List<String> registrationTokens =
       Arrays.asList(
           "REPLACE_WITH_FCM_REGISTRATION_TOKEN"); // TODO: add FCM Registration Tokens to
   // subscribe
   String topicName = "app_promotion";

   TopicManagementResponse response =     FirebaseMessaging.getInstance().subscribeToTopic(registrationTokens, topicName);
   System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
 }

Abra o servidor do app e clique em Run para executar a função principal no arquivo FcmSubscriptionManager.java:

Enviar uma mensagem com substituições de plataformapara um tópico

Agora você está pronto para enviar uma mensagem de substituição de plataforma de tópicos. No snippet de código a seguir:

• Você cria uma solicitação de envio com uma mensagem base e o título "A new app is available".
• A mensagem gera uma notificação de exibição com o título "A new app is available" nas plataformas da Web e do iOS.
• A mensagem gera uma notificação de exibição com o título "A new Android app is available" em dispositivos Android.

private static void sendMessageToFcmTopic() throws Exception {
   String topicName = "app_promotion";

   Message message =
       Message.builder()
           .setNotification(
               Notification.builder()
                   .setTitle("A new app is available")
                   .setBody("Check out our latest app in the app store.")
                   .build())
           .setAndroidConfig(
               AndroidConfig.builder()
                   .setNotification(
                       AndroidNotification.builder()
                           .setTitle("A new Android app is available")
                           .setBody("Our latest app is available on Google Play store")
                           .build())
                   .build())
           .setTopic("app_promotion")
           .build();

   FirebaseMessaging.getInstance().send(message);

   System.out.println("Message to topic sent successfully!!");
 }

Na função principal do arquivo FcmSender.java, remova a marca de comentário de sendMessageToFcmTopic();. Clique em Run para enviar a mensagem de tópico.

7. Resumo e próximos passos

Para resumir, você aprendeu sobre o engajamento no desenvolvimento de apps multiplataforma usando o Flutter e o FCM, o que inclui configuração de ambiente, integração de dependências e recebimento e envio de mensagens. Para saber mais, consulte os seguintes materiais:

Codelabs

• Para saber mais sobre como o Flutter funciona com outros produtos do Firebase, incluindo autenticação de usuários e sincronização de dados, consulte Conheça o Firebase para Flutter.
• Para saber mais sobre o FCM, incluindo mensagens e tópicos no app: Use o FCM e o FIAM para enviar mensagens aos usuários e Sua primeira mensagem push multicast usando tópicos do FCM

References

• Site do Firebase
• Site do Flutter
• Widgets do Flutter no Firebase para Flutter
• Canal do Firebase no YouTube
• Canal do Flutter no YouTube