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

Wichtig :In diesem Leitfaden wird erwähnt, dass Firebase in einem Service Worker initialisiert werden kann. Wenn Sie das modulare SDK in einem Service Worker verwenden möchten, müssen Sie Ihre Service Worker-Datei bündeln, da ES-Module relativ neu sind und nicht weithin unterstützt werden (siehe ES-Module in Service Workers). Wenn Sie Ihre Service Worker-Datei nicht bündeln möchten, können Sie die von den Compat-Paketen bereitgestellte Namespace-API verwenden. Informationen zur Verwendung von Modul-Bundlern mit Firebase finden Sie unter Modul-Bundler mit Firebase verwenden.

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 Dienstworker zur Verfügung stellen.

Web

Weitere Informationen zur modularen Web API, die durch Tree Shaking optimiert werden kann, und zum Upgrade von der API mit Namensraum.

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

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

Weitere Informationen zur modularen Web API, die durch Tree Shaking optimiert werden kann, und zum Upgrade von der API mit Namensraum.

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

Nachrichten verarbeiten, während Ihre 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.

Klickaktionen unterstützen nur sichere HTTPS-URLs.

Benachrichtigungsoptionen in der Sendeanfrage festlegen

Für Benachrichtigungsnachrichten, die vom App-Server 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 Klicken auf die Benachrichtigung in den Vordergrund gebracht. 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.

Hinweis :Wenn Sie Nachrichten an Themen senden möchten, abonnieren Sie mit dem Admin SDK App-Instanzen für Themen. Wenn Sie die Admin FCM API verwenden möchten, müssen Sie zuerst die Schritte unter Dem Server das Firebase Admin SDK hinzufügen ausführen, um das SDK zu initialisieren.

Benachrichtigungsoptionen im Dienst-Worker festlegen

Für Datennachrichten können Sie Benachrichtigungsoptionen im Dienstarbeiter festlegen. Initialisieren Sie zuerst Ihre App im Service Worker:

Web

Weitere Informationen zur modularen Web API, die durch Tree Shaking optimiert werden kann, und zum Upgrade von der API mit Namensraum.

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

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

Weitere Informationen zur modularen Web API, die durch Tree Shaking optimiert werden kann, und zum Upgrade von der API mit Namensraum.

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

Hinweis :Wenn Sie im Service Worker ein benutzerdefiniertes Verhalten definieren möchten, wenn auf die Benachrichtigung geklickt wird, müssen Sie notificationclick verarbeiten, bevor Sie FCM-Funktionen oder ‑Bibliotheken importieren. Andernfalls wird das benutzerdefinierte Verhalten möglicherweise von FCM überschrieben.

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:

• Verwenden Sie das Symbolfeld, um ein aussagekräftiges Bild zu 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.