Recibe mensajes en un cliente de JavaScript

El comportamiento de los mensajes varía si la página se encuentra en primer plano (tiene el “enfoque”) o en segundo plano, escondida detrás de otras pestañas, o completamente cerrada. En todos los casos, la página debe controlar la devolución de llamada onMessage. No obstante, en los casos en segundo plano, es posible que también debas controlar onBackgroundMessage o configurar la notificación en pantalla para permitir que el usuario lleve la app web al primer plano.

Estado de la app	Notificación	Datos	Ambos
Primer plano	onMessage	onMessage	onMessage
En segundo plano (service worker)	onBackgroundMessage (notificación en pantalla que se muestra automáticamente)	onBackgroundMessage	onBackgroundMessage (notificación en pantalla que se muestra automáticamente)

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

Importante: En esta guía, se menciona la inicialización de Firebase en un servicio de trabajo. Para usar el SDK modular en un service worker, debes agrupar tu archivo de servicio de trabajo, ya que los módulos de ES son relativamente nuevos y no son compatibles con muchos sistemas (consulta Módulos de ES en service workers). Si no quieres agrupar tu archivo de service worker, puedes usar la API con espacio de nombres que proporcionan los paquetes de compatibilidad. Para ver cómo puedes usar agrupadores de módulos con Firebase, consulta Usa agrupadores de módulos con Firebase.

Maneja mensajes cuando la aplicación web está en primer plano

Para recibir el evento onMessage, tu app debe definir el service worker de mensajería de Firebase en firebase-messaging-sw.js. Otra opción es proporcionar un service worker existente al SDK mediante getToken(): Promise<string>.

Web

Obtén más información sobre la API modular web que admite la eliminación de código no utilizado y realiza la actualización 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

// 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 la app se encuentra en primer plano (el usuario está viendo tu página web actualmente), puedes recibir cargas útiles de datos y notificaciones directamente en la página.

Web

Obtén más información sobre la API modular web que admite la eliminación de código no utilizado y realiza la actualización 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

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

Maneja mensajes cuando la app web está en segundo plano

Todos los mensajes que se reciben mientras la app está en segundo plano desencadenan una notificación en pantalla en el navegador. Puedes especificar opciones para esta notificación, como un título o una acción de clic, ya sea en la solicitud de envío del servidor de apps o mediante el uso de la lógica del service worker en el cliente.

Las acciones de clic son compatibles únicamente con las URLs HTTPS seguras.

Configura las opciones de notificación en la solicitud de envío

En el caso de los mensajes de notificación que se envían desde el servidor de apps, la API de JavaScript de FCM es compatible con la clave fcm_options.link. Por lo general, se asigna a la clave una página de la aplicación web, como en este ejemplo:

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 vínculo apunta a una página que ya está abierta en una pestaña del navegador, la pestaña se pondrá en primer plano cuando se haga clic en la notificación. Si la página no está abierta, se abrirá en una pestaña nueva cuando se haga clic en la notificación.

Debido a que los mensajes de datos no son compatibles con fcm_options.link, es conveniente que agregues una carga útil de notificación a todos los mensajes de datos. También puedes administrar notificaciones con el service worker.

Para ver una explicación de la diferencia entre los mensajes de notificación y los de datos, consulta los tipos de mensaje.

Nota: Para enviar mensajes a temas, usa el SDK de Admin a fin de suscribir las instancias de la app a los temas. Si quieres usar la API de Admin de FCM, primero debes seguir los pasos en Agrega el SDK de Firebase Admin a tu servidor para inicializar el SDK.

Configura las opciones de notificación en el service worker

Para los mensajes de datos, puedes configurar las opciones de notificación en el service worker. Primero, inicializa tu app en el service worker:

Web

Obtén más información sobre la API modular web que admite la eliminación de código no utilizado y realiza la actualización 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

// 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 las opciones, llama a onBackgroundMessage en firebase-messaging-sw.js. En este ejemplo, crearemos una notificación con campos de título, ícono y cuerpo.

Web

Obtén más información sobre la API modular web que admite la eliminación de código no utilizado y realiza la actualización 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

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 deseas definir un comportamiento personalizado en el service worker cuando se hace clic en la notificación, asegúrate de configurar notificationclick antes de importar funciones o bibliotecas de FCM. De lo contrario, FCM puede reemplazar el comportamiento personalizado.

Prácticas recomendadas para las notificaciones

Si estás familiarizado con el envío de mensajes push a través de la Web, es posible que ya conozcas los lineamientos sobre las características de una buena notificación. En el caso de programadores que envían notificaciones a través de FCM para la Web, las consideraciones más importantes son la precisión y la relevancia. A continuación, te mostramos algunas recomendaciones específicas para que tus notificaciones sean precisas y relevantes:

• Usa el campo de ícono para enviar una imagen significativa. En diversos casos de uso, debería emplearse un logotipo de la empresa o app que los usuarios reconozcan con facilidad. En el caso de una aplicación de chat, podría ser la imagen de perfil del usuario remitente.
• Usa 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 uses este espacio valioso para el nombre de tu empresa o tu app. Para ello, usa el ícono.
• No uses el título ni el cuerpo de la notificación para mostrar el nombre de tu sitio web o dominio. Las notificaciones ya contienen el nombre de tu dominio.
• Agrega un fcm_options.link para dirigir al usuario de vuelta a tu aplicación web y enfocar la app en el navegador. En casos poco comunes en los que toda la información que debes transmitir cabe en la notificación, es posible que no necesites un vínculo.