PHPTime

Jeapie и мобильные PUSH-уведомления из PHP для iOS и Android

Jeapie позволял PHP-скрипту отправить уведомление на телефон через API и готовое мобильное приложение. Сегодня для личных оповещений подходит тот же принцип, а для уведомлений пользователям своего приложения обычно используют FCM или APNs.

Как работал Jeapie и чем его заменить

У Jeapie было две части: приложение принимало сообщения на телефоне, а PHP-скрипт передавал в API ключ проекта, ключ получателя и текст. Так можно было узнать о новом заказе или сбое базы данных, не выпуская собственное приложение. В старом проекте такой вызов можно встретить в виде прямого запроса через cURL, класса PushMessage или расширения для Yii.

При миграции сначала определите, кто получает уведомления. Для дежурного или небольшой команды подойдёт сервис с готовым клиентом под iOS и Android и серверным API. Получатели устанавливают клиент, а бэкенд хранит выданные сервисом идентификаторы. Если PUSH должны приходить пользователям вашего приложения, настройте его интеграцию с Firebase Cloud Messaging (FCM) или Apple Push Notification service (APNs). Ключи Jeapie в новый канал перенести нельзя. Получателей нужно зарегистрировать заново.

Как выбрать канал для iOS и Android

ЗадачаКаналЧто потребуется
Оповещения себе и командеСервис с готовым приложениемКлиент на телефоне, ключ API и идентификатор получателя
Своё приложение на Android и iOSFCMИнтеграция Firebase на обеих платформах. Для iOS также нужна настройка APNs в Firebase
Своё приложение только на iOSAPNs напрямуюТокен устройства от APNs, данные для авторизации отправителя и клиент с поддержкой HTTP/2

На iOS FCM передаёт уведомления через APNs. Если PHP отправляет сообщения через FCM, ему нужен регистрационный токен FCM и на Android, и на iOS. Токен APNs нужен серверу при прямой отправке через APNs. Эти два токена нельзя использовать взаимозаменяемо.

Как зарегистрировать устройство на бэкенде

Приложение получает токен у выбранного провайдера и передаёт его в защищённый эндпоинт вашего API. Привязывайте токен к пользователю из серверной сессии или проверенного токена авторизации. Идентификатор пользователя из тела запроса для такой операции не подходит.

  1. Храните одну запись на установку приложения. Сохраните идентификатор установки, пользователя, провайдера, окружение, токен и время обновления. У одного аккаунта может быть несколько устройств.
  2. При обновлении токена заменяйте его для той же установки. Повторная регистрация должна обновлять существующую запись без дублей.
  3. При выходе из аккаунта удаляйте привязку установки к пользователю. При входе под другой учётной записью обновляйте привязку атомарно, чтобы на общем телефоне не появились уведомления прежнего владельца.
  4. Учитывайте разрешения на показ уведомлений. Приложение может зарегистрировать токен, даже если пользователь запретил видимые уведомления.

Разделите тестовые и рабочие установки и учётные данные. При прямой отправке через APNs используйте окружение, в котором выдан токен. Для FCM токен и отправитель должны относиться к корректно настроенному проекту.

Отправка через FCM HTTP v1 на PHP 8.3–8.5

Пример отправляет видимое уведомление на одну установку. Понадобится расширение curl. В FCM_SEND_ENDPOINT передайте полный адрес метода отправки HTTP v1 для своего проекта. FCM_ACCESS_TOKEN должен содержать краткоживущий OAuth 2.0 access token с областью доступа firebase.messaging. Для разового запуска можно передать уже полученный токен, а рабочему процессу поручите получение и обновление токена библиотеке Google Auth. Учётные данные должны иметь право отправлять сообщения в целевой проект.

PHP
<?php
declare(strict_types=1);

function requiredEnv(string $name): string
{
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Не задана переменная {$name}");
    }
    return $value;
}

// Токен установки в рабочем приложении берётся из базы.
$payload = json_encode([
    'message' => [
        'token' => requiredEnv('FCM_DEVICE_TOKEN'),
        'notification' => [
            'title' => 'Новый заказ',
            'body' => 'Откройте приложение, чтобы посмотреть детали.',
        ],
        // В FCM значения полей data должны быть строками.
        'data' => ['event_id' => 'order-created-481'],
    ],
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);

$endpoint = requiredEnv('FCM_SEND_ENDPOINT');
$accessToken = requiredEnv('FCM_ACCESS_TOKEN');
$curl = curl_init($endpoint);
if ($curl === false) {
    throw new RuntimeException('Не удалось создать запрос cURL');
}

curl_setopt_array($curl, [
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($curl);
if ($response === false) {
    throw new RuntimeException('Ошибка транспорта cURL: ' . curl_errno($curl));
}

$status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200 || !is_string($result['name'] ?? null)) {
    // Сохраняем код ошибки. Токены и тело запроса в журнал не пишем.
    $reason = $result['error']['status'] ?? 'UNKNOWN';
    throw new RuntimeException("FCM вернул {$status}: {$reason}");
}

echo $result['name'], PHP_EOL;

Поле name означает, что FCM принял сообщение. Факт показа на телефоне этим ответом установить нельзя. Блок notification задаёт заголовок и текст, а data передаёт приложению служебные поля. Обработку нажатия и поведение при открытом приложении проверяйте отдельно на обеих платформах. Данные заказа загружайте с бэкенда после авторизации. Само уведомление может быть видно на заблокированном экране.

Повторы, устаревшие токены и сбои провайдера

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

  • Токен больше не зарегистрирован. В рабочем обработчике разбирайте error.details и ищите код FCM UNREGISTERED. Удаляйте или отключайте именно тот токен, с которым ушёл запрос. К моменту ответа приложение уже могло зарегистрировать новый.
  • Ошибка запроса или авторизации. При 400 проверьте полезную нагрузку. При сбое авторизации допускается обновить просроченный access token и повторить запрос один раз. Если свежий токен не помогает, проверьте права отправителя, проект и детали ответа.
  • Временная ошибка. При 429, 500 или 503 отложите повтор. Учитывайте Retry-After, если он есть. Увеличивайте интервалы со случайным разбросом и прекращайте попытки, когда уведомление теряет смысл.
  • Таймаут. Сервер мог принять запрос до обрыва соединения. Используйте стабильный идентификатор события для дедупликации заданий и обработки данных в приложении. Даже с таким идентификатором повтор может показать второй системный баннер.

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

Чек-лист перед включением PUSH

  • Выберите канал по получателям. Для оповещений команды используйте готовый клиент, для пользователей продукта подключите своё приложение к FCM или APNs.
  • Проверьте регистрацию, обновление токена и выход из аккаунта. Отдельно проверьте смену пользователя на одном телефоне.
  • Отправьте тестовое сообщение на реальный iPhone и Android. Проверьте показ при открытом и свёрнутом приложении, на заблокированном экране и при выключенных разрешениях.
  • Проверьте очередь на временной ошибке, просроченном задании и отозванном токене. Убедитесь, что операция, породившая уведомление, работает при недоступности провайдера.
  • При переносе с Jeapie сохраните места, где приложение создаёт события, и переключите отправку на новый канал после регистрации получателей и тестовой доставки.

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

Можно ли отправить PUSH из PHP без своего мобильного приложения?

Да. Выберите сервис с готовым приложением для получателя и серверным API. Получатель устанавливает клиент и привязывает его к своему аккаунту, после чего PHP может отправлять туда уведомления.

Можно ли отправлять PUSH на iPhone через Firebase?

Да. Подключите Firebase Messaging в приложении, настройте учётные данные APNs в Firebase и передавайте на PHP-бэкенд регистрационный токен FCM. Firebase доставит сообщение на iOS через APNs.

Почему FCM вернул HTTP 200, а уведомление на телефоне не появилось?

Код 200 подтверждает приём сообщения FCM. Проверьте разрешение на показ уведомлений, режим фокусирования, сетевое подключение, содержимое сообщения и обработку уведомлений при открытом приложении. Для iOS также проверьте конфигурацию APNs.

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

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

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

Как настроить Web Push в Chrome и Safari на PHP 8.3–8.5: запросить разрешение, сохранить подписку, отправить уведомление и обработать ошибки доставки.

8 мин

Не работает 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 мин