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

O comportamento das mensagens difere dependendo se a página está em primeiro plano (tem foco), ou em segundo plano, escondida 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 coloque seu aplicativo da Web em primeiro plano.

estado do aplicativo Notificação Dados Ambos
Primeiro plano onMessage onMessage onMessage
Plano de fundo (trabalhador de serviço) onBackgroundMessage (notificação de exibição mostrada automaticamente) onBackgroundMessage onBackgroundMessage (notificação de exibição mostrada automaticamente)

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

Lidar com mensagens quando seu aplicativo da Web estiver em primeiro plano

Para receber o evento onMessage , seu aplicativo deve definir o trabalhador do serviço 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 da 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.

Definindo 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 aponta 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 abrirá a página em uma nova guia.

Como as mensagens de dados não oferecem suporte fcm_options.link , é recomendável adicionar uma carga útil de notificação a todas as mensagens de dados. Como alternativa, você pode lidar com notificações usando o service worker.

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

Definindo 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 de título, corpo e ícone.

Web version 9

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

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 constitui 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 de 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 essa finalidade.
  • 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 cabem na notificação, talvez você não precise de um link.