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

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

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

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

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

Чтобы получить событие onMessage , ваше приложение должно определить сервис-воркер Firebase Messaging в 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 для веб-сайтов, важнейшими факторами являются точность и релевантность. Вот несколько конкретных рекомендаций по обеспечению точности и релевантности ваших уведомлений:

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