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 (oculta atrás de outras guias) ou completamente fechada. Em todos os casos, a página precisa administrar o callback onMessage, mas em casos de segundo plano, também pode ser preciso administrar o onBackgroundMessage ou configurar a notificaçã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)	onBackgroundMessage (notificação aparece automaticamente)	onBackgroundMessage	onBackgroundMessage (notificação de exibição automática)

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

Importante: este guia menciona a inicialização do Firebase em um service worker. Para usar o SDK modular em um service worker, é necessário agrupar o arquivo do service worker, já que os módulos ES são relativamente novos e não têm suporte amplo. Consulte Módulos ES em service workers. Se você não quiser agrupar seu arquivo de worker de serviço, use a API com namespace fornecida pelos pacotes de compatibilidade. Para saber como usar os bundlers de módulo com o Firebase, consulte Como usar os bundlers de módulo com o Firebase.

Processar mensagens quando seu app da Web estiver em primeiro plano

Para receber o evento onMessage, seu app precisa definir o service worker de mensagens do Firebase em firebase-messaging-sw.js. Se preferir, forneça um service worker ao SDK usando o getToken(): Promise<string>.

Web

Saiba mais sobre a API modular da Web que oferece suporte a tree shaking e o upgrade da API com namespace.

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// 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
const firebaseApp = 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 = getMessaging(firebaseApp);
messaging_init_in_sw.js

Web

// 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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.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();
service-worker.js

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

Web

Saiba mais sobre a API modular da Web que oferece suporte a tree shaking e o upgrade da API com namespace.

// 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.onBackgroundMessage` handler.
import { getMessaging, onMessage } from "firebase/messaging";

const messaging = getMessaging();
onMessage(messaging, (payload) => {
  console.log('Message received. ', payload);
  // ...
});
messaging_receive_message.js

Web

// 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.onBackgroundMessage` handler.
messaging.onMessage((payload) => {
  console.log('Message received. ', payload);
  // ...
});
index.js

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 dessa 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.

As ações de clique aceitam apenas URLs HTTPS seguros.

Configurar opções de notificação na solicitação de envio

Para mensagens de notificações enviadas pelo servidor do app, a API FCM JavaScript é compatível com a chave fcm_options.link. Em geral, isso é definido como 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 gerenciar notificações com o service worker.

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

Observação: para enviar mensagens a tópicos, use o SDK Admin para fazer a inscrição de instâncias de app em tópicos. Para usar a API Admin FCM, primeiro siga as etapas que estão na página Adicionar o SDK Admin do Firebase ao seu servidor para inicializar o SDK.

Como 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:

Web

Saiba mais sobre a API modular da Web que oferece suporte a tree shaking e o upgrade da API com namespace.

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// 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
const firebaseApp = 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 = getMessaging(firebaseApp);
messaging_init_in_sw.js

Web

// 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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.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();
service-worker.js

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

Web

Saiba mais sobre a API modular da Web que oferece suporte a tree shaking e o upgrade da API com namespace.

import { getMessaging } from "firebase/messaging/sw";
import { onBackgroundMessage } from "firebase/messaging/sw";

const messaging = getMessaging();
onBackgroundMessage(messaging, (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'
  };

  self.registration.showNotification(notificationTitle,
    notificationOptions);
});
messaging_on_background_message.js

Web

messaging.onBackgroundMessage((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'
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});
service-worker.js

Observação: caso você queira definir um comportamento personalizado no service worker, quando houver um clique na notificação, processe notificationclick antes de importar funções ou bibliotecas do FCM. Caso contrário, o FCM pode substituir o comportamento personalizado.

Práticas recomendadas para notificações

Se você conhece mensagens push para Web, já deve ter lido as diretrizes gerais sobre os elementos de uma boa notificação. Para desenvolvedores que enviam notificações usando o 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 "icon" 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 chat, pode ser a imagem do perfil do remetente.
• Use o campo "title" 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 para incluir um link que direcionará o usuário para seu app da Web e colocará o app em primeiro plano no navegador. Nos raros casos em que todas as informações necessárias para transmissão couberem na notificação, o link poderá ser desnecessário.