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.

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

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

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

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

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.

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

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

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

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.