Nachrichten in einem JavaScript-Client empfangen

Das Verhalten von Nachrichten unterscheidet sich je nachdem, ob die Seite im Vordergrund (im Fokus) oder im Hintergrund ist, hinter anderen Tabs verborgen oder vollständig geschlossen ist. In allen Fällen muss die Seite den onMessage-Callback verarbeiten. Bei Hintergrundfällen müssen Sie möglicherweise auch onBackgroundMessage verarbeiten oder die Anzeigebenachrichtigung so konfigurieren, dass der Nutzer Ihre Webanwendung in den Vordergrund bringen kann.

App-Status Benachrichtigung Daten Beides
Vordergrund onMessage onMessage onMessage
Hintergrund (Dienst-Worker) onBackgroundMessage (Benachrichtigung im Display wird automatisch angezeigt) onBackgroundMessage onBackgroundMessage (Benachrichtigung wird automatisch angezeigt)

Im JavaScript-Beispiel für die Kurzanleitung wird der gesamte Code zum Empfangen von Nachrichten veranschaulicht.

Nachrichten verarbeiten, wenn Ihre Webanwendung im Vordergrund ist

Damit das Ereignis onMessage empfangen werden kann, muss Ihre App den Firebase-Messaging-Dienst-Worker in firebase-messaging-sw.js definieren. Alternativ können Sie dem SDK über getToken(): Promise<string> einen vorhandenen Dienst-Worker zur Verfügung stellen.

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

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

Wenn sich Ihre App im Vordergrund befindet (der Nutzer sieht sich gerade Ihre Webseite an), können Sie Daten- und Benachrichtigungsnutzlasten direkt auf der Seite empfangen.

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

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

Nachrichten verarbeiten, wenn die Webanwendung im Hintergrund ausgeführt wird

Alle Nachrichten, die empfangen werden, während die App im Hintergrund läuft, lösen eine Benachrichtigung im Browser aus. Sie können Optionen für diese Benachrichtigung wie Titel oder Klickaktion entweder in der Sendeanfrage von Ihrem App-Server oder mithilfe der Service Worker-Logik auf dem Client angeben.

Benachrichtigungsoptionen in der Sendeanfrage festlegen

Für Benachrichtigungen, die vom Anwendungsserver gesendet werden, unterstützt die FCM JavaScript API den Schlüssel fcm_options.link. Normalerweise wird dies auf eine Seite in Ihrer Webanwendung festgelegt:

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

Wenn der Linkwert auf eine Seite verweist, die bereits in einem Browsertab geöffnet ist, wird dieser Tab durch einen Klick auf die Benachrichtigung im Vordergrund angezeigt. Wenn die Seite noch nicht geöffnet ist, wird sie durch Klicken auf die Benachrichtigung in einem neuen Tab geöffnet.

Da Datennachrichten fcm_options.link nicht unterstützen, empfehlen wir, allen Datennachrichten eine Benachrichtigungsnutzlast hinzuzufügen. Alternativ können Sie Benachrichtigungen auch über den Dienst-Worker verarbeiten.

Eine Erklärung zum Unterschied zwischen Benachrichtigungs- und Datennachrichten finden Sie unter Nachrichtentypen.

Benachrichtigungsoptionen im Service Worker festlegen

Für Datennachrichten können Sie Benachrichtigungsoptionen im Dienstarbeiter festlegen. Initialisieren Sie zuerst Ihre App im 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);

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

Wenn Sie Optionen festlegen möchten, geben Sie in firebase-messaging-sw.js onBackgroundMessage ein. In diesem Beispiel erstellen wir eine Benachrichtigung mit den Feldern „Titel“, „Text“ und „Symbol“.

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

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

Best Practices für Benachrichtigungen

Wenn Sie mit Push-Mitteilungen für das Web vertraut sind, haben Sie sich vielleicht schon mit den allgemeinen Richtlinien zu guten Benachrichtigungen vertraut gemacht. Für Entwickler, die Benachrichtigungen über FCM für das Web senden, sind Genauigkeit und Relevanz die wichtigsten Aspekte. Hier sind einige konkrete Empfehlungen, wie Sie Ihre Benachrichtigungen präzise und relevant halten können:

  • Über das Symbolfeld können Sie ein aussagekräftiges Bild senden. Bei vielen Anwendungsfällen sollte dies ein Unternehmens- oder App-Logo sein, das Ihre Nutzer sofort erkennen. Bei einer Chat-Anwendung kann es sich auch um das Profilbild des sendenden Nutzers handeln.
  • Geben Sie im Feld „Titel“ die genaue Art der Nachricht an. „Jimmy hat geantwortet“ ist beispielsweise eine präzisere Information als „Neue Nachricht“. Verwenden Sie diesen wertvollen Platz nicht für den Namen Ihres Unternehmens oder Ihrer App. Verwenden Sie dazu das Symbol.
  • Geben Sie den Namen oder die Domain Ihrer Website nicht im Titel oder im Text der Benachrichtigung an. Benachrichtigungen enthalten bereits Ihren Domainnamen.
  • Fügen Sie fcm_options.link hinzu, um den Nutzer normalerweise wieder mit Ihrer Webanwendung zu verknüpfen und sie im Browser in den Fokus zu rücken. In seltenen Fällen, in denen alle erforderlichen Informationen in die Benachrichtigung passen, ist möglicherweise kein Link erforderlich.