Envie e receba notificações para um aplicativo Flutter usando Firebase Cloud Messaging

1. Introdução

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

Este codelab orienta você no processo de desenvolvimento de um aplicativo multiplataforma com Firebase Cloud Messaging (FCM) usando Flutter. Você escreverá uma parte da implementação do aplicativo e, em seguida, criará e executará ele perfeitamente em três plataformas: Android, iOS e web. Você também aprenderá como integrar o FCM ao Flutter e como escrever código para receber e enviar mensagens. Por fim, o codelab apresenta o recurso de blocos específicos da plataforma da API FCM HTTP v1, que permite enviar uma mensagem com comportamentos diferentes em plataformas diferentes.

Pré-requisito

Compreensão básica do Flutter.

O que você aprenderá

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

O que você precisará

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

Você pode executar o codelab usando qualquer um dos seguintes dispositivos:

• Um dispositivo Android físico conectado ao seu computador.
• Um emulador Android (consulte Executar aplicativos no Android Emulator ).
• Um navegador de sua preferência, como o Chrome.

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

2. Configuração de vibração

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

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

1. Baixe e instale o Flutter para o seu sistema operacional: Instalar | Vibração
2. Certifique-se de que a ferramenta Flutter esteja adicionada ao seu caminho.
3. Configure seu editor para Flutter conforme mostrado em Configurar um editor | Flutter Certifique-se de instalar os plug-ins Flutter e Dart em seu editor. No restante do codelab, você usará o Android Studio.
4. Na linha de comando, execute flutter doctor , que verifica sua configuração e lista todas as dependências ausentes que precisam ser corrigidas. Siga as instruções para corrigir quaisquer dependências importantes ausentes. Observe que algumas dependências podem não ser necessárias. Por exemplo, se você não pretende desenvolver para iOS, uma dependência ausente do CocoaPods não será um problema de bloqueio.
5. Execute este comando para criar seu aplicativo Flutter no diretório fcmflutter flutter create --org com.flutter.fcm --project-name fcmflutter fcmflutter e, em seguida, altere os diretórios para fcmflutter .

6. No Android Studio, vá para File -> Open , encontre o caminho do seu aplicativo Flutter e clique em Open para abrir o projeto no Android Studio. O código do aplicativo 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 de destino estiver vazio, instale dispositivos Android virtuais ou navegador Chrome ou simulador iOS se preferir iniciar o aplicativo a partir de um navegador da web ou dispositivo iOS. Pode ser necessário iniciar o dispositivo manualmente e atualizar a lista para encontrar o dispositivo de destino.

Clique em Executar para iniciar o aplicativo.

Parabéns! Você criou um aplicativo Flutter com sucesso.

3. Configuração do Firebase e FlutterFire

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

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

Crie seu projeto Firebase

Se você já possui um projeto Firebase, pode pular esta etapa.

1. Se você tiver uma Conta do Google, abra o Firebase , faça login com sua Conta do Google e clique em Ir para o console .
2. No Firebase Console, clique em Adicionar projeto . Siga as instruções para criar um projeto. Não marque Habilitar Google Analytics para este projeto porque você não o usará neste projeto.
3. Depois que o projeto for criado, navegue até as Configurações do projeto clicando no ícone de engrenagem próximo a Visão geral do projeto .

O ID do projeto é usado para identificar exclusivamente o projeto e pode ser diferente do nome do projeto . O ID do projeto será usado para configurar o FlutterFire posteriormente.

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

Configure a CLI do Firebase

Se você tiver a CLI do Firebase configurada, poderá pular esta etapa.

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

firebase login

Configurar o FlutterFire

1. Instale o plugin FlutterFire usando o comando: flutter pub add firebase_core
2. Instale o plugin FCM: flutter pub add firebase_messaging
3. Configure a CLI do FlutterFire: dart pub global activate flutterfire_cli
4. Configure o projeto Firebase no Flutter: flutterfire configure --project=fcm4flutter. Use as teclas de seta e 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 plataformas. Se for solicitado o ID do pacote iOS, insira com.flutter.fcm.fcmflutter ou seu próprio ID do pacote iOS no formato [company domain name].[project name] . Após a conclusão do comando, atualize a página do Firebase Console. Você verá que ele criou aplicativos para as plataformas selecionadas no projeto Firebase.

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

Configure o Cloud Messaging para iOS

1. Navegue até a página do desenvolvedor Apple e clique em Criar uma chave na guia Chaves .

2. Digite o nome da chave e verifique os serviços Apple Push Notifications (APNs) .
3. Baixe o arquivo-chave, que possui uma extensão de arquivo .p8 .
4. No console do Firebase , navegue até as configurações do projeto do projeto e escolha a guia Cloud Messaging .

5. Carregue o arquivo de chave APNs para o aplicativo iOS na guia Cloud Messaging . Insira o ID da chave APNs na guia Cloud Messaging e o ID da equipe, que pode ser encontrado no centro de associação da Apple.

4. Preparação para FCM

Antes que um aplicativo possa receber mensagens do FCM, ele precisa:

• Inicialize o FlutterFire.
• Solicite permissões de notificação.
• Registre-se no FCM para obter 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 in Android Studio para carregar os pacotes adicionados em Set up FlutterFire e exibir o código com a configuração apropriada do Intellisense 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 aplicativo precisa pedir permissão ao 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 conceda ou negue a permissão.

Primeiro, copie este código para a função principal sob o comentário TODO: Request permission . As settings retornadas informam se o usuário concedeu permissão. Recomendamos solicitar permissão apenas 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 aplicativo). Neste codelab, solicitamos permissão na inicialização do app para simplificar.

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 aplicativo novamente.

Em seguida, uma guia do Chrome é iniciada com um pop-up solicitando permissão. Se você clicar em Allow , verá um log no console do Android Studio: Permission granted: AuthorizationStatus.authorized . Depois de permitir ou bloquear a solicitação de permissão, sua resposta será armazenada junto com seu aplicativo no navegador e o pop-up não será exibido novamente. Observe que, ao executar o aplicativo Web novamente no Android Studio, a permissão poderá ser solicitada novamente.

Cadastro

Copie este código para a função principal abaixo do comentário TODO: Register with FCM para registrar-se no FCM. A chamada getToken retorna um token de registro que pode ser usado pelo servidor de aplicativos ou 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 aplicativo. No console do Android Studio, o token de registro é impresso assim:

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 utilizará posteriormente para enviar mensagens.

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

Etapas extras para receber mensagens na web

Os aplicativos da Web precisam de duas etapas extras para obter o token de registro e escutar as mensagens recebidas. A Web precisa passar uma chave VAPID para getToken para autorizar o envio de solicitações para serviços web push suportados.

Primeiro, abra a guia Cloud Messaging do projeto Firebase no Firebase Console, role para baixo até a seção de configuração da Web para encontrar o par de chaves existente ou gere um novo par de chaves. Clique no botão destacado para copiar a chave para que ela possa ser usada como vapidKey.

Em seguida, substitua o código de registro na seção Registro 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 seu projeto. Copie o seguinte para firebase-messaging-sw.js para permitir que o aplicativo da web receba eventos onMessage . Consulte Configurando opções de notificação no service worker para obter 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, na guia Configurações do projeto -> Geral , role para baixo e encontre o Web App , copie a seção de código firebaseConfig e cole-a em firebase-messaging-sw.js .

Por fim, na barra de ferramentas do Android Studio, selecione Chrome (web) no seletor de destino e execute o aplicativo. No console do Android Studio, o token de registro é impresso assim:

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 para enviar mensagens posteriormente.

Etapas extras para receber mensagens no iOS

Para receber mensagens do FCM, os dispositivos iOS precisam ativar notificações push e modos de segundo plano no Xcode:

1. No Android Studio, clique com o botão direito no nome do projeto e selecione Flutter -> Open iOS module in Xcode .
2. Após o lançamento do Xcode, habilite notificações push e modos de segundo plano na guia Assinatura e recursos para o destino do projeto. Consulte Configurar seu aplicativo para obter mais informações.
3. Na barra de ferramentas do Android Studio, selecione um dispositivo iOS no seletor de destino e execute o aplicativo. 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 aplicativo com sucesso no FCM. Você está pronto para receber mensagens, conforme descrito na próxima seção.

5. Receba mensagens do FCM

Configurar gerenciadores de mensagens

O aplicativo precisa lidar com eventos onMessage quando as mensagens chegam enquanto o aplicativo está no modo de primeiro plano e eventos onBackgroundMessage quando o aplicativo está em segundo plano.

Manipulador de mensagens em primeiro plano

Primeiro, adicione um controlador de stream após o comentário TODO: Add stream controller in file main.dart para passar mensagens do manipulador de eventos para a UI.

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 Ferramentas -> Flutter -> Flutter Pub. Entre 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 escutar mensagens em primeiro plano após o comentário TODO: Set up foreground message handler . Ele imprime logs 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 State original no arquivo main.dart por este código, que adiciona um assinante ao controlador de fluxo no widget State 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),
         ],
       ),
     ),
   );
 }
}

Manipulador de mensagens em segundo plano para Android/iOS

As mensagens são tratadas pelo manipulador onBackgroundMessage enquanto o aplicativo está em segundo plano. O manipulador deve ser uma função de nível superior. A UI pode ser atualizada quando o aplicativo é colocado em primeiro plano, manipulando as mensagens (consulte Tratamento da interação ) ou sincronizando com o servidor do aplicativo.

Crie a função manipuladora após o comentário TODO: Define the background message handler fora da função principal e chame-o 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());
}

Manipulador de mensagens em segundo plano para web

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

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

Configure o servidor de aplicativos

1. Importe o código do servidor inicial abrindo o projeto https://github.com/FirebaseExtended/firebase_fcm_flutter/tree/main/server no Android Studio. O servidor é um projeto Java baseado em Gradle com dependência do SDK firebase-admin , que fornece funcionalidade de envio de mensagens FCM.
2. Configure uma conta de serviço do Firebase que permita que o SDK Admin do Firebase autorize chamadas para 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 baixar o snippet de configuração.
3. Renomeie o arquivo para service-account.json e copie-o para o caminho src/main/resources do projeto do servidor.

Envie uma mensagem de teste

No arquivo FcmSender.java , sendMessageToFcmRegistrationToken compõe uma mensagem de notificação com uma carga útil de dados. O token de registro tem como alvo a instância do aplicativo 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 Executar para executar a função principal e enviar a mensagem ao usuário através do FCM.

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

Quando o aplicativo Android estiver em primeiro plano, você verá um log no console do Android Studio: "Tratando uma mensagem em primeiro plano". O conteúdo da mensagem também é exibido na UI porque a UI está inscrita no controlador de fluxo 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, verá um comportamento semelhante:

• Quando o aplicativo da web estiver em segundo plano (ou seja, quando estiver oculto por outra janela ou outra guia estiver ativa), você verá uma notificação da web.

• Quando o aplicativo da web estiver em primeiro plano, você poderá visualizar 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 UI.

6. Envie uma mensagem de tópico

O recurso de substituição de plataforma da API FCM HTTP v1 permite que uma solicitação de envio de mensagem tenha comportamentos diferentes em plataformas diferentes. Um caso de uso desse recurso é exibir diferentes conteúdos de mensagens de notificação com base na plataforma. O recurso é mais utilizado ao direcionar vários dispositivos (que podem abranger diversas plataformas) com mensagens de tópico. Esta seção orienta você nas etapas para fazer com que seu aplicativo receba uma mensagem de tópico personalizada para cada plataforma.

Inscrever-se em um tópico do cliente

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

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

[Opcional] Assine um tópico do servidor para web

Você pode pular esta seção se não estiver desenvolvendo na plataforma web.

Atualmente, o FCM JS SDK não oferece suporte à assinatura de tópicos do lado do cliente. Em vez disso, você pode se inscrever usando a API de gerenciamento de tópicos do servidor do SDK Admin. Este código ilustra a assinatura de tópico do lado do servidor com o Java Admin SDK.

 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 de aplicativos e clique em Executar para executar a função principal no arquivo FcmSubscriptionManager.java :

Envie uma mensagem com substituição de plataforma para um tópico

Agora você está pronto para enviar uma mensagem de substituição da plataforma de tópico. No seguinte trecho de código:

• Você constrói 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 iOS e web.
• 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 o comentário sendMessageToFcmTopic(); . Clique em Executar para enviar a mensagem do tópico.

7. Resumo e o que vem a seguir

Para resumir, você aprendeu como envolver o desenvolvimento de aplicativos multiplataforma usando Flutter e FCM, o que inclui configuração de ambiente, integração de dependências e recebimento e envio de mensagens. Para se aprofundar, consulte os seguintes materiais:

Codelabs

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

Referências

• Site do Firebase
• Site flutuante
• Widgets FlutterFire Firebase Flutter
• Canal do Firebase no YouTube
• Canal Flutter no YouTube