Envie mensagens para vários dispositivos

Para direcionar uma mensagem para vários dispositivos, use Mensagens de tópico . Este recurso permite que você envie uma mensagem para vários dispositivos que ativaram um tópico específico.

Este tutorial se concentra no envio de mensagens de tópico do servidor do seu aplicativo usando o SDK Admin ou a API REST para FCM e no recebimento e processamento delas em um aplicativo Android. Abordaremos o tratamento de mensagens para aplicativos em segundo e primeiro plano. Todas as etapas para conseguir isso são abordadas, desde a configuração até a verificação.

Configure o SDK

Esta seção pode abranger etapas que você já concluiu se tiver configurado um aplicativo cliente Android para FCM ou trabalhado nas etapas para Enviar sua primeira mensagem .

Antes de você começar

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

  • Certifique-se de que seu projeto atenda a estes requisitos:

    • Segmenta API de nível 19 (KitKat) ou superior
    • Usa Android 4.4 ou superior
    • Usa Jetpack (AndroidX) , que inclui atender a estes requisitos de versão:
      • com.android.tools.build:gradle v7.3.0 ou posterior
      • compileSdkVersion 28 ou posterior

  • Configure um dispositivo físico ou use um emulador para executar seu aplicativo.
    Observe que os SDKs do Firebase que dependem do Google Play Services exigem que o dispositivo ou emulador tenha o Google Play Services instalado.

  • Faça login no Firebase usando sua conta do Google.

Se você ainda não tem um projeto Android e deseja apenas testar um produto Firebase, baixe um de nossos exemplos de início rápido .

Crie um projeto do Firebase

Antes de adicionar o Firebase ao seu aplicativo Android, você precisa criar um projeto do Firebase para se conectar ao seu aplicativo Android. Visite Entenda os projetos do Firebase para saber mais sobre os projetos do Firebase.

Registre seu aplicativo no Firebase

Para usar o Firebase em seu aplicativo Android, você precisa registrar seu aplicativo no projeto do Firebase. Registrar seu aplicativo geralmente é chamado de "adicionar" seu aplicativo ao projeto.

  1. Vá para o console do Firebase .

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

  3. Insira o nome do pacote do seu aplicativo no campo Nome do pacote Android .

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

  5. Clique em Registrar aplicativo .

Adicione um arquivo de configuração do Firebase

  1. Baixe e adicione o arquivo de configuração do Firebase Android ( google-services.json ) ao seu aplicativo:

    1. Clique em Baixar google-services.json para obter seu arquivo de configuração do Firebase Android.

    2. Mova seu arquivo de configuração para o diretório raiz do módulo (nível do aplicativo) do seu aplicativo.

  2. Para tornar os valores em seu arquivo de configuração google-services.json acessíveis aos SDKs do Firebase, você precisa do plug-in Gradle de serviços do Google ( google-services ).

    1. Em seu arquivo Gradle de nível raiz (nível de projeto) ( <project>/build.gradle.kts ou <project>/build.gradle ), adicione o plug-in de serviços do Google como uma dependência:

      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.1" 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.1' apply false
}

    2. No arquivo Gradle do módulo (nível do aplicativo) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle ), adicione o plug-in de serviços do Google:

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

Adicione SDKs do Firebase ao seu aplicativo

  1. No arquivo Gradle do módulo (nível do aplicativo) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle ), adicione a dependência para o Firebase Cloud Biblioteca de mensagens para Android. Recomendamos usar o Firebase Android BoM para controlar o controle de versão da biblioteca.

    Para uma experiência ideal com o Firebase Cloud Messaging, recomendamos ativar o Google Analytics no seu projeto do Firebase e adicionar o SDK do Firebase para Google Analytics ao seu aplicativo.

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

    Ao usar o Firebase Android BoM , seu aplicativo sempre usará versões compatíveis das bibliotecas do Firebase Android.

    (Alternativa) Adicionar dependências da biblioteca Firebase sem usar o BoM

    Se você optar por não usar o Firebase BoM, deverá especificar cada versão da biblioteca do Firebase em sua linha de dependência.

    Observe que se você usa várias bibliotecas do Firebase no seu aplicativo, é altamente recomendável usar a BoM para gerenciar as versões da biblioteca, o que garante que todas as versões sejam compatíveis.

    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.4.1")
    implementation("com.google.firebase:firebase-analytics:21.6.1")
}
    Procurando um módulo de biblioteca específico para Kotlin? A partir de outubro de 2023 (Firebase BoM 32.5.0) , tanto os desenvolvedores Kotlin quanto os Java podem depender do módulo da biblioteca principal (para obter detalhes, consulte o FAQ sobre esta iniciativa ).

  2. Sincronize seu projeto Android com arquivos Gradle.

Inscrever o aplicativo cliente em um tópico

Os aplicativos cliente podem assinar qualquer tópico existente ou podem criar um novo tópico. Quando um aplicativo cliente assina um novo nome de tópico (um que ainda não existe para seu projeto do Firebase), um novo tópico com esse nome é criado no FCM e qualquer cliente pode subscrevê-lo posteriormente.

Para assinar um tópico, o aplicativo cliente chama subscribeToTopic() Firebase Cloud Messaging com o nome do tópico FCM. Este método retorna um Task , que pode ser usado por um ouvinte de conclusão para determinar se a assinatura 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 assinatura, o aplicativo cliente chama o Firebase Cloud Messaging unsubscribeFromTopic() com o nome do tópico.

Receber e lidar com mensagens de tópico

O FCM entrega mensagens de tópico da mesma forma que outras mensagens downstream.

Para receber mensagens, use um serviço que estenda FirebaseMessagingService . Seu serviço deve substituir os retornos de chamada onMessageReceived e onDeletedMessages .

A janela de tempo para lidar com uma mensagem pode ser inferior a 20 segundos, dependendo dos atrasos ocorridos antes da chamada onMessageReceived , incluindo atrasos do sistema operacional, tempo de inicialização do aplicativo, thread principal sendo bloqueado por outras operações ou chamadas onMessageReceived anteriores demorando muito. Após esse período, vários comportamentos do sistema operacional, como a eliminação de processos do Android ou os limites de execução em segundo plano do Android O, podem interferir na sua capacidade de concluir o trabalho.

onMessageReceived é fornecido para a maioria dos tipos de mensagens, com as seguintes exceções:

  • Mensagens de notificação entregues quando seu aplicativo está em segundo plano . Nesse caso, a notificação é entregue na bandeja do sistema do dispositivo. Um toque do usuário em uma notificação abre o inicializador de aplicativos por padrão.

  • Mensagens com notificação e carga de dados, quando recebidas em segundo plano . Nesse caso, a notificação é entregue na bandeja do sistema do dispositivo, e a carga útil de dados é entregue nos extras da intenção da sua atividade do iniciador.

Resumindo:

Estado do aplicativo Notificação Dados Ambos
Primeiro plano onMessageReceived onMessageReceived onMessageReceived
Fundo Bandeja do sistema onMessageReceived Notificação: bandeja do sistema
Dados: em extras da intenção.
Para obter mais informações sobre tipos de mensagens, consulte Notificações e mensagens de dados .

Edite o manifesto do aplicativo

Para usar FirebaseMessagingService , você precisa adicionar o seguinte ao manifesto do seu aplicativo:

<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, é recomendável definir valores padrão para personalizar a aparência das notificações. Você pode especificar um ícone padrão personalizado e uma cor padrão personalizada que serão aplicadas sempre que valores equivalentes não forem definidos na carga de notificação.

Adicione estas linhas dentro da tag application para definir o ícone padrão personalizado e a cor personalizada:

<!-- 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 padrão personalizado para

  • Todas as mensagens de notificação enviadas pelo compositor de notificações .
  • Qualquer mensagem de notificação que não defina explicitamente o ícone na carga de notificação.

O Android usa a cor padrão personalizada para

  • Todas as mensagens de notificação enviadas pelo compositor de notificações .
  • Qualquer mensagem de notificação que não defina explicitamente a cor na carga de notificação.

Se nenhum ícone padrão personalizado for definido e nenhum ícone for definido na carga de notificação, o Android exibirá o ícone do aplicativo renderizado em branco.

Substituir onMessageReceived

Ao substituir o método FirebaseMessagingService.onMessageReceived , você pode executar ações com base no objeto RemoteMessage recebido e obter 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, o FCM pode não entregar uma mensagem. Isso ocorre quando há muitas mensagens (>100) pendentes para seu aplicativo em um dispositivo específico no momento da conexão ou se o dispositivo não estiver conectado ao FCM há mais de um mês. Nesses casos, você poderá receber um retorno de chamada para FirebaseMessagingService.onDeletedMessages() . Quando a instância do aplicativo receber esse retorno de chamada, ela deverá realizar uma sincronização completa com o servidor do seu aplicativo. Se você não enviou uma mensagem para o aplicativo nesse dispositivo nas últimas quatro semanas, o FCM não chamará onDeletedMessages() .

Lidar com mensagens de notificação em um aplicativo em segundo plano

Quando seu aplicativo está em segundo plano, o Android direciona as mensagens de notificação para a bandeja do sistema. Um toque do usuário na notificação abre o inicializador de aplicativos por padrão.

Isso inclui mensagens que contêm notificação e carga útil de dados (e todas as mensagens enviadas do console do Notificações). Nesses casos, a notificação é entregue na bandeja do sistema do dispositivo, e a carga de dados é entregue nos extras da intenção da sua atividade do iniciador.

Para obter informações sobre a entrega de mensagens no seu aplicativo, consulte o painel de relatórios do FCM , que registra o número de mensagens enviadas e abertas em dispositivos Apple e Android, juntamente com dados de "impressões" (notificações vistas pelos usuários) para aplicativos Android.

Criar solicitações de envio

Depois de criar um tópico, seja inscrevendo instâncias do aplicativo cliente no tópico no lado do cliente ou por meio da API do servidor , você poderá enviar mensagens para o tópico. Se esta for a primeira vez que você cria solicitações de envio para o FCM, consulte o guia do ambiente do seu servidor e do FCM para obter informações importantes sobre antecedentes e configuração.

Na sua lógica de envio no backend, especifique o nome do tópico desejado conforme mostrado:

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

Pitão

# 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

Ir

// 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);

DESCANSAR

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 condição a seguir enviará mensagens para dispositivos inscritos em TopicA e TopicB ou TopicC :

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

O FCM primeiro avalia quaisquer condições entre parênteses e depois avalia a expressão da esquerda para a direita. Na expressão acima, um usuário inscrito em um único tópico não recebe a mensagem. Da mesma forma, um usuário que não assina o TopicA não recebe a mensagem. Estas combinações recebem:

  • TopicA e TopicB
  • TopicA e TopicC

Você pode incluir até cinco tópicos em 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

Pitão

# 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

Ir

// 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);

DESCANSAR

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óximos passos