Получать сообщения в клиенте JavaScript

Поведение сообщений различается в зависимости от того, находится ли страница на переднем плане (имеет фокус), или на заднем плане, скрыта за другими вкладками или полностью закрыта. Во всех случаях страница должна обрабатывать обратный вызов onMessage , но в фоновых случаях вам также может потребоваться обработать onBackgroundMessage или настроить отображение уведомления, чтобы позволить пользователю вывести ваше веб-приложение на передний план.

Состояние приложения Уведомление Данные Оба
передний план onMessage onMessage onMessage
Фон (сервисный работник) onBackgroundMessage (уведомление отображается автоматически) onBackgroundMessage onBackgroundMessage (уведомление отображается автоматически)

Пример быстрого запуска JavaScript демонстрирует весь код, необходимый для получения сообщений.

Обработка сообщений, когда ваше веб-приложение находится на переднем плане

Чтобы получить событие onMessage , ваше приложение должно определить работника службы обмена сообщениями Firebase в firebase-messaging-sw.js . Альтернативно вы можете предоставить SDK существующего сервис-воркера через 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

Когда ваше приложение находится на переднем плане (пользователь в данный момент просматривает вашу веб-страницу), вы можете получать данные и полезные данные уведомлений непосредственно на странице.

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

Обработка сообщений, когда ваше веб-приложение находится в фоновом режиме

Все сообщения, полученные в то время, когда приложение находится в фоновом режиме, вызывают отображение уведомления в браузере. Вы можете указать параметры для этого уведомления, такие как заголовок или действие по клику, либо в запросе на отправку с сервера приложений, либо с помощью логики сервисного работника на клиенте.

Настройка параметров уведомления в запросе на отправку

Для сообщений уведомлений, отправляемых с сервера приложений, API JavaScript FCM поддерживает ключ fcm_options.link . Обычно это устанавливается на страницу вашего веб-приложения:

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

Если значение ссылки указывает на страницу, которая уже открыта на вкладке браузера, щелчок по уведомлению переводит эту вкладку на передний план. Если страница еще не открыта, щелчок по уведомлению откроет страницу на новой вкладке.

Поскольку сообщения с данными не поддерживают fcm_options.link , рекомендуется добавлять полезные данные уведомления ко всем сообщениям с данными. Альтернативно вы можете обрабатывать уведомления с помощью сервис-воркера.

Объяснение разницы между уведомлениями и сообщениями с данными см. в разделе Типы сообщений .

Настройка параметров уведомлений в сервис-воркере

Для сообщений с данными вы можете настроить параметры уведомлений в сервисном работнике. Сначала инициализируйте свое приложение в сервис-воркере:

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

Чтобы установить параметры, вызовите onBackgroundMessage в firebase-messaging-sw.js . В этом примере мы создаем уведомление с полями заголовка, тела и значка.

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

Рекомендации по использованию уведомлений

Если вы знакомы с push-сообщениями в Интернете, возможно, вы уже прочитали общие рекомендации о том, что такое хорошее уведомление . Для разработчиков, отправляющих уведомления через FCM for Web, наиболее важными факторами являются точность и актуальность. Вот несколько конкретных рекомендаций, как сделать ваши уведомления точными и актуальными:

  • Используйте поле значка, чтобы отправить значимое изображение. Во многих случаях это должен быть логотип компании или приложения, который пользователи сразу узнают. Или, в случае приложения чата, это может быть изображение профиля отправляющего пользователя.
  • Используйте поле заголовка, чтобы точно выразить суть сообщения. Например, фраза «Ответил Джимми» передает более точную информацию, чем «Новое сообщение». Не используйте это ценное пространство для названия вашей компании или приложения — используйте для этой цели значок.
  • Не используйте заголовок или текст уведомления для отображения имени или домена вашего веб-сайта; уведомления уже содержат ваше доменное имя.
  • Добавьте fcm_options.link обычно для того, чтобы связать пользователя с вашим веб-приложением и отобразить его в браузере. В редких случаях, когда вся информация, которую вам нужно передать, может быть помещена в уведомление, ссылка может не понадобиться.