Recibir mensajes en un cliente JavaScript

El comportamiento de los mensajes difiere dependiendo de si la página está en primer plano (tiene foco), o en segundo plano, escondida detrás de otras pestañas o completamente cerrada. En todos los casos, la página debe manejar la devolución de llamada onMessage , pero en casos en segundo plano es posible que también necesite manejar onBackgroundMessage o configurar la notificación de visualización para permitir que el usuario coloque su aplicación web en primer plano.

Estado de la aplicación	Notificación	Datos	Ambos
Primer plano	onMessage	onMessage	onMessage
Antecedentes (trabajador de servicios)	onBackgroundMessage (la notificación se muestra automáticamente)	onBackgroundMessage	onBackgroundMessage (la notificación se muestra automáticamente)

El ejemplo de inicio rápido de JavaScript muestra todo el código necesario para recibir mensajes.

Manejar mensajes cuando su aplicación web está en primer plano

Para recibir el evento onMessage , tu aplicación debe definir el trabajador del servicio de mensajería de Firebase en firebase-messaging-sw.js . Alternativamente, puede proporcionar un trabajador de servicio existente al SDK a través de getToken(): Promise<string> .

Web modular API

Obtenga más información sobre la API web modular que se puede sacudir en árbol y actualice desde la API con espacio de nombres.

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 namespaced API

// 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/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/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();
service-worker.js

Cuando su aplicación está en primer plano (el usuario está viendo su página web actualmente), puede recibir cargas útiles de datos y notificaciones directamente en la página.

Web modular API

Obtenga más información sobre la API web modular que se puede sacudir en árbol y actualice desde la API con espacio de nombres.

// 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 namespaced API

// 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

Manejar mensajes cuando su aplicación web está en segundo plano

Todos los mensajes recibidos mientras la aplicación está en segundo plano activan una notificación en el navegador. Puede especificar opciones para esta notificación, como el título o la acción de hacer clic, ya sea en la solicitud de envío desde el servidor de su aplicación o utilizando la lógica del trabajador del servicio en el cliente.

Las acciones de clic solo admiten URL HTTPS seguras.

Configurar opciones de notificación en la solicitud de envío

Para los mensajes de notificación enviados desde el servidor de aplicaciones, la API de JavaScript de FCM admite la clave fcm_options.link . Normalmente, esto se configura en una página de su aplicación 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"
      }
    }
  }
}

Si el valor del enlace apunta a una página que ya está abierta en una pestaña del navegador, un clic en la notificación pone esa pestaña en primer plano. Si la página aún no está abierta, al hacer clic en una notificación se abre la página en una nueva pestaña.

Debido a que los mensajes de datos no son compatibles con fcm_options.link , se recomienda agregar una carga útil de notificación a todos los mensajes de datos. Alternativamente, puede manejar notificaciones utilizando el trabajador del servicio.

Para obtener una explicación de la diferencia entre mensajes de notificación y de datos, consulte Tipos de mensajes .

Nota: Para enviar mensajes a temas , utilice el SDK de administración para suscribir instancias de aplicaciones a temas. Para usar la API de Admin FCM, primero debe seguir los pasos en Agregar el SDK de administrador de Firebase a su servidor para inicializar el SDK.

Configuración de opciones de notificación en el trabajador del servicio.

Para mensajes de datos, puede configurar opciones de notificación en el trabajador del servicio. Primero, inicializa tu aplicación en el trabajador de servicio:

Web modular API

Obtenga más información sobre la API web modular que se puede sacudir en árbol y actualice desde la API con espacio de nombres.

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 namespaced API

// 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/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/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();
service-worker.js

Para configurar opciones, llame onBackgroundMessage en firebase-messaging-sw.js . En este ejemplo, creamos una notificación con campos de título, cuerpo e ícono.

Web modular API

Obtenga más información sobre la API web modular que se puede sacudir en árbol y actualice desde la API con espacio de nombres.

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 namespaced API

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

Nota: Si desea definir un comportamiento personalizado en el trabajador del servicio cuando se hace clic en la notificación, asegúrese de controlar notificationclick antes de importar funciones o bibliotecas de FCM. De lo contrario, FCM puede sobrescribir el comportamiento personalizado.

Mejores prácticas para notificaciones

Si está familiarizado con la mensajería push para la web, es posible que ya haya leído las pautas generales sobre lo que constituye una buena notificación . Para los desarrolladores que envían notificaciones a través de FCM para Web, las consideraciones más importantes son la precisión y la relevancia. Aquí hay algunas recomendaciones específicas para mantener sus notificaciones precisas y relevantes:

• Utilice el campo del icono para enviar una imagen significativa. En muchos casos de uso, este debería ser el logotipo de una empresa o aplicación que los usuarios reconozcan inmediatamente. O, para una aplicación de chat, podría ser la imagen de perfil del usuario emisor.
• Utilice el campo de título para expresar la naturaleza precisa del mensaje. Por ejemplo, "Jimmy respondió" transmite información más precisa que "Mensaje nuevo". No utilice este valioso espacio para el nombre de su empresa o aplicación; utilice el icono para ese fin.
• No utilice el título o el cuerpo de la notificación para mostrar el nombre o dominio de su sitio web; Las notificaciones ya contienen su nombre de dominio.
• Agregue fcm_options.link , generalmente para vincular al usuario a su aplicación web y resaltarla en el navegador. En casos excepcionales en los que toda la información que necesita transmitir puede caber en la notificación, es posible que no necesite un enlace.