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 и iOS | FCM | Интеграция Firebase на обеих платформах. Для iOS также нужна настройка APNs в Firebase |
| Своё приложение только на iOS | APNs напрямую | Токен устройства от APNs, данные для авторизации отправителя и клиент с поддержкой HTTP/2 |
На iOS FCM передаёт уведомления через APNs. Если PHP отправляет сообщения через FCM, ему нужен регистрационный токен FCM и на Android, и на iOS. Токен APNs нужен серверу при прямой отправке через APNs. Эти два токена нельзя использовать взаимозаменяемо.
Как зарегистрировать устройство на бэкенде
Приложение получает токен у выбранного провайдера и передаёт его в защищённый эндпоинт вашего API. Привязывайте токен к пользователю из серверной сессии или проверенного токена авторизации. Идентификатор пользователя из тела запроса для такой операции не подходит.
- Храните одну запись на установку приложения. Сохраните идентификатор установки, пользователя, провайдера, окружение, токен и время обновления. У одного аккаунта может быть несколько устройств.
- При обновлении токена заменяйте его для той же установки. Повторная регистрация должна обновлять существующую запись без дублей.
- При выходе из аккаунта удаляйте привязку установки к пользователю. При входе под другой учётной записью обновляйте привязку атомарно, чтобы на общем телефоне не появились уведомления прежнего владельца.
- Учитывайте разрешения на показ уведомлений. Приложение может зарегистрировать токен, даже если пользователь запретил видимые уведомления.
Разделите тестовые и рабочие установки и учётные данные. При прямой отправке через 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
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и ищите код FCMUNREGISTERED. Удаляйте или отключайте именно тот токен, с которым ушёл запрос. К моменту ответа приложение уже могло зарегистрировать новый. - Ошибка запроса или авторизации. При
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.