Empfangen Sie Nachrichten in einem JavaScript-Client

Das Verhalten von Nachrichten unterscheidet sich je nachdem, ob sich die Seite im Vordergrund befindet (den Fokus hat), im Hintergrund, hinter anderen Registerkarten verborgen oder vollständig geschlossen ist. In allen Fällen muss die Seite den onMessage Rückruf verarbeiten, aber in Hintergrundfällen müssen Sie möglicherweise auch onBackgroundMessage verarbeiten oder die Anzeigebenachrichtigung konfigurieren, damit der Benutzer Ihre Web-App in den Vordergrund bringen kann.

App-Status Benachrichtigung Daten Beide
Vordergrund onMessage onMessage onMessage
Hintergrund (Servicemitarbeiter) onBackgroundMessage (Benachrichtigung wird automatisch angezeigt) onBackgroundMessage onBackgroundMessage (Benachrichtigung wird automatisch angezeigt)

Das JavaScript- Schnellstartbeispiel zeigt den gesamten Code, der zum Empfangen von Nachrichten erforderlich ist.

Behandeln Sie Nachrichten, wenn sich Ihre Web-App im Vordergrund befindet

Um das onMessage Ereignis zu empfangen, muss Ihre App den Firebase-Messaging-Service-Worker in firebase-messaging-sw.js definieren. Alternativ können Sie dem SDK über getToken(): Promise<string> einen vorhandenen Service-Worker bereitstellen.

Web modular API

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

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

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

Web modular API

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

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

Verarbeiten Sie Nachrichten, wenn Ihre Web-App im Hintergrund läuft

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

Festlegen von Benachrichtigungsoptionen in der Sendeanforderung

Für vom App-Server gesendete Benachrichtigungsnachrichten unterstützt die FCM-JavaScript-API den Schlüssel fcm_options.link . Normalerweise wird dies auf eine Seite in Ihrer Web-App 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 Browser-Tab geöffnet ist, wird dieser Tab durch einen Klick auf die Benachrichtigung in den Vordergrund gerückt. Wenn die Seite noch nicht geöffnet ist, öffnet ein Benachrichtigungsklick die Seite in einem neuen Tab.

Da Datennachrichten fcm_options.link nicht unterstützen, wird empfohlen, allen Datennachrichten eine Benachrichtigungsnutzlast hinzuzufügen. Alternativ können Sie Benachrichtigungen über den Service Worker bearbeiten.

Eine Erläuterung des Unterschieds zwischen Benachrichtigungs- und Datennachrichten finden Sie unter Nachrichtentypen .

Festlegen von Benachrichtigungsoptionen im Service Worker

Für Datennachrichten können Sie im Service Worker Benachrichtigungsoptionen festlegen. Initialisieren Sie zunächst Ihre App im Service Worker:

Web modular API

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

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

Um Optionen festzulegen, rufen Sie onBackgroundMessage in firebase-messaging-sw.js auf. In diesem Beispiel erstellen wir eine Benachrichtigung mit Titel-, Text- und Symbolfeldern.

Web modular API

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

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-Nachrichten für das Web vertraut sind, haben Sie möglicherweise bereits die allgemeinen Richtlinien für eine gute Benachrichtigung gelesen. Für Entwickler, die Benachrichtigungen über FCM für Web senden, sind Präzision und Relevanz die wichtigsten Überlegungen. Hier sind einige spezifische Empfehlungen, damit Ihre Benachrichtigungen präzise und relevant bleiben:

  • Verwenden Sie das Symbolfeld, um ein aussagekräftiges Bild zu senden. Für viele Anwendungsfälle sollte es sich um ein Firmen- oder App-Logo handeln, das Ihre Nutzer sofort erkennen. Bei einer Chat-Anwendung könnte es sich auch um das Profilbild des sendenden Benutzers handeln.
  • Verwenden Sie das Titelfeld, um die genaue Art der Nachricht auszudrücken. Beispielsweise vermittelt „Jimmy antwortete“ präzisere Informationen als „Neue Nachricht“. Nutzen Sie diesen wertvollen Platz nicht für Ihren Firmen- oder App-Namen – nutzen Sie zu diesem Zweck das Symbol.
  • Verwenden Sie den Titel oder Text der Benachrichtigung nicht zur Anzeige Ihres Website-Namens oder Ihrer Domain. Benachrichtigungen enthalten bereits Ihren Domainnamen.
  • Fügen Sie fcm_options.link hinzu, normalerweise um den Benutzer wieder mit Ihrer Web-App zu verknüpfen und sie im Browser in den Fokus zu rücken. In seltenen Fällen, in denen alle Informationen, die Sie übermitteln müssen, in die Benachrichtigung passen, benötigen Sie möglicherweise keinen Link.