Enviar mensagens para tópicos na Web/JavaScript

Dependendo do modelo de publicação/assinatura, as mensagens de tópico do FCM permitem que você envie uma mensagem a vários dispositivos que assinaram um tópico específico. Você escreve as mensagens em tópicos conforme necessário, e o FCM processa de maneira confiável o encaminhamento e a entrega delas aos dispositivos certos.

Por exemplo, os usuários de um aplicativo de previsão de marés podem assinar um tópico de "alertas de correntes de maré" e receber notificações das melhores condições de pesca em água salgada em áreas específicas. Os usuários de um app sobre esportes podem assinar atualizações automáticas de placares de jogos em tempo real dos times favoritos.

Alguns lembretes sobre os tópicos:

  • As mensagens em tópicos são mais adequadas a conteúdo de clima ou outras informações disponibilizadas publicamente.
  • As mensagens em tópicos são otimizadas para capacidade, não para latência. Para enviar mensagens com rapidez e segurança para dispositivos únicos ou pequenos grupos de dispositivos, segmente-as para tokens em vez de tópicos.
  • Se for necessário enviar mensagens a vários dispositivos por usuário, use as mensagens para grupos de dispositivos.
  • As mensagens em tópicos permitem um número ilimitado de assinaturas para cada tópico. No entanto, o FCM impõe limites nessas áreas:
    • Uma instância de app pode assinar no máximo 2.000 tópicos.
    • Se você estiver usando a importação em lote para assinar instâncias de app, cada solicitação estará limitada a 1.000 instâncias.
    • A frequência de novas assinaturas é limitada por projeto. Se você enviar muitas solicitações de assinatura em um curto período de tempo, os servidores FCM responderão com uma resposta 429 RESOURCE_EXHAUSTED ("cota excedida"). Tente novamente com retirada exponencial.

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 Google Instance ID server API. Chame a Instance ID API 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 de 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 desta forma:

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.

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

Receber e processar mensagens de tópico

O FCM entrega as mensagens de tópico da mesma maneira que outras mensagens downstream. A forma de processamento das mensagens no cliente depende do estado de primeiro plano/segundo plano da página da Web e de outros fatores descritos nesta seção.

O comportamento das mensagens varia, dependendo se a página está em primeiro plano (em foco), em segundo plano (escondida atrás de outras guias) ou completamente fechada. Em todos os casos, o callback onMessage precisa ser processado pela página. Porém, se ela estiver em segundo plano, também será necessário processar setBackgroundMessageHandler ou configurar a notificação de exibição para permitir que o usuário abra o 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 existente 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/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-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(function(payload) {
  console.log('Message received. ', payload);
  // ...
});

Tratar mensagens quando seu app da Web está 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 dessa notificação, como um título ou uma ação de clique, na solicitação de envio a partir do servidor de 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 a partir do servidor do app, a API FCM JavaScript é compatível com a chave click_action. 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 a ação de clique 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 click_action, 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 mensagens de notificação e de dados em Tipos de mensagens.

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

Para as mensagens de notificação e 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/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

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

Para definir as opções, chame setBackgroundmensagemHandler em firebase-messaging-sw.js. Neste exemplo, definimos as opções de título, corpo, ícone e ação de clique.

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

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

Criar solicitações de envio

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

Solicitação HTTP POST de tópico

Enviar para um único tópico:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
  "to" : "/topics/foo-bar",
  "priority" : "high",
  "notification" : {
    "body" : "This is a Firebase Cloud Messaging Topic Message!",
    "title" : "FCM Message",
  }
}

Resposta HTTP de tópico

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

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

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

Próximas etapas

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.