1. Introducción

Última actualización: 04/04/2022

En este codelab, se explica el proceso de desarrollo de una app multiplataforma con Firebase Cloud Messaging (FCM) mediante Flutter. Escribirás una parte de la implementación de la app y, luego, la compilarás y ejecutarás sin problemas en tres plataformas: Android, iOS y la Web. También aprenderás a integrar FCM en Flutter y a escribir código para recibir y enviar mensajes. Por último, el codelab presenta la función de bloques específicos de la plataforma de la API de HTTP v1 de FCM, que te permite enviar un mensaje que tenga diferentes comportamientos en diferentes plataformas.

Requisitos previos

Conocimientos básicos de Flutter

Qué aprenderás

• Cómo configurar y crear una app de Flutter
• Cómo agregar dependencias de FCM
• Cómo enviar mensajes de FCM individuales a tu app
• Cómo enviar mensajes de FCM de temas a tu app

Requisitos

• La versión estable más reciente de Android Studio configurada con los complementos de Dart y Flutter

Puedes ejecutar el codelab en cualquiera de los siguientes dispositivos:

• Un dispositivo Android físico conectado a tu computadora
• Un emulador de Android (consulta Cómo ejecutar apps en Android Emulator).
• El navegador que elijas, como Chrome

De manera opcional, para ejecutar el codelab con la plataforma de iOS, necesitas un dispositivo iOS, una cuenta de Apple Developer y un dispositivo macOS con Xcode instalado.

2. Configuración de Flutter

Si ya tienes configurado un entorno de desarrollo de Flutter, omite esta sección.

Para configurar un entorno de desarrollo de Flutter, sigue estos pasos:

1. Descarga e instala Flutter para tu sistema operativo: Install | Flutter
2. Asegúrate de que la herramienta de Flutter se haya agregado a tu ruta.
3. Configura tu editor para Flutter como se muestra en Configura un editor | Flutter. Asegúrate de instalar los complementos de Flutter y Dart para tu editor. En el resto del codelab, usarás Android Studio.
4. Desde la línea de comandos, ejecuta flutter doctor, que analiza tu configuración y enumera las dependencias faltantes que se deben corregir. Sigue las instrucciones para corregir las dependencias importantes que faltan. Ten en cuenta que es posible que algunas dependencias no sean necesarias. Por ejemplo, si no vas a desarrollar para iOS, una dependencia faltante de CocoaPods no será un problema de bloqueo.
5. Ejecuta este comando para crear tu app de Flutter en el directorio fcmflutter flutter create --org com.flutter.fcm --project-name fcmflutter fcmflutter y, luego, cambia de directorio a fcmflutter.

6. En Android Studio, ve a File -> Open, busca la ruta de acceso de tu app para Flutter y, luego, haz clic en Open para abrir el proyecto en Android Studio. El código de la app se encuentra en el archivo ​​lib/main.dart.

En la barra de herramientas de Android Studio, haz clic en la flecha hacia abajo para seleccionar un dispositivo Android. Si el selector de destino está vacío, instala dispositivos virtuales de Android, el navegador Chrome o el simulador de iOS si prefieres iniciar la app desde un navegador web o un dispositivo iOS. Es posible que debas iniciar el dispositivo de forma manual y actualizar la lista para encontrar el dispositivo de destino.

Haz clic en Run para iniciar la app.

¡Felicitaciones! Creaste correctamente una app de Flutter.

3. Configuración de Firebase y FlutterFire

Para desarrollar una app que se integre con Firebase Cloud Messaging con Flutter, necesitas lo siguiente:

• Un proyecto de Firebase
• Una Firebase CLI que funcione
• Una instalación de FlutterFire.
• Una app configurada y generada con flutterfire configure

Crea tu proyecto de Firebase

Si ya tienes un proyecto de Firebase, puedes omitir este paso.

1. Si tienes una Cuenta de Google, abre Firebase, accede con tu Cuenta de Google y, luego, haz clic en Ir a la consola.
2. En Firebase console, haz clic en Agregar proyecto. Sigue las instrucciones para crear un proyecto. No marques la opción Habilitar Google Analytics para este proyecto porque no lo usarás en este proyecto.
3. Después de crear el proyecto, haz clic en el ícono de ajustes junto a Descripción general del proyecto para navegar a la Configuración del proyecto.

El ID del proyecto se usa para identificar el proyecto de forma única y puede ser diferente del Nombre del proyecto. El ID del proyecto se usará para configurar FlutterFire más adelante.

¡Felicitaciones! Creaste correctamente un proyecto de Firebase.

Configura Firebase CLI

Si tienes configurado Firebase CLI, puedes omitir este paso.

Ve a la referencia de Firebase CLI para descargar e instalar Firebase CLI. Accede a Firebase con tu Cuenta de Google con el siguiente comando:

firebase login

Configura FlutterFire

1. Instala el complemento FlutterFire con el comando flutter pub add firebase_core.
2. Instala el complemento de FCM: flutter pub add firebase_messaging
3. Configura la CLI de FlutterFire: dart pub global activate flutterfire_cli
4. Configura el proyecto de Firebase en Flutter: flutterfire configure --project=fcm4flutter. Usa las teclas de flecha y el espacio para seleccionar las plataformas o presiona Intro para usar las plataformas predeterminadas.

En este codelab, se usan las plataformas predeterminadas (Android, iOS y la Web), pero puedes seleccionar solo una o dos plataformas. Si se te solicita el ID del paquete de iOS, ingresa com.flutter.fcm.fcmflutter o tu propio ID del paquete de iOS en el formato [company domain name].[project name]. Una vez que se complete el comando, actualiza la página de Firebase console. Verás que se crearon apps para las plataformas seleccionadas en el proyecto de Firebase.

Este comando genera un archivo firebase_options.dart en el directorio lib, que contiene todas las opciones necesarias para la inicialización.

Configura Cloud Messaging para iOS

1. Navega a la página para desarrolladores de Apple y haz clic en Crear una clave en la pestaña Claves.

2. Ingresa el nombre de la clave y marca la opción Servicios de notificaciones push de Apple (APNS).
3. Descarga el archivo de clave, que tiene la extensión de archivo .p8.
4. En Firebase console, navega a la Configuración del proyecto del proyecto y elige la pestaña Cloud Messaging.

5. Sube el archivo de claves de APNS de la app para iOS en la pestaña Cloud Messaging. Ingresa el ID de clave de APNs de la pestaña Cloud Messaging y el ID de equipo, que se encuentra en el Centro de membresías de Apple.

4. Preparación para FCM

Para que una app pueda recibir mensajes de FCM, debe cumplir con los siguientes requisitos:

• Inicializa FlutterFire.
• Solicita permisos de notificaciones.
• Regístrate en FCM para obtener un token de registro.

Inicialización

Para inicializar el servicio, reemplaza la función 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());
}

Luego, ejecuta Tools -> Flutter -> Flutter Pub Get en Android Studio para cargar los paquetes agregados en Configura FlutterFire y muestra el código con la configuración de Intellisense adecuada en Android Studio.

Esto inicializa FlutterFire para la plataforma DefaultFirebaseOptions.currentPlatform actual, que se importa desde el archivo firebase_options.dart generado. Ten en cuenta que initializeApp es una función asíncrona, y la palabra clave await garantiza que la inicialización se complete antes de ejecutar la aplicación.

Cómo solicitar permiso

La app debe solicitar el permiso del usuario para recibir notificaciones. El método requestPermission que proporciona firebase_messaging muestra un diálogo o una ventana emergente en la que se le solicita al usuario que permita o rechace el permiso.

Primero, copia este código en la función principal debajo del comentario TODO: Request permission. El settings que se muestra te indica si el usuario otorgó el permiso. Recomendamos solicitar el permiso solo cuando el usuario necesite usar una función que requiera acceso (p.ej., cuando el usuario activa las notificaciones en la configuración de la app). En este codelab, solicitamos permiso al inicio de la app por cuestiones de simplicidad.

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}');
 }

A continuación, en la barra de herramientas de Android Studio, selecciona Chrome (web) en el selector de destino y, luego, vuelve a ejecutar la app.

Luego, se abrirá una pestaña de Chrome con una ventana emergente que solicitará permiso. Si haces clic en Allow, verás un registro en la consola de Android Studio: Permission granted: AuthorizationStatus.authorized. Después de permitir o bloquear la solicitud de permiso, tu respuesta se almacena junto con la app en el navegador y no se vuelve a mostrar la ventana emergente. Ten en cuenta que, cuando vuelvas a ejecutar la app web en Android Studio, es posible que se te solicite nuevamente el permiso.

Registro

Copia este código en la función principal debajo del comentario TODO: Register with FCM para registrarte en FCM. La llamada a getToken muestra un token de registro que el servidor de apps o el entorno de servidor de confianza pueden usar para enviar mensajes a los usuarios.

// 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');
}

En la barra de herramientas de Android Studio, selecciona un dispositivo Android y ejecuta la app. En la consola de Android Studio, el token de registro se imprime de la siguiente manera:

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

Cópialo en un editor de texto, ya que lo usarás para enviar mensajes más adelante.

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

Pasos adicionales para recibir mensajes en la Web

Las apps web necesitan dos pasos adicionales para obtener el token de registro y escuchar los mensajes entrantes. La Web debe pasar una clave VAPID a getToken para autorizar solicitudes de envío a servicios push web compatibles.

Primero, abre la pestaña Cloud Messaging del proyecto de Firebase en Firebase console, desplázate hacia abajo hasta la sección Configuración web para encontrar el par de claves existente o generar uno nuevo. Haz clic en el botón destacado para copiar la clave y que se pueda usar como vapidKey.

A continuación, reemplaza el código de registro en la sección Registro por este código y, luego, actualiza 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');
 }

Luego, crea un archivo firebase-messaging-sw.js debajo del directorio web/ en la raíz de tu proyecto. Copia lo siguiente en firebase-messaging-sw.js para permitir que la app web reciba eventos onMessage. Consulta Cómo configurar las opciones de notificación en el service worker para obtener más información.

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

Después, en la pestaña Project Settings -> General, desplázate hacia abajo y busca Web App, copia la sección de código firebaseConfig y pégala en firebase-messaging-sw.js.

Por último, en la barra de herramientas de Android Studio, selecciona Chrome (web) en el selector de destino y ejecuta la app. En la consola de Android Studio, el token de registro se imprime de la siguiente manera:

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

Copia el token de registro en un editor de texto para poder usarlo para enviar mensajes más adelante.

Pasos adicionales para recibir mensajes en iOS

Para recibir mensajes de FCM, los dispositivos iOS deben habilitar las notificaciones push y los modos en segundo plano en Xcode:

1. En Android Studio, haz clic con el botón derecho en el nombre del proyecto y, luego, selecciona Flutter -> Open iOS module in Xcode.
2. Después de iniciar Xcode, habilita Notificaciones push y Modos en segundo plano en la pestaña Firma y capacidades para el destino del proyecto. Consulta Configura tu app para obtener más información.
3. En la barra de herramientas de Android Studio, selecciona un dispositivo iOS en el selector de destino y ejecuta la app. Después de que se otorgue el permiso de notificación, el token de registro se imprimirá en la consola de Android Studio.

Felicitaciones, registraste correctamente tu app en FCM. Ya puedes recibir mensajes, como se describe en la siguiente sección.

5. Cómo recibir mensajes de FCM

Cómo configurar controladores de mensajes

La app debe controlar los eventos onMessage cuando llegan mensajes mientras la app está en modo en primer plano y los eventos onBackgroundMessage cuando la app está en segundo plano.

Controlador de mensajes en primer plano

Primero, agrega un controlador de transmisión después del comentario TODO: Add stream controller en el archivo main.dart para pasar mensajes del controlador de eventos a la IU.

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

Para agregar la dependencia rxdart, ejecuta este comando desde el directorio del proyecto: flutter pub add rxdart.

A continuación, ejecuta Tools -> Flutter -> Flutter Pub Get en Android Studio para cargar el paquete rxdart.dart y mostrar el código con la configuración de Intellisense adecuada en Android Studio.

Luego, agrega un controlador de eventos para detectar mensajes en primer plano después del comentario TODO: Set up foreground message handler. Imprime registros y publica el mensaje en el controlador de flujo.

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

Después de eso, reemplaza el widget de estado original en el archivo main.dart por este código, que agrega un suscriptor al controlador de transmisión en el widget de estado y muestra el último mensaje en el 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),
         ],
       ),
     ),
   );
 }
}

Controlador de mensajes en segundo plano para Android/iOS

El controlador onBackgroundMessage controla los mensajes mientras la app está en segundo plano. El controlador debe ser una función de nivel superior. La IU se puede actualizar cuando la app pasa a primer plano controlando los mensajes (consulta Cómo controlar la interacción) o sincronizando con el servidor de la app.

Crea la función del controlador después del comentario TODO: Define the background message handler fuera de la función principal y llámala en la función principal después del comentario 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());
}

Controlador de mensajes en segundo plano para la Web

A partir de la versión 11.2.8 de firebase_messaging de FlutterFire, el manejo de mensajes en segundo plano en plataformas basadas en la Web requiere un flujo diferente. Por lo tanto, debes agregar un controlador de mensajes independiente en el trabajador de servicio web/firebase-messaging-sw.js.

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

Configura el servidor de apps

1. Para importar el código del servidor de partida, abre el proyecto https://github.com/FirebaseExtended/firebase_fcm_flutter/tree/main/server en Android Studio. El servidor es un proyecto de Java basado en Gradle con una dependencia en el SDK de firebase-admin, que proporciona la funcionalidad de envío de mensajes de FCM.
2. Configura una cuenta de servicio de Firebase que permita que el SDK de Firebase Admin autorice las llamadas a las APIs de FCM. Abre la configuración del proyecto en Firebase console y selecciona la pestaña Cuentas de servicio. Elige “Java” y haz clic en Generate new private key para descargar el fragmento de configuración.
3. Cambia el nombre del archivo a service-account.json y cópialo en la ruta de acceso src/main/resources del proyecto del servidor.

Cómo enviar un mensaje de prueba

En el archivo FcmSender.java, sendMessageToFcmRegistrationToken compone un mensaje de notificación con una carga útil de datos. El token de registro se orienta a la instancia de la app a la que se envía el mensaje.

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. Copia el token de registro de Android que copiaste de la sección Registro y pégalo en el valor de la variable registrationToken.
2. Haz clic en Run para ejecutar la función principal y enviar el mensaje al usuario a través de FCM.

Cuando la app para Android está en segundo plano, el mensaje aparece en la bandeja de notificaciones.

Cuando la app para Android esté en primer plano, verás un registro en la consola de Android Studio: "Handling a foreground message". El contenido del mensaje también se muestra en la IU porque esta se suscribe al controlador de transmisión para recibir mensajes nuevos.

Si pegas el token de registro y envías el mensaje desde el servidor de apps o algún otro entorno de servidor de confianza, verás un comportamiento similar:

• Cuando la app web esté en segundo plano (es decir, cuando esté oculta por otra ventana o cuando otra pestaña esté activa), verás una notificación web.

• Cuando la app web está en primer plano, puedes ver el registro en la Consola de Chrome. Para ello, haz clic con el botón derecho en la Web y selecciona Inspect. El contenido del mensaje también se muestra en la IU.

6. Cómo enviar un mensaje de tema

La función de anulación de plataforma de la API de HTTP v1 de FCM permite que una solicitud de envío de mensajes tenga diferentes comportamientos en diferentes plataformas. Un caso de uso de esta función es mostrar diferentes contenidos de mensajes de notificación según la plataforma. La función se usa más cuando se segmenta para varios dispositivos (que pueden abarcar varias plataformas) con la mensajería a temas. En esta sección, se explican los pasos para que tu app reciba un mensaje de tema personalizado para cada plataforma.

Cómo suscribirse a un tema desde el cliente

Para suscribirte a un tema, llama al método messaging.subscribeToTopic al final de la función principal en el archivo main.dart de la app de Flutter.

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

[Opcional] Suscríbete a un tema desde el servidor para la Web

Puedes omitir esta sección si no estás desarrollando en la plataforma web.

Actualmente, el SDK de FCM para JS no admite la suscripción a temas del cliente. En su lugar, puedes suscribirte con la API de administración de temas del servidor del SDK de Admin. En este código, se muestra la suscripción a temas del servidor con el SDK de Admin de 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());
 }

Abre el servidor de la app y haz clic en Run para ejecutar la función principal en el archivo FcmSubscriptionManager.java:

Envía un mensaje con anulaciones de la plataformaa un tema

Ya puedes enviar un mensaje de anulación de la plataforma de temas. En el siguiente fragmento de código:

• Creas una solicitud de envío con un mensaje base y el título "A new app is available".
• El mensaje genera una notificación visible con el título "A new app is available" en iOS y plataformas web.
• El mensaje genera una notificación visible con el título "A new Android app is available" en 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!!");
 }

En la función principal del archivo FcmSender.java, quita el comentario de sendMessageToFcmTopic();. Haz clic en Ejecutar para enviar el mensaje del tema.

7. Resumen y próximos pasos

En resumen, aprendiste a desarrollar apps multiplataforma atractivas con Flutter y FCM, lo que incluye la configuración del entorno, la integración de dependencias y el envío y la recepción de mensajes. Para obtener más información, consulta los siguientes materiales:

Codelabs

• Para obtener más información sobre cómo funciona Flutter con otros productos de Firebase, incluida la autenticación de usuarios y la sincronización de datos, consulta Descubre Firebase para Flutter.
• Para obtener más información sobre FCM, incluidos los temas y los mensajes integrados en la app, consulta Cómo usar FCM y FIAM para enviar mensajes a los usuarios y Tu primer mensaje push multicast con temas de FCM.

References

• Sitio de Firebase
• Sitio de Flutter
• Widgets de FlutterFire Firebase para Flutter
• Canal de YouTube de Firebase
• Canal de YouTube de Flutter