Jeapie и массовые мобильные push-уведомления в PHP
Jeapie объединял три сценария мобильных уведомлений: сигнал самому себе, сообщение выбранным подписчикам и рассылку всей аудитории. В PHP 8.3–8.5 эту модель удобно реализовать через очередь и адаптеры FCM и APNs. Разберём, как выбрать получателей, пережить сбой отправки и понять, чем завершилась кампания.
Как были устроены рассылки Jeapie
В Jeapie администратор создавал провайдера уведомлений, приглашал коллег или клиентов подписаться и отправлял сообщения из панели управления либо через API. Провайдер объединял аудиторию вокруг одного источника. Для команды это мог быть канал мониторинга, для магазина — канал уведомлений приложения.
| Метод Jeapie API 2.0 | Получатели | Пример |
|---|---|---|
personal/send | Сам отправитель | Сбой ночного импорта |
users/send | Один или несколько подписчиков | Заказ готов к выдаче |
broadcast/send | Все подписчики провайдера | Плановые работы в приложении |
Эти имена описывают исторический интерфейс Jeapie. В новом проекте их можно выразить тремя режимами выбора аудитории внутри приложения. Дальнейший путь у сообщений общий: запись получателей, задача в очереди, вызов транспорта и обработка ответа.
Разделите подписку, устройство и транспорт
Подписка отвечает на вопрос, какие уведомления хочет получать пользователь. Токен регистрации FCM или токен устройства APNs определяет, куда отправить push. У одного аккаунта может быть несколько активных установок приложения. Разрешение показывать уведомления в операционной системе и подписка на конкретную категорию хранятся и меняются отдельно.
- В подписке храните пользователя, канал или категорию, состояние и время изменения. Учитывайте правила категории при отправке: уведомление о заказе и рекламная акция могут иметь разные настройки.
- Для установки храните идентификатор, владельца, приложение, транспорт, окружение, актуальный токен и время его обновления. Обновляемый токен привязывайте к установке через авторизованный запрос.
- При выходе из аккаунта снимайте привязку установки к пользователю. При смене аккаунта на том же устройстве это защитит от доставки уведомлений предыдущего владельца.
Для Android используйте FCM HTTP v1. Для iOS можно выбрать прямой APNs или FCM с настроенной интеграцией APNs. Если iOS обслуживает FCM, на сервере используйте выданный FCM токен регистрации. При прямой отправке в APNs используйте токен устройства APNs и правильное окружение приложения.
Определяйте аудиторию до отправки
При персональной отправке берите получателя из авторизованного контекста. Для автоматических сигналов задайте владельца интеграции в её настройках. При адресной отправке проверяйте право отправителя работать с выбранными пользователями. Для рассылки всем отдельно проверяйте право на запуск кампании и ограничивайте выборку нужным приложением, организацией и категорией. Пустой список адресатов должен давать пустую аудиторию.
Для массовой кампании зафиксируйте получателей при запуске, например сохранив записи с идентификаторами установок. Перед отправкой проверьте актуальную подписку и владельца установки, а токен прочитайте заново. Тогда пользователь, отписавшийся после запуска, будет пропущен, а обновление токена во время ожидания не потребует пересоздавать кампанию.
Для общих объявлений можно использовать темы FCM, если приложению подходит модель подписки на тему и достаточно отчётности по запросу отправки. Содержимое тем делайте пригодным для широкой аудитории. Для личных событий и кампаний с учётом результата по каждой установке используйте адресную отправку.
Подготовьте запрос к FCM в PHP 8.3–8.5
Функция ниже собирает JSON для отправки на один токен через FCM HTTP v1. Она задаёт одинаковую подсказку о сроке жизни для Android и APNs. Передавайте один и тот же идентификатор события при повторах. В приложении он пригодится для обработки повторных событий, хотя сам по себе не подавляет дубликаты, которые операционная система уже показала.
<?php
declare(strict_types=1);
function buildFcmRequest(
string $token,
string $eventId,
string $title,
string $body,
int $ttlSeconds = 900,
): string {
if ($ttlSeconds < 1 || $ttlSeconds > 2_419_200) {
throw new InvalidArgumentException('Недопустимый срок жизни push');
}
// Передаём только идентификатор. Детали загрузит приложение.
return json_encode([
'message' => [
'token' => $token,
'notification' => ['title' => $title, 'body' => $body],
'data' => ['event_id' => $eventId],
'android' => ['ttl' => $ttlSeconds . 's'],
'apns' => ['headers' => [
'apns-expiration' => (string) (time() + $ttlSeconds),
]],
],
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
}Передайте этот JSON HTTP-клиенту вашего проекта. Адаптер FCM получает краткоживущий OAuth 2.0 access token через библиотеку Google Auth или учётные данные среды и добавляет его в заголовок Authorization. При прямой отправке через APNs адаптер использует HTTP/2, учётные данные APNs, идентификатор приложения и формат payload Apple. Храните серверные ключи в хранилище секретов. Формируйте запрос непосредственно перед отправкой и рассчитывайте срок жизни по оставшемуся времени актуальности события.
Заголовок и текст могут появиться на заблокированном экране. Для чувствительных событий используйте нейтральное сообщение и открывайте детали внутри приложения после проверки доступа. Если клиент получает event_id, сервер всё равно проверяет права при запросе соответствующих данных.
Свяжите кампанию и очередь в PHP или Yii
HTTP-обработчик проверяет полномочия, сохраняет кампанию и возвращает её идентификатор. Постановку отправки сделайте восстанавливаемой. Например, сохраните кампанию и запись о предстоящей публикации задачи в одной транзакции через transactional outbox. Отдельный процесс подберёт запись и поставит задачу в очередь, даже если веб-процесс завершится сразу после коммита.
В Yii2 разместите создание кампании в сервисе, вызываемом из контроллера. При использовании yii2-queue передавайте в задаче идентификатор кампании или записи доставки. Обработчик загружает состояние из базы, выбирает адаптер и сохраняет результат. Разбивайте аудиторию на порции, ограничивайте параллелизм и держите отдельную очередь или приоритет для срочных уведомлений, чтобы крупная рассылка не задержала сигналы мониторинга.
Уникальное ограничение по паре campaign_id и installation_id защитит от повторного создания одной доставки. При параллельной обработке атомарно захватывайте запись с ограниченным сроком владения. Перед обращением к транспорту проверяйте отмену кампании, срок актуальности и статус доставки. Если воркер потерял соединение после отправки запроса, провайдер мог его принять. Повтор в таком случае может показать уведомление дважды, поэтому для критичных сценариев учитывайте риск дубля в правилах повторной отправки.
Обрабатывайте ошибки и считайте результаты
- Временный отказ. Для ответов о перегрузке, ошибок сервера и сетевых сбоев планируйте ограниченные повторы с увеличивающейся задержкой и случайным разбросом. Если провайдер прислал
Retry-After, учитывайте его. Просроченные сообщения закрывайте без повторной отправки. - Токен недействителен. Деактивируйте токен при явном сигнале транспорта, например
UNREGISTEREDу FCM илиUnregisteredу APNs. Сверяйте токен и версию регистрации с данными запроса, чтобы старый ответ не отключил уже обновлённую установку. - Ошибка запроса или доступа. При отклонении payload исправляйте данные. При проблемах с авторизацией или настройкой транспорта приостановите отправку через затронутый адаптер и разберите причину. Храните код ошибки без полного токена и содержимого личного уведомления.
В отчёте показывайте размер аудитории, долю обработанных записей и количества по исходам: принято транспортом, ожидает повтора, пропущено, истёк срок, окончательный отказ. Успешный ответ FCM или APNs подтверждает приём запроса транспортом. Если продукту важно измерить открытие, фиксируйте событие в приложении и связывайте его с идентификатором уведомления.
Чек-лист перед первой массовой отправкой
- Проверьте права на три режима отправки и убедитесь, что пустой адресный сегмент никого не захватывает.
- Отправьте тестовый push на реальные устройства Android и iOS. Проверьте показ на заблокированном экране и переход в нужный раздел приложения.
- Проверьте отписку после запуска кампании, обновление токена и смену пользователя на одном устройстве.
- Смоделируйте временный отказ транспорта, повторную выдачу задачи и падение воркера во время отправки. Проверьте сроки повторов и статусы в отчёте.
- Перед запуском покажите оператору текст и размер аудитории. Начните с небольшой группы и убедитесь, что кампания отображает прогресс, а отмена останавливает ещё не начатые отправки.
Частые вопросы
Чем в Jeapie массовая рассылка отличалась от адресной?
Метод broadcast/send охватывал всех подписчиков провайдера. Метод users/send отправлял сообщение конкретному подписчику или выбранной группе. В современной реализации эти режимы могут пользоваться одним транспортом и одной очередью, а различаться правилами доступа и выборкой аудитории.
Можно ли отправлять push на Android и iOS из одного PHP-бэкенда?
Да. Бэкенд может обслуживать обе платформы через FCM при настроенной интеграции с APNs для iOS. Другой вариант — отдельные адаптеры FCM и APNs с общими правилами подписки, очередью и отчётом.
Почему успешный ответ FCM или APNs ещё не означает, что пользователь увидел push?
Ответ подтверждает приём запроса транспортом. На показ влияют доступность устройства, срок жизни сообщения и настройки уведомлений. Открытие можно измерять по событию в мобильном приложении.