Recevoir des messages dans un client JavaScript

Le comportement des messages diffère selon que la page est au premier plan (mise au point), en arrière-plan (masquée derrière d'autres onglets) ou complètement fermée. Dans tous les cas, la page doit gérer le rappel onMessage. Toutefois, dans les cas en arrière-plan, vous devrez peut-être également gérer onBackgroundMessage ou configurer la notification d'affichage pour permettre à l'utilisateur de mettre votre application Web au premier plan.

État de l'application	Notification	Données	Les deux
Premier plan	onMessage	onMessage	onMessage
Arrière-plan (service worker)	onBackgroundMessage (notification d'affichage automatique)	onBackgroundMessage	onBackgroundMessage (notification d'affichage automatique)

L'exemple de démarrage rapide JavaScript montre tout le code nécessaire pour recevoir des messages.

Important : Ce guide mentionne l'initialisation de Firebase dans un service worker. Pour utiliser le SDK modulaire dans un service worker, vous devez regrouper votre fichier de service worker, car les modules ES sont relativement récents et ne sont pas largement pris en charge (voir Modules ES dans les service workers). Si vous ne souhaitez pas regrouper votre fichier de service worker, vous pouvez utiliser l'API avec espace de noms fournie par les packages de compatibilité. Pour découvrir comment utiliser des bundlers de modules avec Firebase, consultez Utiliser des bundlers de modules avec Firebase.

Gérer les messages lorsque votre application Web est au premier plan

Pour recevoir l'événement onMessage, votre application doit définir le service worker de messagerie Firebase dans firebase-messaging-sw.js. Vous pouvez également fournir un service worker existant au SDK via 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

Lorsque votre application est au premier plan (l'utilisateur consulte actuellement votre page Web), vous pouvez recevoir des charges utiles de données et de notifications directement sur la page.

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

Gérer les messages lorsque votre application Web est en arrière-plan

Tous les messages reçus lorsque l'application est en arrière-plan déclenchent une notification d'affichage dans le navigateur. Vous pouvez spécifier des options pour cette notification, comme le titre ou l'action au clic, soit dans la requête d'envoi depuis le serveur de votre application, soit à l'aide de la logique du service worker sur le client.

Les actions de clic n'acceptent que les URL HTTPS sécurisées.

Définir les options de notification dans la requête d'envoi

Pour les messages de notification envoyés depuis le serveur d'application, l'API JavaScript FCM est compatible avec la clé fcm_options.link. En général, il s'agit d'une page de votre application 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 la valeur du lien pointe vers une page déjà ouverte dans un onglet du navigateur, un clic sur la notification fait passer cet onglet au premier plan. Si la page n'est pas déjà ouverte, un clic sur la notification l'ouvre dans un nouvel onglet.

Étant donné que les messages de données ne sont pas compatibles avec fcm_options.link, nous vous recommandons d'ajouter une charge utile de notification à tous les messages de données. Vous pouvez également gérer les notifications à l'aide du service worker.

Pour comprendre la différence entre les messages de notification et les messages de données, consultez Types de messages.

Remarque : Pour envoyer des messages à des thèmes, utilisez le SDK Admin pour abonner les instances d'application à des thèmes. Pour utiliser l'API Admin FCM, vous devez d'abord suivre les étapes décrites dans Ajouter le SDK Admin Firebase à votre serveur pour initialiser le SDK.

Définir les options de notification dans le service worker

Pour les messages de données, vous pouvez définir des options de notification dans le service worker. Commencez par initialiser votre application dans le 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

Pour définir des options, appelez onBackgroundMessage dans firebase-messaging-sw.js. Dans cet exemple, nous créons une notification avec des champs de titre, de corps et d'icône.

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

Remarque : Si vous souhaitez définir un comportement personnalisé dans le service worker lorsque l'utilisateur clique sur la notification, assurez-vous de gérer notificationclick avant d'importer des fonctions ou des bibliothèques FCM. Sinon, FCM peut remplacer le comportement personnalisé.

Bonnes pratiques pour les notifications

Si vous connaissez les messages push pour le Web, vous avez peut-être déjà lu les consignes générales sur ce qui fait une bonne notification. Pour les développeurs qui envoient des notifications via FCM pour le Web, les considérations les plus importantes sont la précision et la pertinence. Voici quelques recommandations spécifiques pour que vos notifications soient précises et pertinentes :

• Utilisez le champ "Icône" pour envoyer une image explicite. Dans de nombreux cas d'utilisation, il doit s'agir d'un logo d'entreprise ou d'application que vos utilisateurs reconnaissent immédiatement. Dans une application de chat, il peut s'agir de la photo de profil de l'utilisateur qui envoie le message.
• Utilisez le champ "Titre" pour exprimer la nature précise du message. Par exemple, "Jimmy a répondu" est plus précis que "Nouveau message". N'utilisez pas cet espace précieux pour le nom de votre entreprise ou de votre application. Utilisez plutôt l'icône à cet effet.
• N'utilisez pas le titre ni le corps de la notification pour afficher le nom ou le domaine de votre site Web. Les notifications contiennent déjà votre nom de domaine.
• Ajoutez fcm_options.link, généralement pour rediriger l'utilisateur vers votre application Web et la mettre au premier plan dans le navigateur. Dans de rares cas où toutes les informations que vous devez transmettre peuvent être incluses dans la notification, vous n'aurez peut-être pas besoin de lien.