Acompanhe tudo o que foi anunciado no Firebase Summit e saiba como usar o Firebase para acelerar o desenvolvimento de apps e executá-los com confiança. Saiba mais

Receber mensagens em um cliente JavaScript

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O comportamento das mensagens difere dependendo se a página está em primeiro plano (tem foco), ou em segundo plano, oculta atrás de outras guias ou completamente fechada. Em todos os casos, a página deve lidar com o retorno de chamada onMessage , mas em casos de segundo plano, você também pode precisar lidar com onBackgroundMessage ou configurar a notificação de exibição para permitir que o usuário traga seu aplicativo da Web para o primeiro plano.

Estado do aplicativo Notificação Dados Ambos
Primeiro plano onMessage onMessage onMessage
Histórico (funcionário de serviço) onBackgroundMessage (exibir notificação mostrada automaticamente) onBackgroundMessage onBackgroundMessage (exibir notificação mostrada automaticamente)

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

Lidar com mensagens quando seu aplicativo Web estiver em primeiro plano

Para receber o evento onMessage , seu aplicativo deve definir o service worker de mensagens do Firebase em firebase-messaging-sw.js . Como alternativa, você pode fornecer um service worker existente ao SDK por meio de getToken(): Promise<string> .

Web version 9

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

Web version 8

// 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/9.2.0/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/9.2.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 aplicativo está em primeiro plano (o usuário está visualizando sua página da Web), você pode receber dados e cargas de notificação diretamente na página.

Web version 9

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

Web version 8

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

Lidar com mensagens quando seu aplicativo Web estiver em segundo plano

Todas as mensagens recebidas enquanto o aplicativo está em segundo plano acionam uma notificação de exibição no navegador. Você pode especificar opções para essa notificação, como título ou ação de clique, na solicitação de envio do servidor de aplicativos ou usando a lógica do service worker no cliente.

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

Para mensagens de notificação enviadas do servidor de aplicativos, a API JavaScript do FCM oferece suporte à chave fcm_options.link . Normalmente, isso é definido para uma página em seu aplicativo 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 traz essa guia para o primeiro plano. Se a página ainda não estiver aberta, um clique de notificação abre a página em uma nova guia.

Como as mensagens de dados não são compatíveis fcm_options.link , é recomendável adicionar uma carga de notificação a todas as mensagens de dados. Como alternativa, você pode manipular notificações usando o service worker.

Para obter uma explicação da diferença entre mensagens de notificação e de dados, consulte Tipos de mensagem .

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

Para mensagens de dados, você pode definir opções de notificação no service worker. Primeiro, inicialize seu aplicativo no service worker:

Web version 9

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

Web version 8

// 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/9.2.0/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/9.2.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 onBackgroundMessage em firebase firebase-messaging-sw.js . Neste exemplo, criamos uma notificação com os campos título, corpo e ícone.

Web version 9

import { getMessaging } from "firebase/messaging";
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);
});

Web version 8

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

Práticas recomendadas para notificações

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

  • Use o campo de ícone para enviar uma imagem significativa. Para muitos casos de uso, deve ser um logotipo de empresa ou aplicativo que seus usuários reconheçam imediatamente. Ou, para um aplicativo de bate-papo, pode ser a imagem do perfil do usuário remetente.
  • Use o campo de 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 sua empresa ou aplicativo — use o ícone para esse fim.
  • Não use o título ou o corpo da notificação para exibir o nome ou domínio do seu site; notificações já contêm seu nome de domínio.
  • Adicione fcm_options.link , geralmente para vincular o usuário de volta ao seu aplicativo da Web e colocá-lo em foco no navegador. Em casos raros em que todas as informações que você precisa transmitir podem caber na notificação, talvez você não precise de um link.