1. Introducción
Objetivos
En este codelab, aprenderás a instrumentar tu app multiplataforma para que puedas realizar la multidifusión de mensajes push a varios subgrupos de las instancias de tu app usando temas de FCM.
Cuando termines, podrás aprovechar la infraestructura de FCM para administrar estos subgrupos, así como los mensajes push multicast en los subgrupos.
Descripción general de los temas
Los temas son una forma compatible con la infraestructura de FCM de llegar a subgrupos de las instancias de tu app con mensajes.
FCM proporciona las API para enviar mensajes y mantener suscripciones a estos temas. El acto de asociar y desvincular una instancia de app a un tema se denomina suscripción y anulación de la suscripción, respectivamente.
Los temas deben usarse para el contenido disponible públicamente. Por ejemplo, mensajes sobre actualizaciones del clima. Si quieres enviar mensajes sensibles al usuario, usa el SDK de Firebase Admin para multicastear mensajes en varios dispositivos.
La transmisión multicast basada en temas está optimizada para la capacidad de procesamiento.
Qué aprenderás
- Cómo suscribir (y anular la suscripción) a los usuarios a temas desde una app para dispositivos móviles
- Cómo enviar mensajes push de multidifusión con temas
- Cómo enviar mensajes a una combinación de temas con las condiciones de tema
- Cómo administrar suscripciones a temas en el servidor y realizar suscripciones y anulaciones de suscripciones de forma masiva
Qué compilarás
- Una app para Android que suscribe o anula la suscripción a temas y recibe mensajes cuando se envían a los temas.
- Una integración en el servidor con el SDK de Firebase Admin, que se usará para enviar mensajes por temas a través de las APIs de FCM
Requisitos
- El navegador que elijas, como Chrome.
- IDE de IntelliJ IDEA para desarrollar aplicaciones de Java.
- Asegúrate de habilitar la compatibilidad con Gradle durante la instalación.
- IDE Android Studio para desarrollar aplicaciones para Android
- Un dispositivo para ejecutar la aplicación para Android Cualquiera de los siguientes:
- Android Emulator (Requiere configuración en Android Studio).
- Un dispositivo Android físico conectado a tu computadora y configurado en modo de desarrollador
- Una Cuenta de Google para crear y administrar tu proyecto de Firebase
2. Cómo prepararte
Obtén el código
Clona el repositorio de GitHub a partir de la línea de comandos:
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 app de partida de este codelab se encuentra en el directorio messaging
de la rama fcm-topics-codelab
. Sigue estos pasos para acceder al código de partida. Contiene dos directorios: StockNewsApp
y StockNewsServer
. El primero contiene la app para Android de partida y el segundo tiene el código del servidor de partida.
git checkout fcm-topics-codelab cd messaging/fcm-topics-codelab/starter
La versión completa de este codelab se ubica en el directorio messaging/fcm-topics-codelab/completed
.
Crea un proyecto de Firebase
- En Firebase console, haz clic en Agregar proyecto, asígnale el nombre StockNews al proyecto y haz clic en Continuar. Nota: Recuerda el ID del proyecto de Firebase (o haz clic en el ícono Editar para establecer el ID del proyecto que prefieras).
- Puedes omitir la habilitación de Google Analytics. Para los fines de este codelab, no lo necesitas. Haz clic en Continuar.
- Haz clic en Crear proyecto.
¡Felicitaciones! Acabas de crear tu proyecto de Firebase. Ahora, puedes hacer clic en el nombre del proyecto para ingresar a la consola.
3. Configuración de la app de Firebase específica para cada plataforma
La mayoría de los cambios de código que se necesitan para habilitar la compatibilidad con Firebase ya están registrados en el proyecto en el que estás trabajando. Sin embargo, para agregar compatibilidad con las plataformas móviles, debes hacer lo siguiente:
- Registra la plataforma deseada en el proyecto de Firebase
- Descarga el archivo de configuración específico de la plataforma y agrégalo al código.
A los fines de este codelab, agregaremos una app de Firebase para Android.
Cómo configurar Android
- En Firebase console, selecciona Configuración del proyecto en la parte superior de la barra de navegación izquierda del engranaje de configuración y haz clic en el ícono de Android en Tus apps en la página General.
Deberías ver el siguiente diálogo:
- El valor importante que se debe proporcionar es el nombre del paquete de Android. Establécelo en
com.ticker.stocknews
.- El nombre de paquete que se proporciona aquí debe ser el mismo que se proporciona en el
AndroidManifest.xml
del código de inicio de StockNewsApp. Si deseas localizarlo o cambiarlo, sigue estos pasos:- En el directorio StockNewsApp, abre el archivo
app/src/main/AndroidManifest.xml
. - En el elemento
manifest
, busca el valor de cadena del atributopackage
. Este valor es el nombre del paquete de Android.
- En el directorio StockNewsApp, abre el archivo
- El nombre de paquete que se proporciona aquí debe ser el mismo que se proporciona en el
- En el diálogo de Firebase, pega el nombre del paquete que copiaste en el campo Nombre del paquete de Android.
- No necesitas el certificado de firma SHA-1 de depuración para este codelab, ya que no se lanzará esta app. Deja este campo en blanco.
- Haga clic en Registrar app.
- En Firebase console, sigue las instrucciones para descargar el archivo de configuración
google-services.json
. - Puedes omitir los pasos de configuración restantes, dado que todo lo demás ya está configurado en el código de la app de partida. Encontrarás tu app en la página principal de Firebase console.
- Copia el archivo
google-services.json
(que acabas de descargar) en el directoriomessaging/fcm-topics-codelab/starter/StockNewsApp/app
.
4. Compila y ejecuta tu app
Está todo listo para que comiences a trabajar en tu app. Primero, compila y ejecuta la app.
Importa la app de partida
Inicia Android Studio e importa el archivo messaging/fcm-topics-codelab/starter/StockNewsApp
desde el directorio del código de partida.
Luego de que se cargue el proyecto, es posible que veas una alerta que indique que Git no está realizando un seguimiento de todos los cambios locales. Puedes hacer clic en Ignorar. o la "X" arriba a la derecha. (No enviarás ningún cambio al repositorio de Git).
En la esquina superior izquierda de la ventana del proyecto, deberías ver una imagen similar a la que se muestra más abajo si estás en la vista Android. (Si estás en la vista Project, deberás expandir el proyecto para ver lo mismo).
Ten en cuenta que Android Studio puede tardar varios segundos la primera vez que compile el proyecto en segundo plano. Durante este tiempo, verás un ícono giratorio en la barra de estado de la parte inferior de Android Studio:
Te recomendamos que esperes hasta que termine antes de realizar cambios en el código. De esta manera, Android Studio podrá extraer todos los componentes necesarios.
Además, si recibes un mensaje que dice “Volver a cargar para que se apliquen los cambios de idioma?” o algo similar, selecciona "Sí".
Configuración del emulador
Si necesitas ayuda para configurar un emulador de Android, consulta el artículo Cómo ejecutar tu app.
Comprende el código de partida de la app para Android
- El código de partida es una app para Android ligera con IU y funcionalidad mínimas.
- Ya se agregó una dependencia al SDK de firebase-messaging en el archivo
app/build.gradle
.
- En
AndroidManifest.xml
, ya se agregó un controlador de devolución de llamadaMESSAGING_EVENT
.- Este controlador,
StockNewsMessagingService.java
, extiende la claseFirebaseMessagingService
, que proporciona varias funciones relacionadas con Firebase Cloud Messaging. Consulta la documentación de FirebaseMessagingService para obtener más información.
- Se llama a la función
onNewToken
cuando se crea o se actualiza el token de registro de FCM. Consulta Supervisa la generación de tokens para obtener más información. - Se llama a la función
onMessageReceived
cuando se recibe un mensaje y la app se encuentra en primer plano. Actualmente, solo registra el mensaje recibido.- Consulta Cómo recibir mensajes en una app para Android para obtener más información sobre las diferencias entre la entrega y el manejo de mensajes en primer y segundo plano.
- Este controlador,
- Además, en
AndroidManifest.xml
, también se proporciona una claseApplication
de Android llamadaStockNewsApplication
.- Esta clase será la primera en crearse cuando se inicie la app.
- En la función
onCreate
de la claseStockNewsApplication
, se agrega una llamada a la creación de un token de registro de FCM. Se generará un token de registro de FCM válido y se registrará.
- El elemento
MainActivity.java
agrega elRecyclerView
que muestra las opciones de categoría de acciones. SubscriptionAdapter.java
implementaRecyclerView.Adapter
, que dibuja la pantalla de selección de categorías de acciones.- Cada categoría de acciones tiene un nombre y un botón de activación de suscripción junto a ella.
- Si cambias el botón de activación, se debería realizar una llamada a FCM para suscribirse a un tema o anular la suscripción.
- Implementarás estas llamadas en las próximas secciones.
- La clase
model/StockCategories.java
contiene una lista de todas las categorías de acciones y los nombres de temas asociados.
Ejecuta la app de partida
- Conecta tu dispositivo Android a la computadora o inicia un emulador.
- En la barra de herramientas superior, selecciona el dispositivo Android o emulador de destino y presiona el botón de ejecución.
- La IU de la app se verá de la siguiente manera:
- La app creará un token de registro de FCM y lo registrará. Sin embargo, no cambiará nada en la IU de la app.
- Copia y guarda el token de registro de FCM, ya que se usará en los próximos pasos.
5. Envía un mensaje de prueba
Ya puedes enviar un mensaje de prueba a la instancia de la app que configuraste en el último paso.
Importa el código del servidor de partida
Inicia IntelliJ IDEA y abre el proyecto messaging/fcm-topics-codelab/starter/StockNewsServer
.
La vista Project en la barra de navegación izquierda debería verse de la siguiente manera:
Ten en cuenta que IntellIj IDEA puede tardar unos minutos en compilar tu proyecto, lo que incluye extraer las dependencias necesarias.
Comprende el código de partida del servidor
- El código de partida del servidor es un proyecto de Java basado en Gradle.
- El archivo
build.gradle
ya tiene la dependencia del SDK de firebase-admin que se le agregó. Este SDK proporciona acceso a varias funciones de envío de mensajes de FCM.
- Por último, hay dos clases:
FcmSender.java
: Esta clase contiene los siguientes métodos importantes: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 administrar suscripciones a temas desde el servidor.initFirebaseSDK
: Inicializa el SDK de firebase-admin.subscribeFcmRegistrationTokensToTopic
: Suscribe los tokens de registro de FCM a un tema de FCM.unsubscribeFcmRegistrationTokensFromTopic
: Anula la suscripción de los tokens de registro de FCM de un tema de FCM.
Configura el código del servidor
- En primer lugar, debemos configurar una cuenta de servicio de Firebase que permita que el SDK de firebase-admin autorice las llamadas a las API de FCM.
- Ve a Firebase console, haz clic en el ícono de ajustes junto a Descripción general del proyecto en la barra de navegación izquierda y selecciona Configuración del proyecto.
- En la página de configuración, selecciona Cuentas de servicio y haz clic en Crear cuenta de servicio.
- Ahora haz clic en el botón Generar nueva clave privada y comenzará una descarga automática de tu archivo de claves.
- Cambia el nombre del archivo de clave a
service-account.json
y cópialo en la carpetamessaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources
. - Tanto
FcmSender.java
comoFcmSubscriptionManager.java
cargan el archivoservice-account.json
desde el classpath con el siguiente código.
- En este punto, el código del servidor está listo. Ejecuta Build -> Build Project desde la barra de menú superior.
Cómo enviar un mensaje de prueba
- En
FcmSender.java
, busca la funciónsendMessageToFcmRegistrationToken
y, luego, inserta el token de registro de FCM que copiaste de la sección Ejecuta la app de partida en el camporegistrationToken
. - En la función
main
, quita el comentario solo de la funciónsendMessageToFcmRegistrationToken
y haz clic en Ejecutar para ejecutar el código.- Observa cómo el token de registro de FCM se establece en el campo
Token
del objetomessage
. - Además, observa cómo usamos la API de
send
de la interfazFirebaseMessaging
.
- Observa cómo el token de registro de FCM se establece en el campo
- Esto debería enviar un mensaje a la instancia de la app que configuraste en el paso anterior.
- Cuando la instancia de la app esté en primer plano, deberías ver el contenido del mensaje registrado.
- Y cuando la instancia de la app esté en segundo plano, verás que el mensaje aparece en la bandeja de notificaciones.
Genial. Usaste el SDK de Firebase Admin para enviar mensajes a una instancia de la app. Obtén más información para usar el SDK de Firebase Admin en tu servidor.
6. Implementa la suscripción o anulación de suscripción a temas
En este paso, implementarás acciones de suscripción a temas y anulación de suscripción en el botón de activación de categoría de acciones de la app para Android.
Cuando el usuario de una aplicación activa el interruptor para una categoría de acciones en particular, se realiza una llamada para suscribirse a un tema o para anularla.
Revisa el código
- Navega a la clase
SubscriptionAdapter.java
en el código de la app para Android y busca la claseRecyclerViewViewHolder
.
- El constructor de clase configura un objeto de escucha para activar o desactivar la suscripción con
setOnCheckedChangeListener
. - Según el botón de activación, las acciones de suscripción y anulación de suscripción se realizan llamando a los métodos
subscribeToStockCategory
yunsubscribeFromStockCategory
, respectivamente. - El
onBindViewHolder
del adaptador de RecyclerView llama al métodosetData
para vincular ViewHolder con la categoría de stock adecuada.
Implementa la suscripción al tema
- En el método
subscribeToStockCategory
, implementarás la llamada a la API desubscribeToTopic
del objetoFirebaseMessaging
. El código podría verse de la siguiente manera:
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(); }); }
Implementa la anulación de la suscripción al tema
- De manera similar, en la condición else, implementarás la llamada a la API de
unsubscribeFromTopic
. Algo como 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(); }); }
Probemos
- Ejecuta la app y activa o desactiva las opciones de la categoría de acciones para ejecutar las acciones de suscripción y anulación de la suscripción. Se vería algo así:
Suscribirse | Anular la suscripción |
7. Cómo enviar tu primer mensaje de tema
En este paso, implementarás código del servidor para enviar un mensaje por tema de FCM.
Implementa la integración del servidor para enviar mensajes de temas
- En el código del servidor, ve a
FcmSender.java
y busca el método llamadosendMessageToFcmTopic
.
- En la primera línea, ingresa el tema de FCM al que quieres enviar el mensaje.
- Es una cadena del siguiente formato:
/topics/<Topic Name>
. Por ejemplo,/topics/Technology
- Es una cadena del siguiente formato:
- En las siguientes líneas, crea un nuevo objeto
message
(similar al que se definió en la funciónsendMessageToFcmRegistrationToken
).- La diferencia será que, en lugar de establecer el campo
Token
del objetomessage
, establecerás el campoTopic
.
- La diferencia será que, en lugar de establecer el campo
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, agrega la llamada a la instancia
FirebaseMessaging
para enviar el mensaje (idéntico a la llamada de envío realizada en la funciónsendMessageToFcmRegistrationToken
).
FirebaseMessaging.getInstance().send(message);
- Por último, actualiza la función
main
y habilita la llamada solo a la funciónsendMessageToFcmTopic
.
Enviar mensaje y validar la confirmación
- Antes de enviar el mensaje a tema, primero asegúrate de que tu instancia de app esté suscrita al tema al que deseas enviar.
- Esto se puede hacer con un giro del botón de activación correspondiente. Por ejemplo:
- Ahora puedes enviar tu mensaje de tema ejecutando la función
main
deFcmSender.java
. - Al igual que antes, deberías poder ver la recepción del mensaje en la instancia de la app.
- Instancia de la app en primer plano
- Instancia de la app en segundo plano
- Actividad adicional: Intenta anular la suscripción al tema al que enviaste el mensaje y volver a enviar el mensaje. Notarás que el mensaje no se entrega a la instancia de la app.
8. Envía tu primer mensaje de condición del tema
La función de condición de tema te permite enviar mensajes a una combinación de temas, lo que te permite proporcionar una definición de público más expresiva.
Por ejemplo, en la app de StockNews, considera la posibilidad de enviar mensajes a un grupo de instancias de apps que estén suscritos a temas de Tecnología o Industria automotriz. Ese caso puede ocurrir, por ejemplo, si hay un evento importante que involucre a Waymo.
Topics te permite expresar tu combinación en forma de una expresión booleana con los siguientes operadores:
- & : Lógico AND. Por ejemplo,
'Technology' in topics && 'Automotive' in topics
: Se orienta solo a las instancias de la app que están suscritas a los temas de tecnología y Automotive. - || : O lógico. Por ejemplo,
'Technology' in topics || 'Automotive' in topics
: Se segmenta para instancias de app que se suscriben a los temas Tecnología o Automotriz. - () : Paréntesis para agrupar. Por ejemplo,
'Technology' in topics && ('Automotive' in topics || 'Energy' in topics)
: Se orienta solo a las instancias de la app suscritas a los temas Tecnología y Industria automotriz o Energía.
Obtén más información sobre cómo crear solicitudes de envío para usar esta función.
Implementa la integración del servidor para enviar mensajes de condición de tema
- Regresa al código del servidor, ve a
FcmSender.java
y ubica el método llamadosendMessageToFcmTopicCondition
.
- En la primera línea, para la variable
topicCondition
, proporciona la condición del tema a la que deseas enviar el mensaje. Puedes establecerlo en:'Technology' in topics && 'Automotive' in topics
. - En las siguientes líneas, crea un nuevo objeto
message
(similar al que se definió en la funciónsendMessageToFcmTopic
).- La diferencia será que, en lugar de establecer el campo
Topic
del objeto, establecerás el campoCondition
.
- La diferencia será que, en lugar de establecer el campo
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, agrega la llamada a la instancia
FirebaseMessaging
para enviar el mensaje (idéntico a la llamada de envío realizada en la funciónsendMessageToFcmTopic
).
FirebaseMessaging.getInstance().send(message);
- Por último, actualiza la función
main
y habilita la llamada solo a la funciónsendMessageToFcmTopicCondition
.
Envía el mensaje y valida la recepción
- Antes de enviar el mensaje del tema, asegúrate de que la instancia de tu app cumpla con la condición del tema especificada. Para ello, suscríbete la instancia de la app a los temas de Tecnología y Industria automotriz.
- Ahora puedes enviar tu mensaje a tema ejecutando la función
main
deFcmSender.java
. - Al igual que antes, deberías poder ver la recepción del mensaje en la instancia de la app.
- Instancia de la app en primer plano
- Instancia de la app en segundo plano
- Contenido adicional: Ahora puedes anular la suscripción al tema Tecnología y volver a enviar el mensaje de condición del tema. Deberías observar que la instancia de la app no recibe el mensaje.
9. Resumen
Repasemos lo que aprendiste hasta ahora.
- Cómo iniciar una suscripción o anulación de suscripción a un tema desde una instancia de app
- Envío de un mensaje al tema y verificación de recepción en instancias de app suscritas
- Se envía un mensaje a un tema condición y se verifica la recepción en una instancia de la app que cumpla con la condición.
En la siguiente sección, aprenderás a suscribir o anular la suscripción de instancias de apps a temas sin necesidad de crear instancias de llamadas desde el lado del cliente.
10. Administra suscripciones a temas desde el servidor
Hasta ahora, en este codelab, todas las llamadas de suscripción y anulación de suscripción a temas se inician desde una instancia de app.
Sin embargo, en algunos casos de uso, es posible que desees administrar las suscripciones a temas desde el servidor. Por ejemplo, es posible que desees suscribir un subgrupo de tu base de usuarios existente a un tema nuevo sin esperar el lanzamiento de una app.
En esta sección, aprenderás a usar el SDK de Firebase Admin para suscribir y anular la suscripción de un lote de tokens de registro de FCM a un tema mediante llamadas desde el servidor.
Implementa la suscripción del servidor a los tokens de registro de FCM en el tema de FCM
- En el código del servidor, ve a la clase
FcmSubscriptionManager.java
. Ubica el método llamadosubscribeFcmRegistrationTokensToTopic
. Aquí implementarás la llamada a la API desubscribeToTopic
.
- Suscribamos la instancia de la app al tema Energía. Para ello, primero debes proporcionar los datos en los siguientes dos campos:
registrationTokens
: Es una lista de cadenas separadas por comas que representan los tokens de registro de FCM para los que deseas crear suscripciones a temas.topicName
: Es el nombre del tema Energía, es decir,/topics/Energy
.
- En las próximas líneas, implementa la llamada siguiendo estas líneas:
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic( registrationTokens, topicName);
- Puedes inspeccionar la
TopicManagementResponse
para obtener estadísticas de resultados de alto nivel. Por ejemplo, imprimir la cantidad de suscripciones a temas creadas correctamente congetSuccessCount
.
System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
- Por último, en la función
main
, habilita las llamadas solo a la funciónsubscribeFcmRegistrationTokensToTopic
.
Crea una suscripción y envía un mensaje por tema
- En este punto, ya puedes crear la suscripción al tema y enviarle un mensaje.
- Ejecuta la función
main
de la claseFcmSubscriptionManager.java
. Esto creará una suscripción al tema. - Ahora, configura el código para enviar el mensaje. Al igual que antes,
- En
FcmSender.java
, busca la funciónsendMessageToFcmTopic
. - Establece el
topicName
en el tema Energía, es decir,/topics/Energy
. - Crea un objeto
Message
y oriéntalo al tema consetTopic
. - Por último, actualiza el método
main
para habilitar solo la funciónsendMessageToFcmTopic
.
- En
- Ejecuta la función
main
deFcmSender.java
. Esto enviará el mensaje a la instancia de tu app y podrás observarlo en ella de la siguiente manera.- Instancia de la app en primer plano
- Instancia de la app en segundo plano
Implementa la anulación de la suscripción del servidor de los tokens de registro de FCM al tema de FCM
- Para cancelar la suscripción a temas del servidor, usa esta API de
unsubscribeFromTopic
. Agregarás el código relevante a la funciónunsubscribeFcmRegistrationTokensFromTopic
de la claseFcmSubscriptionManager.java
.
- La implementación del código de anulación de suscripción del servidor y la validación de su efecto mediante el envío de un mensaje a un tema queda como un ejercicio que debes realizar.
11. Felicitaciones
Felicitaciones. Usaste correctamente los temas de FCM para enviar mensajes multicast a los subgrupos de las instancias de tu app. Esto simplificará la capacidad de llegar a los usuarios de forma oportuna mediante contenido relevante.
Próximos pasos
Ahora que completaste tu codelab, considera probar temas para otras plataformas con las siguientes guías: