Enviar mensagens a vários dispositivos

Há duas maneiras de enviar uma mensagem para vários dispositivos usando o Firebase Cloud Messaging:

  • Mensagens de tópicos, que permitem o envio de uma mensagem a vários dispositivos que optaram por receber mensagens sobre um tópico específico.
  • Mensagens para grupos de dispositivos, que permitem o envio de uma mensagem a vários dispositivos que pertencem a um grupo definido por você.

O objetivo deste tutorial é mostrar o envio de mensagens de tópicos pelo servidor do app usando o SDK Admin ou a API REST para FCM, além de como receber e processar essas mensagens em um app Android. Vamos abordar o processamento de mensagens para aplicativos em primeiro e segundo plano. Todas as etapas para alcançar esse objetivo são abordadas, desde a configuração até a verificação.

Configurar o SDK

Se você configurou um app cliente para Android no FCM ou concluiu as etapas para enviar a primeira mensagem, talvez as etapas abordadas nesta seção já tenham sido concluídas.

Antes de começar

  • Instale ou atualize o Android Studio para a versão mais recente.

  • Verifique se o projeto atende a estes requisitos:

    • O nível desejado da API é 19 (KitKat) ou superior
    • Usa o Android 4.4 ou versões mais recentes
    • Usa o Jetpack (AndroidX), que inclui o cumprimento dos seguintes requisitos de versão:
      • com.android.tools.build:gradle v3.2.1 ou mais recente
      • compileSdkVersion 28 ou mais recente

  • Configure um dispositivo físico ou use um emulador para executar o app.
    Os SDKs do Firebase com uma dependência no Google Play Services exigem que o dispositivo ou o emulador tenham o Google Play Services instalado.

  • Faça login no Firebase com sua Conta do Google.

Se você ainda não tem um projeto Android, mas quer testar um produto do Firebase, faça o download de uma das nossas amostras introdutórias.

Criar um projeto do Firebase

Antes de adicionar o Firebase ao app Android, é preciso criar um projeto do Firebase para então conectá-lo ao app. Acesse Noções básicas sobre projetos do Firebase para saber mais.

Registrar o app no Firebase

Para usar o Firebase no seu app Android, é necessário registrá-lo no projeto do Firebase. Registrar o app também quer dizer "adicionar" o app ao projeto.

  1. Acesse o Console do Firebase.

  2. No centro da página de visão geral do projeto, clique no ícone do Android () ou em Adicionar app para iniciar o fluxo de trabalho de configuração.

  3. Digite o nome do pacote do app no campo Nome do pacote Android.

  4. (Opcional) Insira outras informações do aplicativo: apelido do app e certificado de assinatura SHA-1 de depuração.

  5. Clique em Registrar app.

Adicionar um arquivo de configuração do Firebase

  1. Faça o download e adicione ao seu app o arquivo de configuração do Firebase para Android (google-services.json):

    1. Clique em Fazer o download do google-services.json para receber o arquivo de configuração do Firebase para Android.

    2. Mova esse arquivo para o diretório raiz do módulo (nível do app) do seu aplicativo.

  2. Para permitir que os SDKs do Firebase acessem os valores no seu arquivo de configuração google-services.json, você precisa do plug-in do Gradle para Serviços do Google (google-services).

    1. No arquivo Gradle no nível raiz do projeto (<project>/build.gradle), adicione o plug-in dos Serviços do Google como uma dependência do buildscript:

      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. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle), adicione o plug-in dos Serviços do Google:

      plugins {
    id 'com.android.application'

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

Adicionar SDKs do Firebase ao seu app

  1. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle), adicione a dependência da biblioteca Android do Firebase Cloud Messaging. Para gerenciar o controle de versões das bibliotecas, recomendamos usar a BoM do Firebase para Android.

    Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no seu projeto e adicionar o SDK do Firebase para Analytics ao seu 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'
}

    Com a BoM do Firebase para Android, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.

    (Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar a BoM

    Se você preferir não usar a BoM do Firebase, especifique cada versão das bibliotecas do Firebase na linha de dependência correspondente.

    Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a BoM para gerenciar as versões delas, porque isso ajuda a garantir a compatibilidade de todas as bibliotecas. 

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

    Com a BoM do Firebase para Android, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.

    (Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar a BoM

    Se você preferir não usar a BoM do Firebase, especifique cada versão das bibliotecas do Firebase na linha de dependência correspondente.

    Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a BoM para gerenciar as versões delas, porque isso ajuda a garantir a compatibilidade de todas as bibliotecas. 

    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. Sincronize seu projeto do Android com os arquivos Gradle.

Fazer a assinatura do app cliente em um tópico

Os apps clientes podem ser inscritos em qualquer tópico atual ou podem criar um novo tópico. Quando um app cliente for inscrito em um novo nome de tópico que ainda não existe no seu projeto do Firebase, um novo tópico com esse nome será criado no FCM e qualquer cliente poderá se inscrever nele posteriormente.

Para se inscrever em um tópico, o app cliente chama o subscribeToTopic() do Firebase Cloud Messaging com o nome do tópico do FCM. Esse método retorna uma Task, que pode ser usada por um listener de conclusão para determinar se a inscrição foi bem-sucedida:

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 cancelar a inscrição, o app cliente chama o unsubscribeFromTopic() do Firebase Cloud Messaging com o nome do tópico.

Receber e processar mensagens de tópicos

O FCM entrega as mensagens dos tópicos da mesma forma que as outras mensagens downstream.

Para receber mensagens, use um serviço que amplie o FirebaseMessagingService. Seu serviço precisa substituir as callbacks onMessageReceived e onDeletedMessages. Ele deve processar qualquer mensagem em até 20 segundos após o recebimento (10 segundos no Android Marshmallow). O período pode ser mais curto, dependendo dos atrasos do SO incorridos antes de chamar onMessageReceived. Depois disso, vários comportamentos do SO, como os limites de execução em segundo plano do Android O, podem interferir na capacidade de concluir seu trabalho. Para mais informações, consulte nossa visão geral sobre prioridade de mensagens.

O onMessageReceived está disponível para a maioria dos tipos de mensagens, com as seguintes exceções:

  • Mensagens de notificação entregues quando seu app estiver em segundo plano. Nesse caso, a notificação é entregue à bandeja do sistema do dispositivo. Quando um usuário toca na notificação, a tela de início do app é aberta por padrão.

  • Mensagens com payload de notificação e dados, quando recebidas em segundo plano. Nesse caso, a notificação é entregue à bandeja do sistema do dispositivo, e o payload de dados é entregue nos extras da intent da atividade da sua tela de início.

Em resumo:

Estado do app Notificação Dados Ambos
Primeiro plano onMessageReceived onMessageReceived onMessageReceived
Segundo plano Bandeja do sistema onMessageReceived Notificação: bandeja do sistema
Dados: nos extras da intent.
Para mais informações sobre os tipos de mensagens, consulte Notificações e mensagens de dados.

Editar o manifesto do app

Para usar FirebaseMessagingService, adicione o seguinte ao manifesto do seu app:

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
AndroidManifest.xml

Além disso, recomendamos que você defina valores padrão para personalizar a aparência das notificações. É possível especificar uma cor e um ícone padrão personalizados que serão aplicados sempre que valores equivalentes não estiverem definidos no payload da notificação.

Adicione estas linhas na tag application para definir a cor e o ícone padrão 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

O Android exibe o ícone personalizado padrão para:

  • todas as mensagens de notificação enviadas pelo Editor do Notificações;
  • todas as mensagens de notificação que não definem explicitamente o ícone no payload da notificação.

O Android usa a cor padrão personalizada para:

  • todas as mensagens de notificação enviadas pelo Editor do Notificações;
  • todas as mensagens de notificação que não definem explicitamente a cor no payload de notificação.

Se não houver um ícone personalizado padrão ou nenhum ícone estiver definido no payload de notificação, o Android exibirá o ícone do aplicativo renderizado na cor branca.

Substituir onMessageReceived

Ao substituir o método FirebaseMessagingService.onMessageReceived, é possível realizar ações com base no objeto RemoteMessage recebido e acessar os dados da mensagem:

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

Substituir onDeletedMessages

Em algumas situações, é possível que o FCM não entregue uma mensagem. Isso ocorre quando há muitas mensagens pendentes (mais de 100) no app em um dispositivo específico no momento em que ele é conectado ou se o dispositivo não for conectado ao FCM por mais de um mês. Nesses casos, talvez você receba uma callback para FirebaseMessagingService.onDeletedMessages(). Quando isso acontece, a instância do app precisa executar uma sincronização completa com o servidor do app. Se você não enviou uma mensagem ao app no dispositivo nas últimas quatro semanas, o FCM não vai chamar onDeletedMessages().

Processar mensagens de notificação em um app em segundo plano

Quando seu app está em segundo plano, o Android direciona as notificações para a bandeja do sistema. Quando um usuário toca nelas, a tela de início do aplicativo é aberta por padrão.

Isso inclui mensagens que contêm payload de notificação e dados, assim como todas aquelas enviadas pelo console do Notificações. Nesses casos, a notificação é entregue à bandeja do sistema do dispositivo, e o payload de dados é entregue nos extras da intent da atividade da tela de início.

Confira as informações sobre a entrega de mensagens ao seu app no painel de relatórios do FCM, que registra o número de mensagens enviadas e abertas em dispositivos Apple e Android, além de dados de "impressões" (notificações vistas pelos usuários) para apps Android.

Criar solicitações de envio

Depois de criar um tópico, seja inscrevendo instâncias do app cliente no tópico do lado do cliente ou usando a API do servidor, será possível enviar mensagens ao tópico. Se esta for a primeira vez que você cria solicitações de envio para o FCM, consulte o guia do ambiente do servidor e o FCM para informações gerais importantes e sobre configuração.

Na sua lógica de envio no back-end, especifique o nome do tópico desejado conforme mostrado abaixo:

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 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 uma mensagem para uma combinação de tópicos, especifique uma condição, que é uma expressão booleana que especifica os tópicos de destino. Por exemplo, a seguinte condição vai enviar mensagens para dispositivos que estão inscritos em TopicA e TopicB ou TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

No FCM, todas as condições entre parênteses são avaliadas primeiro e depois a expressão é analisada da esquerda para a direita. Na expressão acima, um usuário que se inscreveu em um só tópico não receberá a mensagem. Do mesmo modo, um usuário que não se inscreveu em TopicA também não receberá a mensagem. Somente estas combinações são válidas:

  • TopicA e TopicB
  • TopicA e TopicC

Você pode incluir até cinco tópicos na sua expressão condicional.

Para enviar para uma condição:

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 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óximas etapas