Ir para o console

Receber mensagens em um cliente JavaScript

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, a página precisa processar o callback onMessage, mas, em casos em segundo plano, talvez você precise manipular 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

A amostra de início rápido do JavaScript demonstra todo o código necessário para receber mensagens.

Como processar 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 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": {
    "token": "eEz-Q2sG8nQ:APA91bHJQRT0JJ..."
    "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 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);
});

Práticas recomendadas para notificações

Se estiver familiarizado com mensagens push para a Web, talvez você já tenha lido as diretrizes gerais sobre os elementos de uma boa notificação. Para desenvolvedores que enviam notificações por meio do FCM para Web, as considerações mais importantes são a precisão e a relevância. Estas são algumas recomendações específicas para manter suas notificações precisas e relevantes:

  • Use o campo ícone para enviar uma imagem significativa. Para muitos casos de uso, esse deve ser um logotipo da empresa ou do app que os usuários reconhecem imediatamente. Ou, para um aplicativo de bate-papo, pode ser a imagem do perfil do remetente.
  • Use o campo título para expressar a natureza precisa da mensagem. Por exemplo, "Jimmy respondeu" transmite informações mais precisas do que "Nova mensagem". Não use esse espaço valioso para o nome da empresa ou do app, use o ícone para esse fim.
  • Não use o título ou o corpo da notificação para exibir o nome do site ou o domínio; notificações já contêm seu nome de domínio.
  • Adicione fcm_options.link, normalmente para vincular o usuário ao seu app da Web e para colocá-lo em foco no navegador. Nos casos em que todas as informações que você precisa transmitir couberem na notificação, o link poderá ser desnecessário.