Enviar mensagens a vários dispositivos

O Firebase Cloud Messaging oferece duas maneiras de direcionar uma mensagem a vários dispositivos:

Este tutorial concentra-se no envio de mensagens de tópicos a partir do servidor do app, usando os protocolos HTTP ou XMPP para o FCM, e no recebimento e processamento dessas mensagens em um app da Web. Vamos abordar o processamento de mensagens para apps em segundo plano e primeiro plano.

Configurar o SDK

Se você configurou um app cliente em JavaScript para o FCM ou seguiu as instruções para receber mensagens, talvez as etapas abordadas nesta seção já tenham sido concluídas.

Adicionar o Firebase a seu projeto JavaScript

Adicione o Firebase a seu projeto JavaScript, caso ainda não tenha feito isso.

Recuperar um objeto de mensagem

// Retrieve Firebase Messaging object.
const messaging = firebase.messaging();

Acessar o token de registro

Esta seção descreve como recuperar o token de registro de uma instância do app e como monitorar os eventos de atualização dele. Como o token pode passar por um rodízio após a primeira inicialização, recomendamos que você recupere o token de registro mais atualizado.

O token de registro pode mudar quando:

  • o app da Web exclui o token de registro;
  • o usuário exclui dados do navegador. Nesse caso, chame getToken para recuperar o novo token.

Recuperar o token de registro atual

Quando você precisar recuperar o token atual, chame getToken. Se a permissão de notificação não tiver sido concedida, esse método solicitará ao usuário permissões de notificação. Caso contrário, ele retorna um token ou rejeita a promessa devido a um erro.

O serviço de mensagens requer um arquivo firebase-messaging-sw.js. A menos que você já tenha um arquivo firebase-messaging-sw.js, crie um arquivo vazio com esse nome e coloque-o na raiz do seu domínio antes de recuperar um token. Você pode adicionar conteúdo significativo ao arquivo posteriormente no processo de configuração do cliente.

Para recuperar o token atual:

// Get Instance ID token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken().then((currentToken) => {
  if (currentToken) {
    sendTokenToServer(currentToken);
    updateUIForPushEnabled(currentToken);
  } else {
    // Show permission request.
    console.log('No Instance ID token available. Request permission to generate one.');
    // Show permission UI.
    updateUIForPushPermissionRequired();
    setTokenSentToServer(false);
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  showToken('Error retrieving Instance ID token. ', err);
  setTokenSentToServer(false);
});

Monitorar a atualização do token

O retorno de chamada de onTokenRefresh é acionado sempre que um novo token é gerado. Portanto, chamar getToken nesse contexto garantirá o acesso a um token de registro atual e disponível.

// Callback fired if Instance ID token is updated.
messaging.onTokenRefresh(() => {
  messaging.getToken().then((refreshedToken) => {
    console.log('Token refreshed.');
    // Indicate that the new Instance ID token has not yet been sent to the
    // app server.
    setTokenSentToServer(false);
    // Send Instance ID token to app server.
    sendTokenToServer(refreshedToken);
    // ...
  }).catch((err) => {
    console.log('Unable to retrieve refreshed token ', err);
    showToken('Unable to retrieve refreshed token ', err);
  });
});

Depois de receber o token, envie-o para o servidor do app e armazene-o usando seu método preferido. Você pode usar a API Instance ID Server para receber informações sobre inscrições.

Inscrever o app cliente em um tópico

Com um token de registro e um nome de tópico, é possível adicionar o token ao tópico usando a API Google Instance ID server. Chame a API Instance ID nesse ponto de extremidade fornecendo o token de registro da instância do app e o nome do tópico:

 https://iid.googleapis.com/iid/v1/<REGISTRATION_TOKEN>/rel/topics/<TOPIC_NAME>

Por exemplo, para inscrever uma instância do app em um tópico nomeado como "movies", envie a seguinte solicitação POST do seu servidor para o ponto de extremidade adicionando a chave de API do servidor ao cabeçalho de autorização conforme segue:

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Nunca envie esse tipo de solicitação do cliente devido à sensibilidade da chave do servidor.

Uma solicitação bem-sucedida retorna HTTP 200 OK. Para mais informações sobre respostas de erro e envio de solicitações em lote, consulte Criar mapas de relacionamentos para instâncias de um app.

É possível transferir uma lista de tokens de registro para o método de inscrição do SDK Admin do Firebase para fazer a inscrição dos dispositivos correspondentes em um tópico:

Node.js

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Subscribe the devices corresponding to the registration tokens to the
// topic.
admin.messaging().subscribeToTopic(registrationTokens, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully subscribed to topic:', response);
  })
  .catch(function(error) {
    console.log('Error subscribing to topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Subscribe the devices corresponding to the registration tokens to the
// topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were subscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Subscribe the devices corresponding to the registration tokens to the
# topic.
response = messaging.subscribe_to_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were subscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Subscribe the devices corresponding to the registration tokens to the
// topic.
response, err := client.SubscribeToTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were subscribed successfully")

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};

// Subscribe the devices corresponding to the registration tokens to the
// topic
var response = await FirebaseMessaging.DefaultInstance.SubscribeToTopicAsync(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were subscribed successfully");

A API Admin FCM também permite que você cancele a inscrição de dispositivos em um tópico por meio da transferência de tokens de registro para o método apropriado:

Node.js

// These registration tokens come from the client FCM SDKs.
var registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
admin.messaging().unsubscribeFromTopic(registrationTokens, topic)
  .then(function(response) {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully unsubscribed from topic:', response);
  })
  .catch(function(error) {
    console.log('Error unsubscribing from topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().unsubscribeFromTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were unsubscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Unubscribe the devices corresponding to the registration tokens from the
# topic.
response = messaging.unsubscribe_from_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were unsubscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
response, err := client.UnsubscribeFromTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were unsubscribed successfully")

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};

// Unsubscribe the devices corresponding to the registration tokens from the
// topic
var response = await FirebaseMessaging.DefaultInstance.UnsubscribeFromTopicAsync(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were unsubscribed successfully");

Os métodos subscribeToTopic() e unsubscribeFromTopic() resultam em um objeto que contém a resposta do FCM. O tipo de retorno tem o mesmo formato, independentemente do número de tokens de registro especificados na solicitação.

Em caso de erro (falhas de autenticação, token ou tópico inválido etc.), esses métodos resultam em um erro. Para ver uma lista completa de IDs do erro, incluindo descrições e etapas de solução de problemas, consulte Erros da API Admin FCM.

Receber e processar mensagens de tópicos

O comportamento das mensagens varia dependendo se a página está em primeiro plano (em foco), em segundo plano (oculta atrás de outras guias) ou completamente fechada. Em todos os casos, a página precisa administrar o retorno de chamada onMessage, mas em casos de segundo plano, também pode ser preciso administrar o setBackgroundMessageHandler ou configurar a notificação de exibição para permitir que o usuário coloque seu app da Web em primeiro plano.

Estado do app Notificação Dados Ambos
Primeiro plano onMessage onMessage onMessage
Segundo plano (service worker) Notificação exibida pelo SDK setBackgroundMessageHandler Notificação exibida pelo SDK

Tratar mensagens quando seu app da Web está em primeiro plano

Para receber o evento de onMessage, seu app precisa definir o service worker de mensagens do Firebase em firebase-messaging-sw.js. Se preferir, especifique um service worker com useServiceWorker.

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/7.15.0/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/7.15.0/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

Quando seu app estiver em primeiro plano (o usuário está visualizando a página da Web), você pode receber payloads de dados e de notificações diretamente na página.

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.setBackgroundMessageHandler` handler.
messaging.onMessage((payload) => {
  console.log('Message received. ', payload);
  // ...
});

Processar mensagens quando seu app da Web estiver em segundo plano

Todas as mensagens recebidas enquanto o app está em segundo plano acionam uma notificação de exibição no navegador. Especifique as opções desta notificação, como um título ou uma ação de clique, na solicitação de envio a partir do servidor do app ou usando a lógica do service worker no cliente.

Como configurar opções na solicitação de envio

Para mensagens de notificação enviadas pelo servidor do app, a API FCM JavaScript é compatível com a chave fcm_options.link. Em geral, isso é definido para uma página no seu app da Web:

https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>

{
  "message": {
    "topic": "matchday"
    "notification": {
      "title": "Background Message Title",
      "body": "Background message body"
    },
    "webpush": {
      "fcm_options": {
        "link": "https://dummypage.com"
      }
    }
  }
}

Se o valor do link apontar para uma página que já está aberta em uma guia do navegador, um clique na notificação trará essa guia para o primeiro plano. Se a página ainda não estiver aberta, um clique na notificação abrirá a página em uma nova guia.

Como as mensagens de dados não aceitam fcm_options.link, recomenda-se adicionar um payload de notificação a todas as mensagens de dados. Como alternativa, é possível tratar notificações usando o service worker.

Veja uma explicação sobre a diferença entre as mensagens de notificação e de dados em Tipos de mensagem.

Configurar opções de notificação no service worker

Para mensagens de dados, é possível definir opções de notificação no service worker. Primeiro, inicialize seu app no service worker:

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here, other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/7.15.0/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/7.15.0/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

Para definir opções, chame setBackgroundMessageHandler em firebase-messaging-sw.js. Neste exemplo, criamos uma notificação com os campos title, body e icon.

messaging.setBackgroundMessageHandler(function(payload) {
  console.log('[firebase-messaging-sw.js] Received background message ', payload);
  // Customize notification here
  const notificationTitle = 'Background Message Title';
  const notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  return self.registration.showNotification(notificationTitle,
    notificationOptions);
});

Criar solicitações de envio

Enviar mensagens para um tópico do Firebase Cloud Messaging do servidor é semelhante ao envio para um dispositivo individual ou um grupo de usuários. O servidor do app define a chave to com um valor como /topics/yourTopic. Os desenvolvedores podem escolher um nome de tópico que corresponda à seguinte expressão regular: "/topics/[a-zA-Z0-9-_.~%]+".

Solicitação HTTP POST de tópico

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",
      }
   }
}

Enviar com 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!",
  },
  "topic" : "foo-bar"
}' "https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1"

Resposta HTTP de tópico

{
    "name": "projects/myproject-b5ae1/messages/5735743068807585451"
}

Mensagem XMPP de tópico

Enviar para um único tópico:

<message id="">
  <gcm xmlns="google:mobile:data">
{
  "to" : /topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}
  </gcm>
</message>

Resposta XMPP de tópico

//Success example:
{
  "message_id": "1023456"
}

//failure example:
{
  "error": "TopicsMessageRateExceeded"
}