PHPTime

Push-уведомления в Chrome и Safari: настройка Web Push на PHP

Chrome и Safari получают push-уведомления через стандартный Web Push, поэтому для обоих браузеров можно использовать один PHP-бэкенд. Разберём весь путь от кнопки «Включить уведомления» до отправки, обработки ошибок и удаления просроченных подписок.

Как работает Web Push в Chrome и Safari

Браузер создаёт подписку через Push API и возвращает адрес доставки endpoint и ключи шифрования. PHP сохраняет эту подписку, шифрует сообщение и отправляет его в push-службу, указанную браузером. При доставке браузер запускает service worker, а тот показывает системное уведомление через showNotification(). Открытая вкладка для этого не нужна. Доставка при полностью закрытом браузере зависит от платформы, фоновых процессов и настроек системы.

Старые интеграции могли использовать отдельные схемы для Chrome и Safari, включая GCM и Safari Website Push. Для стандартного Web Push достаточно одной серверной реализации. Браузер сам выбирает push-службу, а сервер отправляет запрос по полученному endpoint. Для Safari не требуется заводить отдельный сертификат APNs.

Где открыли сайтЧто нужно для подписки
Chrome на компьютере и AndroidЗащищённый контекст, service worker и разрешение на уведомления. Установка веб-приложения не нужна.
Safari на macOSЗащищённый контекст, service worker и запрос разрешения по действию пользователя.
iPhone и iPadВеб-приложение на экране «Домой». Пользователь запускает его оттуда и нажимает кнопку подписки. Web Push для таких приложений доступен с iOS и iPadOS 16.4.

На продакшене используйте HTTPS. Для локальной разработки браузеры обычно считают localhost защищённым контекстом. На iPhone и iPad подготовьте манифест с названием, иконками и режимом отображения standalone, чтобы сайт запускался с экрана «Домой» как приложение.

Установите библиотеку и создайте ключи VAPID

Для PHP 8.3–8.5 установите minishlink/web-push через Composer. Если окружения различаются, фиксируйте зависимости для самой младшей версии PHP и запускайте проверки на каждой целевой версии. Библиотека сформирует заголовки Web Push и зашифрует полезную нагрузку ключами конкретной подписки.

Shell
composer require minishlink/web-push

Один раз создайте пару VAPID для приложения. Открытый ключ передайте фронтенду, закрытый храните на сервере в секретах окружения. VAPID идентифицирует отправителя перед push-службой. Ключи подписки p256dh и auth используются для шифрования сообщения.

PHP
<?php
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

// Запустите локально и сохраните пару в настройках приложения.
print_r(\Minishlink\WebPush\VAPID::createVapidKeys());

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

Запросите разрешение и сохраните подписку

Разместите sw.js в корне сайта, если он должен работать со всем приложением. Если service worker уже есть, добавьте в него обработчики из следующего раздела. На странице настроек покажите кнопку enable-push. Перед запуском скрипта передайте в vapidPublicKey открытый ключ, а в csrfToken токен текущей сессии. Зарегистрируйте worker заранее, чтобы запрос разрешения выполнялся прямо в обработчике клика.

JS
async function setupPushButton(vapidPublicKey, csrfToken) {
  const button = document.querySelector('#enable-push');
  if (!isSecureContext || !('serviceWorker' in navigator) ||
      !('PushManager' in window) || !('Notification' in window)) return;

  await navigator.serviceWorker.register('/sw.js');
  const registration = await navigator.serviceWorker.ready;
  // Преобразуем открытый ключ из base64url в массив байтов.
  const base64 = vapidPublicKey.replace(/-/g, '+').replace(/_/g, '/');
  const key = Uint8Array.from(
    atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '=')),
    char => char.charCodeAt(0),
  );

  button.disabled = false;
  button.addEventListener('click', async () => {
    button.disabled = true;
    try {
      if (await Notification.requestPermission() !== 'granted') {
        alert('Разрешение можно изменить в настройках уведомлений.');
        return;
      }
      const subscription = await registration.pushManager.getSubscription()
        ?? await registration.pushManager.subscribe({
          userVisibleOnly: true,
          applicationServerKey: key,
        });
      const response = await fetch('/push/subscriptions', {
        method: 'POST',
        headers: {'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken},
        body: JSON.stringify(subscription),
      });
      if (!response.ok) throw new Error('Подписка не сохранена');
      button.textContent = 'Уведомления включены';
    } catch {
      alert('Не удалось включить уведомления. Попробуйте ещё раз.');
    } finally {
      button.disabled = false;
    }
  });
}
// Кнопка в разметке изначально отключена.
setupPushButton(vapidPublicKey, csrfToken).catch(console.error);

Обработчик POST /push/subscriptions проверяет сессию и CSRF-токен, разбирает JSON и сохраняет endpoint, keys.p256dh и keys.auth. Идентификатор пользователя берите из сессии. Сделайте endpoint уникальным и используйте upsert, чтобы повторная отправка формы обновляла запись. Один аккаунт может иметь несколько подписок. Если устройство общее, отвязывайте подписку при выходе из аккаунта, чтобы следующему пользователю не приходили чужие уведомления.

endpoint поступает от клиента, а PHP-воркер позже делает по нему исходящий запрос. Принимайте HTTPS-адреса доверенных push-служб, ограничьте исходящий трафик воркера и запретите перенаправления. Храните адреса и ключи подписок как чувствительные данные и исключите их из журналов.

Покажите уведомление в service worker

Оборачивайте показ уведомления и обработку клика в event.waitUntil(), чтобы браузер дождался завершения асинхронной работы. В примере уведомление открывает раздел заказов. Сам раздел проверяет права пользователя после перехода.

JS
self.addEventListener('push', event => {
  let message = {};
  try {
    message = event.data?.json() ?? {};
  } catch {
    // Если формат сообщения изменился, покажем запасной текст.
  }
  event.waitUntil(self.registration.showNotification(
    message.title ?? 'Новое уведомление',
    {body: message.body ?? 'Откройте сайт, чтобы узнать подробности.'},
  ));
});

self.addEventListener('notificationclick', event => {
  event.notification.close();
  event.waitUntil(self.clients.openWindow('/orders/'));
});

Держите сообщения короткими: они могут появляться на заблокированном экране, а push-службы ограничивают размер запроса. Для разных переходов передавайте тип события или идентификатор записи и стройте маршрут внутри worker. Если передаёте готовый адрес, проверяйте, что он относится к вашему сайту.

Отправьте тестовое уведомление из PHP

Загрузите сохранённый JSON подписки из базы и передайте его в этот CLI-скрипт через стандартный ввод. Задайте VAPID_SUBJECT контактным идентификатором VAPID с рабочим почтовым адресом в формате mailto:, а VAPID_PUBLIC_KEY и VAPID_PRIVATE_KEY — ранее созданной парой.

PHP
<?php
declare(strict_types=1);

use Minishlink\WebPush\Subscription;
use Minishlink\WebPush\WebPush;

require __DIR__ . '/vendor/autoload.php';

$config = [];
foreach (['subject', 'publicKey', 'privateKey'] as $field) {
    $variable = match ($field) {
        'subject' => 'VAPID_SUBJECT',
        'publicKey' => 'VAPID_PUBLIC_KEY',
        'privateKey' => 'VAPID_PRIVATE_KEY',
    };
    $value = getenv($variable);
    if ($value === false || $value === '') {
        throw new RuntimeException('Не задана переменная ' . $variable);
    }
    $config[$field] = $value;
}

$subscription = Subscription::create(
    json_decode(stream_get_contents(STDIN), true, flags: JSON_THROW_ON_ERROR),
);
$payload = json_encode([
    'title' => 'Статус заказа обновился',
    'body' => 'Подробности доступны в личном кабинете.',
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);

$push = new WebPush(['VAPID' => $config]);
// Через час уведомление потеряет актуальность.
$report = $push->sendOneNotification($subscription, $payload, ['TTL' => 3600]);
$status = $report->getResponse()?->getStatusCode();
fwrite(STDOUT, ($status ?? 'нет HTTP-ответа') . PHP_EOL);
exit($report->isSuccess() ? 0 : 1);

Успешный отчёт означает, что push-служба приняла сообщение. Показ зависит от доступности устройства, срока доставки, разрешений и системных настроек. Для массовой отправки используйте queueNotification() и обрабатывайте отчёты из flush() ограниченными партиями в фоновом воркере.

Обработайте ошибки и отписку

  • 404 или 410 от push-службы. Удалите недействительную подписку. Библиотека определяет её через isSubscriptionExpired(). При удалении сверяйте запись с той, которую отправляли, чтобы сохранить подписку, успевшую обновиться.
  • 429, временная ошибка 5xx или сетевой сбой. Повторите отправку с увеличивающейся задержкой, учитывая Retry-After, если он есть. Ограничьте число попыток и прекратите их после истечения срока актуальности события.
  • 400, 401, 403 или 413. Разберите причину перед повтором. Проверьте формат запроса, соответствие пары VAPID подписке и объём сообщения. При массовом сбое сгруппируйте ошибки по push-службе и версии ключа.

Для кнопки «Отключить уведомления» удалите привязку на сервере и вызовите unsubscribe() у текущей подписки. Разрешение сайта браузер может сохранить, поэтому после отписки проверяйте наличие самой подписки. При повторном открытии настроек сверяйте getSubscription() с записью на сервере: пользователь мог очистить данные сайта или изменить разрешение в браузере.

Чек-лист перед запуском

  1. В Chrome и Safari на macOS подпишитесь по кнопке. На iPhone или iPad повторите проверку после запуска приложения с экрана «Домой».
  2. Отправьте уведомление при закрытой вкладке и нажмите на него. Проверьте показ и переход в нужный раздел на каждом устройстве.
  3. Подпишитесь с двух устройств и отключите уведомления на одном. Убедитесь, что второе продолжает получать сообщения.
  4. Проверьте обработку просроченной подписки, временного сбоя и ошибки VAPID. Убедитесь, что очередь учитывает срок актуальности события.
  5. Проверьте выход из аккаунта и вход под другим пользователем на том же устройстве. В журнале оставьте статус отправки и внутренний идентификатор задания.

Частые вопросы

Нужны ли отдельные PHP-бэкенды для push в Chrome и Safari?

Достаточно одного бэкенда на стандартном Web Push. Браузер выдаёт адрес своей push-службы и ключи подписки, а PHP-библиотека использует их при отправке.

Почему на iPhone не появляется запрос на уведомления?

Откройте веб-приложение с экрана «Домой» и нажмите кнопку подписки внутри него. Если разрешение уже отклонено, проверьте системные настройки уведомлений.

Почему push-служба приняла сообщение, а уведомление не появилось?

Проверьте разрешение на уведомления, регистрацию service worker и выполнение showNotification(). Проверьте также доступность устройства, TTL сообщения и системные настройки уведомлений.

Справка по теме

Ещё в разделе «Инструменты и библиотеки»

Не работает GitHub: как настроить прокси для Git и Composer

Что делать, если GitHub не открывается, git clone зависает, а Composer не скачивает пакеты. Настройка HTTP-прокси, SSH ProxyCommand и зеркала Packagist.

7 мин

PHPOffice в PHP: Excel, Word и PowerPoint на практике

Как читать Excel и генерировать XLSX, DOCX и PPTX в PHP 8.3–8.5. Примеры PHPOffice, работа с шаблонами, формулами, типами ячеек и памятью.

7 мин

Какой PHP-фреймворк выбрать для среднего проекта в 2026 году

Сравниваем Laravel, Symfony, Yii 2, Yii 3 и Slim для среднего PHP-проекта: база данных, очереди, тесты, обновления и выбор под задачи команды.

6 мин

Jeapie и массовые мобильные push-уведомления в PHP

Как устроены рассылки Jeapie и как реализовать мобильные push-уведомления в PHP и Yii: подписки, выбор аудитории, очередь, повторы и отчёт по отправке.

6 мин