Envía mensajes a varios dispositivos

Firebase Cloud Messaging ofrece dos maneras de enviar un mensaje a varios dispositivos:

Este instructivo se enfoca en el envío de mensajes por temas desde el servidor de apps mediante el SDK de Admin 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:

    • El nivel de API objetivo debe ser 19 (KitKat) o superior.
    • Usa Android 4.4 o una versión posterior.
    • Utiliza Jetpack (AndroidX), que incluye el cumplimiento de los siguientes requisitos de versión:
      • com.android.tools.build:gradle 3.2.1 o una versión posterior
      • compileSdkVersion 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.

  1. Dirígete a Firebase console.

  2. 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.

  3. Ingresa el nombre del paquete de tu app en el campo Nombre del paquete de Android.

  4. Ingresa otra información de la app, como el sobrenombre y el certificado de firma SHA-1 de depuración (opcional).

  5. Haz clic en Registrar app.

Agrega un archivo de configuración de Firebase

  1. Descarga y, luego, agrega el archivo de configuración de Firebase para Android (google-services.json) a la app:

    1. Haz clic en Descargar google-services.json a fin de obtener el archivo de configuración de Firebase para Android.

    2. Transfiere tu archivo de configuración al directorio raíz del módulo (nivel de app) de tu app.

  2. Para que los SDKs de Firebase puedan acceder a los valores de tu archivo de configuración google-services.json, necesitas el complemento de los servicios de Google para Gradle (google-services).

    1. Agrega el complemento de los servicios de Google como dependencia de buildscript en el archivo de Gradle (<project>/build.gradle) de nivel de raíz (nivel de proyecto):

      buildscript {

    repositories {
      // Make sure that you have the following two repositories
      google()  // Google's Maven repository
      mavenCentral()  // Maven Central repository
    }

    dependencies {
      ...

      // Add the dependency for the Google services Gradle plugin
      classpath 'com.google.gms:google-services:4.3.15'
    }
}

allprojects {
  ...

  repositories {
    // Make sure that you have the following two repositories
    google()  // Google's Maven repository
    mavenCentral()  // Maven Central repository
  }
}

    2. Agrega el complemento de los servicios de Google en el archivo de Gradle (generalmente <project>/<app-module>/build.gradle) del módulo (nivel de app):

      plugins {
    id 'com.android.application'

    // Add the Google services Gradle plugin
    id 'com.google.gms.google-services'
    ...
}

Agrega los SDKs de Firebase a tu app

  1. Agrega la dependencia de la biblioteca de Android para Firebase Cloud Messaging en el archivo de Gradle (generalmente <project>/<app-module>/build.gradle) del módulo (nivel de app): Te recomendamos usar la BoM de Firebase para Android para controlar las versiones de las bibliotecas.

    Para obtener una experiencia óptima con Firebase Cloud Messaging, recomendamos habilitar Google Analytics en tu proyecto de Firebase y agregar el SDK de Firebase para Google Analytics a la app.

    Java 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:32.1.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'
}

    Si usas la BoM de Firebase para Android, tu app siempre utilizará 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 BoM de Firebase, 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 utilices 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:23.1.2'
    implementation 'com.google.firebase:firebase-analytics:21.3.0'
}

    Kotlin+KTX 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:32.1.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-ktx'
    implementation 'com.google.firebase:firebase-analytics-ktx'
}

    Si usas la BoM de Firebase para Android, tu app siempre utilizará 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 BoM de Firebase, 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 utilices 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-ktx:23.1.2'
    implementation 'com.google.firebase:firebase-analytics-ktx:21.3.0'
}

  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 se puede usar en un objeto de escucha de finalización 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()
    }
MainActivity.kt

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();
            }
        });
MainActivity.java

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 por 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. Debe administrar cualquier mensaje en un plazo de 20 segundos desde su recepción (10 segundos en Android Marshmallow). El margen de tiempo puede ser más breve según los retrasos del SO en los que se incurrió antes de llamar a onMessageReceived. Después de ese tiempo, varios comportamientos del SO, como los límites de ejecución en segundo plano de Android O, pueden interferir en tu capacidad para finalizar el trabajo. Si deseas obtener más información, consulta la descripción general sobre la prioridad de los mensajes.

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
Para obtener más información acerca de los tipos de mensajes, consulta Mensajes de notificación y de datos.

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>
AndroidManifest.xml

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" />
AndroidManifest.xml

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.
}
MyFirebaseMessagingService.kt

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.
}
MyFirebaseMessagingService.java

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 útil de datos 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);
FirebaseMessagingSnippets.java

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)
cloud_messaging.py

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)
messaging.go

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 y TopicB
  • TopicA y TopicC

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);
FirebaseMessagingSnippets.java

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)
cloud_messaging.py

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)
messaging.go

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