Nachrichten in Web-Apps empfangen

Plattform auswählen: iOS+ Android Web Flutter Unity C++


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

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

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

Nachrichten verarbeiten, wenn sich Ihre Web-App im Vordergrund befindet

Damit Ihre App das Ereignis onMessage empfangen kann, muss der Firebase-Messaging-Service-Worker in firebase-messaging-sw.js definiert sein. Alternativ können Sie dem SDK über getToken(): Promise<string> einen vorhandenen Service 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 13.0.0 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/13.0.0/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/13.0.0/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 Ihre Webseite), 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 sich Ihre Web-App im Hintergrund befindet

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

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. In der Regel wird hier 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": {
        ,
        "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, sollten Sie allen Datennachrichten eine Benachrichtigungsnutzlast hinzufügen. Alternativ können Sie Benachrichtigungen mit dem Service Worker verarbeiten.

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

Benachrichtigungsoptionen im Service Worker festlegen

Für Datennachrichten können Sie Benachrichtigungsoptionen im Service Worker 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 13.0.0 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/13.0.0/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/13.0.0/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();

Rufen Sie onBackgroundMessage in firebase-messaging-sw.js auf, um Optionen festzulegen. In diesem Beispiel erstellen wir eine Benachrichtigung mit den Feldern „title“, „body“ und „icon“.

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

Für Entwickler, die Benachrichtigungen über FCM für das Web senden, sind die wichtigsten Überlegungen Präzision und Relevanz. Hier sind einige konkrete Empfehlungen, wie Sie Ihre Benachrichtigungen präzise und relevant halten:

  • Verwenden Sie das Symbolfeld, um ein aussagekräftiges Bild zu senden. In vielen Anwendungsfällen sollte dies ein Unternehmens- oder App-Logo sein, das Ihre Nutzer sofort erkennen. Bei einer Chatanwendung kann es sich um das Profilbild des Absenders handeln.
  • Verwenden Sie das Titelfeld, um den genauen Inhalt der Nachricht anzugeben. Beispielsweise enthält „Jimmy hat geantwortet“ genauere Informationen als „Neue Nachricht“. Verwenden Sie diesen wertvollen Platz nicht für den Namen Ihres Unternehmens oder Ihrer App – verwenden Sie dafür das Symbol.
  • Verwende den Titel oder Text der Benachrichtigung nicht, um den Namen oder die Domain deiner Website anzuzeigen. Benachrichtigungen enthalten bereits deinen Domainnamen.
  • Füge fcm_options.link hinzu, um den Nutzer in der Regel zurück zu deiner Webanwendung zu leiten und sie im Browser in den Fokus zu rücken. In seltenen Fällen, in denen alle Informationen, die Sie vermitteln möchten, in die Benachrichtigung passen, ist möglicherweise kein Link erforderlich.