Para segmentar un mensaje a varios dispositivos, usa Mensajería a temas. Esta función te permite enviar un mensaje a varios dispositivos que hayan aceptado un tema específico.
Este instructivo se enfoca en el envío de mensajes por temas desde el servidor de apps con el Admin SDK o la API de REST para FCM, así como en la recepción y administración de ellos en una app para Android. Abordaremos la administración de mensajes para apps en primer y segundo plano. Se incluyen todos los pasos para hacerlo, desde la configuración hasta la verificación.
Configura el SDK
Es posible que ya hayas completado algunos pasos de esta sección si configuraste una app cliente de Android para FCM o si ya enviaste tu primer mensaje.
Antes de comenzar
Instala Android Studio o actualízalo a su versión más reciente.
Asegúrate de que tu proyecto cumpla con estos requisitos (ten en cuenta que algunos productos pueden tener requisitos más estrictos):
- Se segmenta al nivel de API 21 (Lollipop) o una versión posterior.
- Usa Android 5.0 o una versión posterior.
- Utiliza
Jetpack (AndroidX),
que incluye el cumplimiento de los siguientes requisitos de versión:
com.android.tools.build:gradle
v7.3.0 o una versión posteriorcompileSdkVersion
28 o una versión posterior
Configura un dispositivo físico o usa un emulador para ejecutar tu app.
Ten en cuenta que los SDKs de Firebase con una dependencia en Servicios de Google Play requieren que el dispositivo o el emulador tenga instalados los Servicios de Google Play.Accede a Firebase con tu Cuenta de Google.
Si solo quieres probar un producto de Firebase, pero aún no tienes un proyecto de Android, puedes descargar una de estas muestras de inicio rápido.
Crea un proyecto de Firebase
Antes de poder agregar Firebase a tu app para Android, debes crear un proyecto de Firebase y conectarlo a la app. Visita Información sobre los proyectos de Firebase para obtener más detalles sobre este tema.
Registra tu app en Firebase
Si quieres usar Firebase en tu app para Android, debes registrar la app con el proyecto de Firebase. El registro de tu app a menudo se conoce como “agregar” la app a tu proyecto.
Ve a Firebase console.
En el centro de la página de descripción general del proyecto, haz clic en el ícono de Android (
) o en Agregar app para iniciar el flujo de trabajo de configuración.Ingresa el nombre del paquete de tu app en el campo Nombre del paquete de Android.
Ingresa otra información de la app, como el sobrenombre y el certificado de firma SHA-1 de depuración (opcional).
Haz clic en Registrar app.
Agrega un archivo de configuración de Firebase
Descarga y, luego, agrega el archivo de configuración de Firebase para Android (
) a la app:google-services.json Haz clic en Descargar google-services.json a fin de obtener el archivo de configuración de Firebase para Android.
Transfiere tu archivo de configuración al directorio raíz del módulo (nivel de app) de tu app.
Para que los SDKs de Firebase puedan acceder a los valores de tu archivo de configuración
, necesitas el complemento de los servicios de Google para Gradle (google-services.json google-services
).Agrega el complemento de Google Services como dependencia en el archivo de Gradle (
<project>/build.gradle.kts
o<project>/build.gradle
) a nivel de raíz (a nivel de proyecto):Kotlin
plugins { id("com.android.application") version "7.3.0" apply false // ... // Add the dependency for the Google services Gradle plugin id("com.google.gms.google-services") version "4.4.2" apply false }
Groovy
plugins { id 'com.android.application' version '7.3.0' apply false // ... // Add the dependency for the Google services Gradle plugin id 'com.google.gms.google-services' version '4.4.2' apply false }
Agrega el complemento de los servicios de Google en el archivo de Gradle (generalmente
<project>/<app-module>/build.gradle.kts
o<project>/<app-module>/build.gradle
) del módulo (nivel de app):Kotlin
plugins { id("com.android.application") // Add the Google services Gradle plugin id("com.google.gms.google-services") // ... }
Groovy
plugins { id 'com.android.application' // Add the Google services Gradle plugin id 'com.google.gms.google-services' // ... }
Agrega los SDK de Firebase a tu app
En el archivo Gradle del módulo (nivel de la app) (generalmente
<project>/<app-module>/build.gradle.kts
o<project>/<app-module>/build.gradle
), agrega la dependencia de la biblioteca de Firebase Cloud Messaging para Android. Te recomendamos usar la Firebase Android BoM para controlar las versiones de las bibliotecas.Para obtener una experiencia óptima con Firebase Cloud Messaging, te recomendamos habilitar la Google Analytics en tu proyecto de Firebase y agregar el SDK de Firebase para Google Analytics a tu app.
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.7.0")) // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries // When using the BoM, you don't specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-messaging") implementation("com.google.firebase:firebase-analytics") }
Cuando usas la Firebase Android BoM, tu app siempre usará versiones compatibles de las bibliotecas de Firebase para Android.
(Alternativa) Agrega dependencias de la biblioteca de Firebase sin usar la BoM
Si eliges no usar la Firebase BoM, debes especificar cada versión de la biblioteca de Firebase en su línea de dependencia.
Ten en cuenta que, si usas múltiples bibliotecas de Firebase en tu app, es muy recomendable que uses la BoM para administrar las versiones de las bibliotecas para garantizar que todas las versiones sean compatibles.
dependencies { // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-messaging:24.1.0") implementation("com.google.firebase:firebase-analytics:22.1.2") }
Sincroniza tu proyecto de Android con archivos Gradle.
Suscribe la app cliente a un tema
Las apps cliente se pueden suscribir a cualquier tema existente o pueden crear un tema nuevo. Cuando una app cliente se suscribe a un nombre de tema nuevo (uno que no existe aún para tu proyecto de Firebase), se crea un tema nuevo con ese nombre en FCM y cualquier cliente se puede suscribir a él posteriormente.
Para suscribirse a un tema, la app cliente llama a subscribeToTopic()
de Firebase Cloud Messaging con el nombre del tema de FCM. Este método
muestra una Task
, que un objeto de escucha de finalización puede usar para determinar si
la suscripción se realizó correctamente:
Kotlin+KTX
Firebase.messaging.subscribeToTopic("weather") .addOnCompleteListener { task -> var msg = "Subscribed" if (!task.isSuccessful) { msg = "Subscribe failed" } Log.d(TAG, msg) Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show() }
Java
FirebaseMessaging.getInstance().subscribeToTopic("weather") .addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { String msg = "Subscribed"; if (!task.isSuccessful()) { msg = "Subscribe failed"; } Log.d(TAG, msg); Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show(); } });
Para anular la suscripción, la app cliente llama a unsubscribeFromTopic()
de Firebase Cloud Messaging
con el nombre del tema.
Recibe y administra mensajes a temas
FCM entrega mensajes a temas de la misma manera que otros mensajes downstream.
Para recibir mensajes, usa un servicio que extienda FirebaseMessagingService
.
El servicio debe anular las devoluciones de llamada onMessageReceived
y onDeletedMessages
.
El período para manejar un mensaje puede ser inferior a 20 segundos, según los retrasos en los que se incurrió antes de llamar a onMessageReceived
, incluidos los retrasos del SO, el tiempo de inicio de la app, el subproceso principal que bloquearon otras operaciones o las llamadas a onMessageReceived
previas que demoran demasiado. Después de ese tiempo, varios comportamientos del SO, como la eliminación del proceso de Android o los
límites de ejecución en segundo plano de Android O, pueden interferir en tu capacidad para finalizar el trabajo.
onMessageReceived
se proporciona para la mayoría de los tipos de mensajes, con las siguientes excepciones:
-
Mensajes de notificación enviados cuando la app está en segundo plano. En este caso, la notificación se entrega a la bandeja del sistema del dispositivo. Cuando un usuario presiona una notificación, abre el selector de aplicaciones de forma predeterminada.
-
Mensajes con una notificación y carga útil de datos cuando se reciben en segundo plano. En este caso, la notificación se entrega a la bandeja del sistema del dispositivo, y la carga útil de datos se entrega en los adicionales del intent de tu actividad iniciadora.
Resumen:
Estado de la app | Notificación | Datos | Ambos |
---|---|---|---|
Primer plano | onMessageReceived |
onMessageReceived |
onMessageReceived |
Segundo plano | Bandeja del sistema | onMessageReceived |
Notificación: bandeja del sistema Datos: en adicionales del intent |
Edita el manifiesto de la app
Para usar FirebaseMessagingService
, deberás agregar lo siguiente en el manifiesto de la app:
<service android:name=".java.MyFirebaseMessagingService" android:exported="false"> <intent-filter> <action android:name="com.google.firebase.MESSAGING_EVENT" /> </intent-filter> </service>
Además, te recomendamos establecer valores predeterminados para personalizar el aspecto de las notificaciones. Puedes especificar un ícono y un color predeterminados y personalizados que se aplican cada vez que no se establecen valores equivalentes en la carga útil de notificación.
Agrega estas líneas en la etiqueta application
para establecer el ícono predeterminado y el color personalizados:
<!-- Set custom default icon. This is used when no icon is set for incoming notification messages. See README(https://goo.gl/l4GJaQ) for more. --> <meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@drawable/ic_stat_ic_notification" /> <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming notification message. See README(https://goo.gl/6BKBk7) for more. --> <meta-data android:name="com.google.firebase.messaging.default_notification_color" android:resource="@color/colorAccent" />
Android muestra el ícono predeterminado personalizado para lo siguiente:
- Todos los mensajes de notificación enviados desde el Compositor de Notifications
- Todos los mensajes de notificación que no establecen el ícono de manera explícita en la carga útil de la notificación
Android usa el color predeterminado personalizado para lo siguiente:
- Todos los mensajes de notificación enviados desde el Compositor de Notifications
- Todos los mensajes de notificación que no definen el color de manera explícita en la carga útil de la notificación
Si no hay un ícono predeterminado personalizado ni se establece un ícono en la carga útil de la notificación, Android muestra el ícono de la aplicación en blanco.
Anula onMessageReceived
Puedes anular el método FirebaseMessagingService.onMessageReceived
para realizar acciones según el objeto RemoteMessage recibido y obtener los datos del mensaje de la siguiente manera:
Kotlin+KTX
override fun onMessageReceived(remoteMessage: RemoteMessage) { // TODO(developer): Handle FCM messages here. // Not getting messages here? See why this may be: https://goo.gl/39bRNJ Log.d(TAG, "From: ${remoteMessage.from}") // Check if message contains a data payload. if (remoteMessage.data.isNotEmpty()) { Log.d(TAG, "Message data payload: ${remoteMessage.data}") // Check if data needs to be processed by long running job if (needsToBeScheduled()) { // For long-running tasks (10 seconds or more) use WorkManager. scheduleJob() } else { // Handle message within 10 seconds handleNow() } } // Check if message contains a notification payload. remoteMessage.notification?.let { Log.d(TAG, "Message Notification Body: ${it.body}") } // Also if you intend on generating your own notifications as a result of a received FCM // message, here is where that should be initiated. See sendNotification method below. }
Java
@Override public void onMessageReceived(RemoteMessage remoteMessage) { // TODO(developer): Handle FCM messages here. // Not getting messages here? See why this may be: https://goo.gl/39bRNJ Log.d(TAG, "From: " + remoteMessage.getFrom()); // Check if message contains a data payload. if (remoteMessage.getData().size() > 0) { Log.d(TAG, "Message data payload: " + remoteMessage.getData()); if (/* Check if data needs to be processed by long running job */ true) { // For long-running tasks (10 seconds or more) use WorkManager. scheduleJob(); } else { // Handle message within 10 seconds handleNow(); } } // Check if message contains a notification payload. if (remoteMessage.getNotification() != null) { Log.d(TAG, "Message Notification Body: " + remoteMessage.getNotification().getBody()); } // Also if you intend on generating your own notifications as a result of a received FCM // message, here is where that should be initiated. See sendNotification method below. }
Anula onDeletedMessages
En algunas situaciones, es posible que FCM no envíe un mensaje. Esto ocurre cuando hay muchos
mensajes (más de 100) pendientes para
tu app en un dispositivo específico al momento de conectarse o si el dispositivo no se conecta a
FCM durante más de un mes. En estos casos,
es posible que recibas una devolución de llamada a FirebaseMessagingService.onDeletedMessages()
.
Cuando la instancia de app recibe esta devolución de llamada,
debería ejecutar una sincronización completa con tu servidor de apps. Si no enviaste un mensaje a la app en ese
dispositivo en las últimas 4 semanas, FCM no llamará a onDeletedMessages()
.
Maneja mensajes de notificación en una app en segundo plano
Cuando tu app está en segundo plano, Android dirige los mensajes de notificación a la bandeja del sistema. Cuando un usuario presiona una notificación, se abre el selector de aplicaciones de forma predeterminada.
Esto incluye los mensajes que contienen una notificación y carga útil de datos (y todos los mensajes que se envíen desde la consola de Notifications). En estos casos, la notificación se entrega a la bandeja del sistema del dispositivo, y la carga de datos útil se entrega en los adicionales del intent de tu actividad iniciadora.
Para obtener información sobre la entrega de mensajes en tu app, consulta el panel de informes de FCM, en el que se registra la cantidad de mensajes que se enviaron y abrieron en dispositivos Apple y Android, junto con datos de "impresiones" (las notificaciones que ven los usuarios) de las apps para Android.
Crea solicitudes de envío
Puedes enviar mensajes al tema después de haber creado uno, ya sea mediante la suscripción de instancias de la app cliente al tema desde el cliente o a través de la API del servidor. Si es la primera vez que creas solicitudes de envío para FCM, consulta la guía sobre tu entorno de servidor y FCM para obtener información importante de carácter general y sobre la configuración.
Especifica el nombre que quieres darle al tema en la lógica de envío del backend, como se muestra a continuación:
Node.js
// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';
const message = {
data: {
score: '850',
time: '2:45'
},
topic: topic
};
// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";
// See documentation on defining a message payload.
Message message = Message.builder()
.putData("score", "850")
.putData("time", "2:45")
.setTopic(topic)
.build();
// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'
# See documentation on defining a message payload.
message = messaging.Message(
data={
'score': '850',
'time': '2:45',
},
topic=topic,
)
# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Topic: topic,
}
// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";
// See documentation on defining a message payload.
var message = new Message()
{
Data = new Dictionary<string, string>()
{
{ "score", "850" },
{ "time", "2:45" },
},
Topic = topic,
};
// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
}
}
Comando de cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message": {
"topic" : "foo-bar",
"notification": {
"body": "This is a Firebase Cloud Messaging Topic Message!",
"title": "FCM Message"
}
}
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Para enviar un mensaje a una combinación de temas, debes especificar una condición, es decir, una expresión booleana en la que se especifican los temas de destino. Por ejemplo, la siguiente condición enviará mensajes a los dispositivos suscritos a TopicA
, y a TopicB
o TopicC
:
"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
En primer lugar, FCM evalúa las condiciones en paréntesis y, luego, evalúa
la expresión de izquierda a derecha. En la expresión anterior, un usuario suscrito a uno solo de los temas no recibirá el mensaje. Asimismo, un usuario que no está
suscrito a TopicA
no recibirá el mensaje. Las siguientes combinaciones sí lo reciben:
TopicA
yTopicB
TopicA
yTopicC
Puedes incluir hasta cinco temas en tu expresión condicional.
Para enviar mensajes a una condición, haz lo siguiente:
Node.js
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';
// See documentation on defining a message payload.
const message = {
notification: {
title: '$FooCorp up 1.43% on the day',
body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
},
condition: condition
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
.then((response) => {
// Response is a message ID string.
console.log('Successfully sent message:', response);
})
.catch((error) => {
console.log('Error sending message:', error);
});
Java
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
Message message = Message.builder()
.setNotification(Notification.builder()
.setTitle("$GOOG up 1.43% on the day")
.setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
.build())
.setCondition(condition)
.build();
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
Python
# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"
# See documentation on defining a message payload.
message = messaging.Message(
notification=messaging.Notification(
title='$GOOG up 1.43% on the day',
body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
),
condition=condition,
)
# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
Go
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"
// See documentation on defining a message payload.
message := &messaging.Message{
Data: map[string]string{
"score": "850",
"time": "2:45",
},
Condition: condition,
}
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
C#
// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";
// See documentation on defining a message payload.
var message = new Message()
{
Notification = new Notification()
{
Title = "$GOOG up 1.43% on the day",
Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
},
Condition = condition,
};
// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"condition": "'dogs' in topics || 'cats' in topics",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message",
}
}
}
Comando de cURL:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"notification": {
"title": "FCM Message",
"body": "This is a Firebase Cloud Messaging Topic Message!",
},
"condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Próximos pasos
- Puedes usar tu servidor para suscribir instancias de la app cliente a temas y realizar otras tareas de administración. Consulta cómo administrar suscripciones a temas en el servidor.