Push-уведомления в React с Firebase

человек держит чёрный iPhone с уведомлением на экране

Что такое push-уведомления и как это работает

Push-уведомления позволяют приложению отправлять актуальную информацию, оповещения или персонализированные сообщения прямо на устройство пользователя, даже если приложение не активно. Для веб-приложений уведомления сначала перехватывает браузер и затем передаёт их в приложение через сервис-воркер.

Ключевые компоненты механизма:

Веб-приложение (React) — инициирует запрос разрешения и получает клиентский токен.
Браузер + сервис-воркер — принимают и отображают уведомления в фоне.
Firebase Cloud Messaging (FCM) — доставляет уведомления от отправителя к устройствам.
VAPID-ключи — аутентифицируют веб-приложение при отправке push-сообщений.

Короткое определение терминов:

VAPID: ключи (публичный/приватный) для аутентификации Web Push.
Service Worker: фоновый скрипт, который умеет показывать push-уведомления вне контекста вкладки.
Client token (registration token): уникальный идентификатор устройства/браузера в FCM.

Преимущества и ограничения

Важно

Преимущества: высокая вовлечённость пользователей, мгновенное оповещение, персонализация.
Ограничения: зависимость от разрешений пользователя, различия поведения между браузерами и ОС, необходимость безопасного хранения ключей.

Содержание руководства

Создание проекта в Firebase и регистрация веб‑приложения
Генерация пары ключей Web (VAPID)
Настройка React-приложения и firebase.js
Запрос разрешений и получение токена
Сервис-воркер для фоновых уведомлений
Компонент уведомлений в React
Тестирование и отправка тестовой кампании
Проверки, безопасность, сценарии отказа и альтернативы

Шаг 1 — Создаём проект Firebase

Перейдите в Firebase Console (https://console.firebase.google.com), войдите под Google-аккаунтом и нажмите кнопку Go to Console, чтобы открыть обзор консоли.
На странице обзора нажмите Create a project и укажите имя проекта.

Кнопка 'Create New Project' на странице обзора Firebase

После создания проекта перейдите на страницу обзора проекта и зарегистрируйте веб-приложение: нажмите иконку Web, укажите имя и нажмите Register app.

Иконка Web (регистрация приложения) на странице проекта Firebase

Скопируйте объект конфигурации Firebase (firebaseConfig) с вкладки Project settings — это понадобится в коде.

Настройка Firebase Cloud Messaging (FCM)

Перейдите в Project settings.

Кнопка 'Project settings' на консоли Firebase

На вкладке Cloud Messaging настройте Web configuration и сгенерируйте пару ключей (VAPID) — публичный и приватный.

Вкладка 'Cloud Messaging' в настройках проекта Firebase

В разделе Web configuration нажмите Generate key pair и сохраните публичный VAPID-ключ — он понадобится в коде при получении токена.

Кнопка 'Generate key pair' в разделе Web configuration Cloud Messaging

Важно: приватный ключ храните в безопасном месте и не публикуйте в клиентском коде. Публичный ключ можно передать в браузер для получения токена.

Шаг 2 — Создаём React‑приложение и устанавливаем зависимости

Создайте приложение React (например, с помощью create-react-app) и установите npm-пакеты firebase и react-hot-toast:

npm install firebase react-hot-toast

В репозитории вы найдете исходный код проекта (ссылка на GitHub у автора).

Шаг 3 — Конфигурируем Firebase и FCM в коде

Создайте файл src/firebase.js и добавьте инициализацию Firebase и FCM. Ниже — пример, адаптированный для модульной версии SDK (v9+):

import { initializeApp } from "firebase/app";
import { getMessaging, getToken, onMessage } from 'firebase/messaging';

const firebaseConfig = {
  apiKey: "",
  authDomain: "",
  projectId: "",
  storageBucket: "",
  messagingSenderId: "",
  appId: ""
};

const app = initializeApp(firebaseConfig);
const messaging = getMessaging(app);

export { messaging, getToken, onMessage };

Замените значения в firebaseConfig на те, что вы скопировали из Project settings. Этот код создаёт экземпляр Firebase и объект messaging для работы с FCM.

Шаг 4 — Запрос разрешения на уведомления и получение токена

Добавьте в src/firebase.js функцию requestPermission, которая запросит у пользователя разрешение и при его подтверждении вернёт регистрационный токен.

export const requestPermission = async (vapidKey) => {
  try {
    console.log("Requesting user permission for notifications...");
    const permission = await Notification.requestPermission();

    if (permission === 'granted') {
      console.log('Notification permission granted.');
      const currentToken = await getToken(messaging, { vapidKey });

      if (currentToken) {
        console.log('Client Token: ', currentToken);
        return currentToken;
      } else {
        console.log('Failed to generate the app registration token.');
        return null;
      }
    } else {
      console.log('User denied notification permission.');
      return null;
    }
  } catch (err) {
    console.log('An error occurred while requesting token.', err);
    return null;
  }
};

Примечание: передайте сюда публичный VAPID-ключ (Notification_key_pair) из настроек Cloud Messaging.

Важно: никогда не храните приватный VAPID-ключ в клиентском коде.

Шаг 5 — Слушатели входящих сообщений (в фокусе приложения)

Для обработки уведомлений, когда приложение в фокусе, добавьте onMessageListener:

export const onMessageListener = () =>
  new Promise((resolve) => {
    onMessage(messaging, (payload) => {
      resolve(payload);
    });
  });

onMessage срабатывает, когда приложение открыто и получает пуш. В payload приходят title, body и дополнительные поля data.

Шаг 6 — Сервис-воркер для фоновых уведомлений

FCM требует отдельного сервис-воркера в папке public — файл firebase-messaging-sw.js. Он обрабатывает уведомления в фоне и показывает их через self.registration.showNotification.

Создайте /public/firebase-messaging-sw.js со следующим содержимым:

importScripts("https://www.gstatic.com/firebasejs/9.0.0/firebase-app-compat.js");
importScripts("https://www.gstatic.com/firebasejs/9.0.0/firebase-messaging-compat.js");

// Вставьте сюда ваш firebaseConfig из Project settings
const firebaseConfig = {
  "configuration information"
};

firebase.initializeApp(firebaseConfig);
const messaging = firebase.messaging();

messaging.onBackgroundMessage(function(payload) {
  console.log('Received background message ', payload);
  const notificationTitle = payload.notification?.title || 'Уведомление';
  const notificationOptions = {
    body: payload.notification?.body || '',
    // здесь можно добавить icon, badge, data и т.д.
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});

Пояснение: наработки с firebase-compat используются в сервис-воркере для совместимости. Если вы используете другой способ, убедитесь, что импорт и инициализация соответствуют версии SDK.

Шаг 7 — Компонент Notification в React

Создайте src/components/Notification.js. Компонент запрашивает разрешение, подписывается на onMessageListener и показывает toast-уведомления (react-hot-toast).

import React, { useState, useEffect } from 'react';
import { Toaster, toast } from 'react-hot-toast';
import { requestPermission, onMessageListener } from '../firebase';

function Notification() {
  const [notification, setNotification] = useState({ title: '', body: '' });

  useEffect(() => {
    // Передайте сюда публичный VAPID-ключ
    const vapidKey = 'YOUR_PUBLIC_VAPID_KEY';
    requestPermission(vapidKey);

    const unsubscribe = onMessageListener().then((payload) => {
      setNotification({
        title: payload?.notification?.title,
        body: payload?.notification?.body,
      });

      toast.success(`${payload?.notification?.title}: ${payload?.notification?.body}`, {
        duration: 60000,
        position: 'top-right'
      });
    });

    return () => {
      // onMessageListener возвращает Promise, поэтому обработка отписки зависит от вашей реализации
      if (unsubscribe && typeof unsubscribe.catch === 'function') {
        unsubscribe.catch((err) => console.log('failed: ', err));
      }
    };
  }, []);

  return (
    
      
    
  );
}

export default Notification;

Добавьте компонент в App.js:

import './App.css';
import Notification from './components/Notification';

function App() {
  return (
    
      
        
      
    
  );
}

export default App;

Шаг 8 — Тестирование (локально и в production)

Запустите dev сервер и откройте http://localhost:3000. Браузер покажет запрос на разрешение уведомлений.

Всплывающее окно запроса разрешения на уведомления в браузере

Нажмите Allow. В консоли браузера должен появиться клиентский токен — скопируйте его.

В Firebase Console в разделе Cloud Messaging выберите Create your first campaign, затем Firebase Notification messages и заполните заголовок и текст. В разделе Device preview нажмите Send test message, вставьте client token и отправьте тест.

Кнопка 'Create your first campaign' в Firebase Cloud Messaging

Страница настройки сообщения push-уведомления

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

Если приложение в фокусе — получите уведомление через onMessage и toast. Если вкладка закрыта или браузер в фоне — сервис-воркер покажет фоновое уведомление.

Частые ошибки и способы их устранения

Неверный VAPID-ключ: убедитесь, что вы используете публичный VAPID-ключ при вызове getToken и не публикуете приватный ключ.
Отсутствие сервис-воркера в public: браузер не покажет фоновое уведомление без корректного файла firebase-messaging-sw.js в корне на том же домене.
Токен равен null: скорее всего, пользователь запретил уведомления или браузер не поддерживает Push API.
HTTPS: Web Push требует защищённого соединения (HTTPS) в production. Для локальной разработки работает localhost.
Различия в браузерах: некоторые браузеры (например, iOS Safari) имеют ограниченную поддержку push-уведомлений.

Критерии приёмки

Запрос разрешения появляется при первом посещении и корректно обрабатывается при Allow/Deny.
При Allow генерируется client token и логируется в консоли.
При отправке тестового сообщения через FCM устройство получает уведомление в фокусе (toast) и в фоне (сервис-воркер).
VAPID-публичный ключ используется в клиентском коде, приватный ключ хранится безопасно.

Проверочные тест-кейсы

Установка и первый запуск: страница запрашивает разрешение, ответ Allow генерирует токен.
Deny-путь: при отказе токен не генерируется, пользователю показано корректное сообщение в логах.
Фоновое уведомление: при закрытой вкладке/свернутом браузере приходит системное уведомление.
Несовместимый браузер: graceful fallback — приложение логирует, что Push API недоступен.

Безопасность и конфиденциальность

Храните приватный VAPID-ключ и серверные ключи в защищённом хранилище (секреты среды, KMS и т. п.).
Не записывайте client tokens в публичные логи.
Если вы собираете персональные данные в payload уведомлений — проанализируйте соответствие требованиям GDPR/локального законодательства (обязательное согласие, минимизация данных).
Ограничьте срок действия и объём персонализированных данных в уведомлениях.

Важно: push-уведомления — канал высокой видимости, используйте его ответственно, чтобы не раздражать пользователей.

Альтернативы и когда это не подходит

Если нужно покрыть мобильные приложения — стоит рассмотреть нативные push-решения (APNs для iOS, FCM для Android) в связке с серверной логикой.
Если вы не хотите управлять инфраструктурой — сервисы типа OneSignal, Firebase Messaging (как сервис) или сторонние платформы упрощают интерфейс кампаний, но вводят зависимость от провайдера.
Для приватных интранет-приложений без HTTPS Web Push может быть неприемлем — потребуется туннелирование или VPN.

Когда это не работает:

iOS Safari (до последних обновлений) долго ограничивал Web Push; проверяйте поддержку для целевой аудитории.
Пользователь всегда может отключить уведомления в настройках браузера/устройства.

Советы по масштабированию и эксплуатации

Управляйте списком токенов на сервере: удаляйте устаревшие и отозванные токены.
Используйте темплейты сообщений и сегментацию аудитории для целевых кампаний.
Для массовых рассылок интегрируйте серверную логику (через Admin SDK или FCM HTTP v1 API) и контролируйте частоту отправок.
Логируйте ответы от FCM при отправке (ошибки, отписки) и на их основе очищайте базу токенов.

Шаблон отправки push с сервера (пример HTTP v1)

Ниже — упрощённый пример логики отправки с серверной части (Node.js) через FCM HTTP v1 API. Здесь нужен серверный ключ/OAuth-авторизация (Admin SDK предпочтительнее).

Используйте Firebase Admin SDK на сервере для надёжной отправки сообщений и работы с группами токенов.
Пример отправки через Admin SDK (Node.js) — документация Firebase содержит подробные примеры.

Короткий чек-лист для релиза

VAPID-ключи сгенерированы и публичный ключ добавлен в код.
firebase-messaging-sw.js размещён в public/ и корректно импортирован.
Проверено поведение в основных браузерах (Chrome, Firefox, Edge, Safari по возможности).
HTTPS включён в production.
Логика обработки токенов и их очистки на сервере реализована.

Часто задаваемые вопросы

Можно ли использовать один VAPID-ключ для нескольких сайтов?

Да, но это снижает изоляцию. Рекомендуется генерировать отдельные ключи для разных приложений/доменов.

Что делать, если getToken возвращает null?

Проверьте, разрешил ли пользователь уведомления, корректность VAPID-ключа и поддержку Push API в браузере.

Как обновлять токены у пользователей?

Токены могут обновляться со временем. Отслеживайте события обновления токена и обновляйте запись на сервере.

Как отправлять уведомления с изображением или кнопками действий?

Добавьте соответствующие поля в notificationOptions (icon, image, actions) и обработайте действия в сервис-воркере через event.notification.

Итоги

Firebase Cloud Messaging предоставляет удобный путь для интеграции push-уведомлений в React-приложения.
Ключевые шаги: регистрация приложения, генерация VAPID, настройка service worker, запрос разрешений, получение токена и отправка сообщений.
Тестируйте в разных браузерах, обеспечьте HTTPS и соблюдайте правила безопасности и конфиденциальности.