Esta página se ha traducido con Cloud Translation API.

Su primer mensaje push de multidifusión utilizando temas de FCM

1. Introducción

Objetivos

En este codelab, aprenderá cómo instrumentar su aplicación multiplataforma para que pueda multidifundir mensajes push a varios subgrupos de instancias de su aplicación utilizando temas de FCM.

Una vez terminado, podrá aprovechar la infraestructura de FCM para administrar estos subgrupos, así como mensajes push de multidifusión a través de los subgrupos.

Resumen de temas

Los temas son una forma compatible con la infraestructura de FCM de llegar a subgrupos de instancias de su aplicación con mensajes.

FCM proporciona las API para enviar mensajes y mantener suscripciones a estos temas. El acto de asociar y disociar una instancia de aplicación a un tema se denomina suscripción y cancelación de suscripción, respectivamente.

Los temas deben usarse para contenido disponible públicamente. Por ejemplo, mensajes sobre actualizaciones meteorológicas. Si desea enviar mensajes confidenciales para el usuario, use el SDK de administrador de Firebase para enviar mensajes de multidifusión a través de múltiples dispositivos .

La multidifusión basada en temas está optimizada para el rendimiento.

lo que aprenderás

Cómo suscribir (y cancelar la suscripción) de usuarios a temas desde una aplicación móvil.
Cómo enviar mensajes push de multidifusión utilizando temas.
Cómo enviar mensajes a una combinación de temas usando condiciones de tema.
Cómo gestionar las suscripciones a temas en el lado del servidor y realizar suscripciones y cancelaciones masivas.

lo que construirás

Una aplicación de Android que se suscribe o cancela la suscripción a temas y recibe mensajes cuando se envían a los temas.
Una integración del lado del servidor que utiliza el SDK de administración de Firebase, que se utilizará para enviar mensajes temáticos a través de las API de FCM.

Lo que necesitarás

Un navegador de tu elección, como Chrome.
IntelliJ IDEA IDE para desarrollar aplicaciones Java.
- Asegúrese de optar por la compatibilidad con Gradle durante la instalación.
Android Studio IDE para desarrollar aplicaciones de Android.
Un dispositivo para ejecutar la aplicación de Android. Cualquiera de:
- El emulador de Android. (Requiere configuración en Android Studio ).
- Un dispositivo Android físico conectado a su computadora y configurado en modo desarrollador.
Una cuenta de Google para crear y administrar su proyecto de Firebase.

2. Preparación

Obtener el código

Clona el repositorio de GitHub desde la línea de comando:

git clone https://github.com/firebase/quickstart-android.git fcm-codelab

El código de muestra se clonará en el directorio fcm-codelab .

cd fcm-codelab

La aplicación de inicio para este codelab se encuentra en el directorio messaging de la rama fcm-topics-codelab . Siga los siguientes pasos para alcanzar el código de inicio. Contiene dos directorios StockNewsApp y StockNewsServer . El primero contiene la aplicación de inicio de Android y el segundo tiene el código del lado del servidor de inicio.

git checkout fcm-topics-codelab
cd messaging/fcm-topics-codelab/starter

La versión completa de este codelab se coloca en el directorio messaging/fcm-topics-codelab/completed .

Crear un proyecto de Firebase

En Firebase console , haga clic en Agregar proyecto , asigne al proyecto de Firebase el nombre StockNews y haga clic en continuar. Nota: Recuerde el ID de proyecto de su proyecto de Firebase (o haga clic en el ícono Editar para configurar su ID de proyecto preferido).

Puede omitir la habilitación de Google Analytics. Para los fines de este codelab, no lo necesitas. Haga clic en Continuar.
Haga clic en Crear proyecto .

¡Felicidades! Acabas de crear tu proyecto de Firebase. Ahora, puede hacer clic en el nombre del proyecto para ingresar a la consola.

3. Configuración de la aplicación Firebase específica de la plataforma

La mayoría de los cambios de código necesarios para habilitar la compatibilidad con Firebase ya están registrados en el proyecto en el que estás trabajando. Sin embargo, para agregar soporte para plataformas móviles, necesita:

Registre la plataforma deseada en el proyecto Firebase
Descargue el archivo de configuración específico de la plataforma y agréguelo al código.

Para los propósitos de este codelab, agregaremos una aplicación Firebase de Android.

Configurar Android

En Firebase Console , seleccione Configuración del proyecto en la parte superior de la barra de navegación izquierda en el engranaje de Configuración y haga clic en el ícono de Android en Sus aplicaciones en la página General .

Deberías ver el siguiente cuadro de diálogo:

El valor importante a proporcionar es el nombre del paquete de Android . Configúrelo en com.ticker.stocknews .
1. El nombre del paquete proporcionado aquí debe ser el mismo que el proporcionado en AndroidManifest.xml de su código inicial de StockNewsApp . Si desea localizarlo o cambiarlo, siga estos pasos:
  1. En el directorio StockNewsApp , abra el archivo app/src/main/AndroidManifest.xml .
  2. En el elemento manifest , busque el valor de cadena del atributo package . Este valor es el nombre del paquete de Android.

En el cuadro de diálogo de Firebase, pegue el nombre del paquete copiado en el campo de nombre del paquete de Android .
No necesitas el certificado de firma de depuración SHA-1 para este codelab, porque esta aplicación no se lanzará. Deje esto en blanco.
Haga clic en Registrar aplicación .
Continuando en Firebase Console, siga las instrucciones para descargar el archivo de configuración google-services.json .
Puede omitir los pasos de configuración restantes, ya que todo lo demás ya está configurado en el código de la aplicación de inicio. Encontrará su aplicación en la página principal de Firebase Console.
Copie el archivo google-services.json (que acaba de descargar) al directorio messaging/fcm-topics-codelab/starter/StockNewsApp/app .

4. Crea y ejecuta tu aplicación

¡Estás listo para comenzar a trabajar en tu aplicación! Primero, cree y ejecute la aplicación.

Importar la aplicación de inicio

Inicie Android Studio e importe messaging/fcm-topics-codelab/starter/StockNewsApp desde el directorio del código de inicio.

Después de que el proyecto se haya cargado, es posible que también veas una alerta de que Git no está rastreando todos tus cambios locales. Puedes hacer clic en " Ignorar " o en la " X " en la esquina superior derecha. (No enviarás ningún cambio al repositorio de Git).

En la esquina superior izquierda de la ventana del proyecto, debería ver algo como la imagen a continuación si está en la vista de Android . (Si estás en la vista Proyecto , necesitarás expandir el proyecto para ver lo mismo)

Tenga en cuenta que Android Studio puede tardar varios segundos en compilar el proyecto en segundo plano por primera vez. Durante este tiempo verás una rueda giratoria en la barra de estado en la parte inferior de Android Studio:

Le recomendamos que espere hasta que esto haya terminado antes de realizar cambios en el código. Esto permitirá que Android Studio incorpore todos los componentes necesarios.

Además, si recibe un mensaje que dice "¿Recargar para que los cambios de idioma surtan efecto?" o algo similar, seleccione "Sí".

Configuración del emulador

Si necesita ayuda para configurar un emulador de Android, consulte el artículo Ejecute su aplicación .

Comprender el código de inicio de la aplicación de Android

El código de inicio es una aplicación de Android liviana con funcionalidad e interfaz de usuario mínimas.
Ya se agregó una dependencia del SDK de mensajería de Firebase al archivo app/build.gradle .

En AndroidManifest.xml , ya se agregó un controlador de devolución de llamada MESSAGING_EVENT .
- Este controlador, StockNewsMessagingService.java , extiende la clase FirebaseMessagingService que proporciona varias funciones relacionadas con Firebase Cloud Messaging. Consulte la documentación de FirebaseMessagingService para obtener más información.
- La función onNewToken se llama cuando se crea o actualiza el token de registro de FCM. Consulte Supervisar la generación de tokens para obtener más información.
- La función onMessageReceived se llama cuando se recibe un mensaje y la aplicación está en primer plano. Actualmente, simplemente registra el mensaje recibido.
  - Consulte Recibir mensajes en una aplicación de Android para obtener más información sobre las diferencias entre la entrega y el manejo de mensajes en segundo plano y en primer plano.
Además, en AndroidManifest.xml , también se proporciona una clase Application de Android denominada StockNewsApplication .
- Esta clase será la primera de la que se creará una instancia cuando se inicie la aplicación.
- En la función onCreate de la clase StockNewsApplication , se agrega una llamada de creación de token de registro FCM. Generará un token de registro FCM válido y lo registrará.
MainActivity.java agrega RecyclerView que muestra las opciones de categoría de stock.
SubscriptionAdapter.java implementa RecyclerView.Adapter que dibuja la pantalla de selección de categoría de acciones.
- Cada categoría de acciones tiene un nombre y un botón de suscripción al lado.
- Cambiar la palanca debería generar una llamada de suscripción/cancelación de suscripción a un tema de FCM.
- Implementarás estas convocatorias en las próximas secciones.
La clase model/StockCategories.java contiene una lista de todas las categorías de acciones y sus nombres de temas asociados.

Ejecute la aplicación de inicio

Conecte su dispositivo Android a su computadora o inicie un emulador.
En la barra de herramientas superior, seleccione su dispositivo o emulador Android de destino y presione el botón Ejecutar.

La interfaz de usuario de la aplicación tendrá el siguiente aspecto:

La aplicación creará un token de registro FCM y lo registrará. Sin embargo, nada cambiará en la interfaz de usuario de la aplicación.
1. Copie y guarde el token de registro de FCM, ya que se utilizará en los próximos pasos.

5. Enviar un mensaje de prueba

Ahora está listo para enviar un mensaje de prueba a la instancia de la aplicación que configuró en el último paso.

Importar el código del servidor de inicio

Inicie IntelliJ IDEA y abra el proyecto messaging/fcm-topics-codelab/starter/StockNewsServer .

La vista del proyecto en la barra de navegación izquierda debería verse así:

Tenga en cuenta que Intellij IDEA puede tardar unos minutos en crear su proyecto, incluida la extracción de las dependencias necesarias.

Comprender el código de inicio del servidor

El código de inicio del servidor es un proyecto Java basado en Gradle.
El archivo build.gradle ya tiene agregada la dependencia del SDK de firebase-admin . Este SDK proporciona acceso a varias funcionalidades de envío de mensajes de FCM.

Finalmente, hay dos clases, a saber:
- FcmSender.java : esta clase contiene los siguientes métodos destacados:
  - initFirebaseSDK : Inicializa el SDK de firebase-admin.
  - sendMessageToFcmRegistrationToken : envía un mensaje a un token de registro de FCM.
  - sendMessageToFcmTopic : envía un mensaje a un tema de FCM.
  - sendMessageToFcmTopicCondition : envía un mensaje a una condición de tema de FCM.
- FcmSubscriptionManager.java : esta clase contiene métodos que permiten gestionar suscripciones a temas desde el lado del servidor.
  - initFirebaseSDK : Inicializa el SDK de firebase-admin.
  - subscribeFcmRegistrationTokensToTopic : suscribe tokens de registro de FCM a un tema de FCM.
  - unsubscribeFcmRegistrationTokensFromTopic : cancelar la suscripción de tokens de registro de FCM de un tema de FCM.

Configurar el código del servidor

Primero, necesitamos configurar una cuenta de servicio de Firebase que permita que el SDK de administrador de Firebase autorice llamadas a las API de FCM.
1. Vaya a Firebase Console, haga clic en el ícono de ajustes junto a Descripción general del proyecto en la barra de navegación izquierda y seleccione Configuración del proyecto .
2. En la página de configuración, seleccione Cuentas de servicio y haga clic en Crear cuenta de servicio .
3. Ahora haga clic en el botón Generar nueva clave privada y comenzará una descarga automática de su archivo de clave.
4. Cambie el nombre del archivo de clave a service-account.json y cópielo en la carpeta messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources .
5. Tanto FcmSender.java como FcmSubscriptionManager.java cargan el archivo service-account.json desde classpath usando el siguiente código.
En este punto, el código del servidor está listo. Ejecute Build -> Build Project desde la barra de menú superior.

Enviar un mensaje de prueba

En FcmSender.java busque la función sendMessageToFcmRegistrationToken e inserte el token de registro FCM que copió de la sección Ejecutar la aplicación de inicio en el campo registrationToken .
En la función main , descomente solo la función sendMessageToFcmRegistrationToken y haga clic en ejecutar para ejecutar el código.
1. Observe cómo el token de registro de FCM se configura en el campo Token del objeto message .
2. Además, observe cómo hemos utilizado la API de send de la interfaz FirebaseMessaging .

Esto debería enviar un mensaje a la instancia de la aplicación que configuró en el paso anterior.
Cuando la instancia de la aplicación está en primer plano, debería ver el contenido del mensaje registrado.

Y cuando la instancia de la aplicación esté en segundo plano, observará que aparece el mensaje en la bandeja de notificaciones.

Genial, usaste Firebase Admin SDK para enviar mensajes a una instancia de aplicación. Lea más sobre el uso del SDK de Firebase Admin en su servidor .

6. Implementar suscripción/cancelación de suscripción a temas

En este paso, implementará acciones de suscripción y cancelación de suscripción a temas en el interruptor Categoría de acciones de la aplicación de Android.

Cuando un usuario de la aplicación activa el interruptor para una categoría de acciones en particular, se realizará una llamada de suscripción o cancelación de suscripción a un tema.

Revisar código

Navegue hasta la clase SubscriptionAdapter.java en el código de la aplicación de Android y busque la clase RecyclerViewViewHolder .

El constructor de la clase configura un detector para alternar la suscripción mediante setOnCheckedChangeListener .
Dependiendo del interruptor, las acciones de suscripción y cancelación de suscripción se realizan llamando a los métodos subscribeToStockCategory y unsubscribeFromStockCategory respectivamente.
El método setData es llamado por onBindViewHolder del adaptador RecyclerView para vincular ViewHolder con la categoría de stock adecuada.

Implementar suscripción a temas

En el método subscribeToStockCategory , implementará la llamada a la API subscribeToTopic del objeto FirebaseMessaging . El código podría verse así:

   void subscribeToStockCategory() {
      // Making call to FCM for subscribing to the topic for stockCategory
     FirebaseMessaging.getInstance().subscribeToTopic(stockCategory.getTopicName()).addOnSuccessListener(
          unused -> {
            // Subscribing action successful
            Log.i(TAG, "Subscribed to topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Subscribed to " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

Implementar cancelación de suscripción a temas

De manera similar, en la condición else, implementará la llamada para unsubscribeFromTopic a la API FromTopic. Algo parecido a lo siguiente:

void unsubscribeFromStockCategory() {
      // Making call to FCM for unsubscribing from the topic for stockCategory
      FirebaseMessaging.getInstance().unsubscribeFromTopic(stockCategory.getTopicName())
          .addOnSuccessListener(unused -> {
            // Unsubscribing action successful
            Log.i(TAG, "Unsubscribed from topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Unsubscribed from " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

Probemoslo

Ejecute la aplicación y alterne las opciones de Categoría de acciones para ejecutar acciones de suscripción y cancelación de suscripción. Se vería algo como esto:

Suscribir	Darse de baja

7. Envío de su primer mensaje temático

En este paso, implementará el código del lado del servidor para enviar un mensaje de tema de FCM.

Implementar la integración del lado del servidor para enviar mensajes temáticos.

En el código del servidor, salte a FcmSender.java y busque el método denominado sendMessageToFcmTopic .

En la primera línea, proporcione el tema de FCM al que desea enviar el mensaje.
- Es una cadena de la forma: /topics/<Topic Name> . Por ejemplo, /topics/Technology .
En las siguientes líneas cree un nuevo objeto message (similar al definido en la función sendMessageToFcmRegistrationToken ).
- La diferencia será que en lugar de configurar el campo Token del objeto message , configurará el campo Topic .

Message message = Message.builder()
        .putData("FOOTECH", "$1000")
        .setNotification(
            Notification.builder()
                .setTitle("Investor confidence in Tech Stocks growing")
                .setBody("Foo Tech leading the way in stock growth for Tech sector.")
                .build())
        .setTopic(topicName)
        .build();

Ahora agregue la llamada a la instancia FirebaseMessaging para enviar el mensaje (idéntica a la llamada de envío realizada en la función sendMessageToFcmRegistrationToken ).

FirebaseMessaging.getInstance().send(message);

Finalmente, actualice la función main y habilite la llamada solo a la función sendMessageToFcmTopic .

Enviar mensaje y validar recibo

Antes de enviar el mensaje del tema, primero asegúrese de que la instancia de su aplicación esté suscrita al tema al que desea enviar.
1. Esto se puede hacer girando el interruptor correspondiente. Por ejemplo:
Ahora puede enviar su mensaje de tema ejecutando la función main de FcmSender.java .
Como antes, debería poder observar la recepción del mensaje en la instancia de la aplicación.
1. Instancia de aplicación en primer plano
1. Instancia de aplicación en segundo plano
Bonificación: intente cancelar la suscripción al tema que envió y vuelva a enviar el mensaje. Observará que el mensaje no se entrega a la instancia de la aplicación.

8. Envío de su primer mensaje de condición de tema

La función de condición del tema le permite enviar mensajes a una combinación de temas, lo que le permite proporcionar una definición de audiencia más expresiva.

Por ejemplo, en nuestra App StockNews, considere la posibilidad de enviar mensajes a un grupo de instancias de la aplicación que estén suscritas a temas de Tecnología o Automotriz. Un caso así puede ocurrir, por ejemplo, si hay un evento digno de mención que involucra a Waymo.

Temas le permite expresar su combinación en forma de expresión booleana utilizando los siguientes operadores

&& : Y lógico. Por ejemplo, 'Technology' in topics && 'Automotive' in topics : se dirige solo a las instancias de aplicaciones que están suscritas a Temas de tecnología y automoción.
|| : O lógico. Por ejemplo, 'Technology' in topics || 'Automotive' in topics : apunta a instancias de aplicaciones que están suscritas a temas de Tecnología o Automoción.
() : Paréntesis para agrupación. Por ejemplo, 'Technology' in topics && ('Automotive' in topics || 'Energy' in topics) : se dirige solo a instancias de aplicaciones que están suscritas a Tecnología y a temas de Automoción o Energía.

Lea más sobre cómo crear solicitudes de envío para usar esta funcionalidad.

Implementar la integración del lado del servidor para enviar mensajes de condición del tema

De vuelta en el código del servidor, salte a FcmSender.java y busque el método denominado sendMessageToFcmTopicCondition .

En la primera línea, para la variable topicCondition , proporcione la condición del tema al que desea enviar el mensaje. Puede configurarlo en: 'Technology' in topics && 'Automotive' in topics .
En las siguientes líneas, cree un nuevo objeto message (similar al definido en la función sendMessageToFcmTopic ).
1. La diferencia será que en lugar de configurar el campo Topic del objeto, configurará el campo Condition .

    Message message = Message.builder()
        .putData("FOOCAR", "$500")
        .setNotification(
            Notification.builder()
                .setTitle("Foo Car shows strong Q2 results")
                .setBody("Foo Car crosses 1B miles. Stocks rally.")
                .build())
        .setCondition(topicCondition)
        .build();

Ahora agregue la llamada a la instancia FirebaseMessaging para enviar el mensaje (idéntica a la llamada de envío realizada en la función sendMessageToFcmTopic ).

FirebaseMessaging.getInstance().send(message);

Finalmente, actualice la función main y habilite la llamada solo a la función sendMessageToFcmTopicCondition .

Enviar el mensaje y validar recibo

Antes de enviar el mensaje de tema, primero asegúrese de que la instancia de su aplicación cumpla con la condición de tema especificada suscribiendo la instancia de la aplicación a temas de Tecnología y Automoción.
Ahora puede enviar su mensaje de tema ejecutando la función main de FcmSender.java .
Como antes, debería poder observar la recepción del mensaje en la instancia de la aplicación.
1. Instancia de aplicación en primer plano
1. Instancia de aplicación en segundo plano
Bonificación: ahora puede darse de baja del tema Tecnología y reenviar el mensaje de condición del tema. Debe observar que la instancia de la aplicación no recibe el mensaje.

9. Resumen

Hagamos un breve resumen de lo que ha aprendido hasta este punto.

Cómo iniciar una suscripción/cancelación de suscripción a un tema desde una instancia de aplicación.
Enviar un mensaje al tema y verificar la recepción de instancias de aplicaciones suscritas.
Enviar un mensaje a una condición del tema y verificar la recepción en una instancia de aplicación que cumple la condición.

En la siguiente sección, aprenderá cómo puede suscribirse o cancelar la suscripción de instancias de aplicaciones a temas sin necesidad de crear instancias de llamadas desde el lado del cliente.

10. Administrar las suscripciones a temas desde el lado del servidor

Hasta ahora, en este codelab, todas las llamadas de suscripción y cancelación de suscripción a temas se inician desde una instancia de aplicación.

Sin embargo, en algunos casos de uso, es posible que desee administrar las suscripciones a temas desde el lado del servidor. Por ejemplo, es posible que desee suscribir un subgrupo de su base de usuarios existente a un tema nuevo sin esperar el lanzamiento de la aplicación.

En esta sección, aprenderá cómo usar el SDK de Firebase Admin para suscribir y cancelar la suscripción de un lote de tokens de registro de FCM a un tema mediante llamadas desde el lado del servidor.

Implementar la suscripción del lado del servidor de tokens de registro de FCM al tema de FCM

En el código del servidor, salte a la clase FcmSubscriptionManager.java . Localice el método denominado subscribeFcmRegistrationTokensToTopic . Implementará la llamada a la API subscribeToTopic aquí.

Suscribamos la instancia de la aplicación al tema Energía. Para ello, en primer lugar proporcione datos para los dos campos siguientes:
1. registrationTokens : una lista separada por comas de cadenas que representan los tokens de registro de FCM para los que desea crear suscripciones a temas.
2. topicName : el nombre del tema Energía, es decir /topics/Energy .
En las próximas líneas implemente la llamada, de la siguiente manera:

TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
        registrationTokens, topicName);

Puede inspeccionar TopicManagementResponse para ver algunas estadísticas de resultados de alto nivel. Como imprimir la cantidad de suscripciones a temas creados exitosamente usando getSuccessCount .

System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());

Finalmente, en la función main habilite las llamadas solo a la función subscribeFcmRegistrationTokensToTopic .

Crear suscripción y enviar mensaje de tema.

En este punto, está listo para crear la suscripción al tema y enviarle un mensaje.
Ejecute la función main de la clase FcmSubscriptionManager.java . Esto creará una suscripción al tema.
Ahora, configure el código para enviar el mensaje. Similar a antes,
1. En FcmSender.java , busque la función sendMessageToFcmTopic .
2. Establezca el topicName en el tema Energía, es decir, /topics/Energy .
3. Cree un objeto Message y oriéntelo al tema usando setTopic .
4. Finalmente, actualice el método main para habilitar solo la función sendMessageToFcmTopic .
Ejecute la función main de FcmSender.java . Esto enviará el mensaje a la instancia de su aplicación y podrá observarlo en su aplicación de la siguiente manera.
1. Instancia de aplicación en primer plano
1. Instancia de aplicación en segundo plano

Implementar la cancelación de la suscripción del lado del servidor de los tokens de registro de FCM al tema de FCM

Para cancelar suscripciones a temas del lado del servidor, utilice esta API unsubscribeFromTopic . Agregará el código relevante para unsubscribeFcmRegistrationTokensFromTopic a la función FcmRegistrationTokensFromTopic de la clase FcmSubscriptionManager.java .

La implementación del código de cancelación de suscripción del lado del servidor y la validación de su efecto mediante el envío de un mensaje temático se deja como ejercicio para usted.

11. Felicitaciones

Felicitaciones, ha utilizado con éxito temas de FCM para enviar mensajes de multidifusión a subgrupos de las instancias de su aplicación. Esto ayudará a simplificar su capacidad de llegar oportunamente a sus usuarios con contenido relevante.

¿Que sigue?

Ahora que has completado tu codelab, considera probar temas para otras plataformas usando las siguientes guías:

Documentos de referencia

Referencia de la API de Android ( Java / Kotlin )
Referencia de la API de iOS ( ObjetiveC / Swift )
Referencia de la API de Javascript ( versión 9 / versión 8 )
Referencia del SDK de administrador ( Node.js / Java / Python / .NET )