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 recentecompileSdkVersion
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.
Acesse o Console do Firebase.
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.Digite o nome do pacote do app no campo Nome do pacote Android.
(Opcional) Insira outras informações do aplicativo: apelido do app e certificado de assinatura SHA-1 de depuração.
Clique em Registrar app.
Adicionar um arquivo de configuração do Firebase
Faça o download e adicione ao seu app o arquivo de configuração do Firebase para Android (
):google-services.json Clique em Fazer o download do google-services.json para receber o arquivo de configuração do Firebase para Android.
Mova esse arquivo para o diretório raiz do módulo (nível do app) do seu aplicativo.
Para permitir que os SDKs do Firebase acessem os valores no seu arquivo de configuração
, você precisa do plug-in do Gradle para Serviços do Google (google-services.json google-services
).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 } }
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
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' }
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() }
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 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. |
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>
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" />
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. }
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. }
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);
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 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
eTopicB
TopicA
eTopicC
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);
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 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
- Você pode usar seu servidor para inscrever instâncias de apps clientes em tópicos e realizar outras tarefas de gerenciamento. Consulte Gerenciar inscrições em tópicos no servidor.
- Saiba mais sobre outras maneiras de enviar mensagens a vários dispositivos em Mensagens para grupos de dispositivos.