Как работают push-уведомления: APNs и FCM

Push-уведомление со стороны выглядит просто: на сервере что-то происходит, а через секунду телефон загорается. Между ними стоят две сети доставки, которыми управляют Apple и Google, и ни одно уведомление не доходит до телефона в обход них.
- APNs, Apple Push Notification service, доставляет каждое push-уведомление на iPhone, iPad, Mac и Apple Watch.
- FCM, Firebase Cloud Messaging, доставляет на Android-устройства с сервисами Google Play и может отправлять на iOS, передавая сообщения в APNs.
В этом руководстве одно уведомление проходит путь от вашего сервера до экрана блокировки на обеих платформах. Затрагиваются детали, которые проявляются только в продакшене. Мы работаем с обоими конвейерами в Pocket Alert, поэтому примеры взяты из того, что мы реально выпускаем.
Четыре участника
- Ваш сервер, который Apple называет провайдером. Он решает, что нужно отправить.
- Служба push-уведомлений, APNs или FCM. Она принимает запрос и маршрутизирует его.
- Устройство. Операционная система держит одно долгоживущее зашифрованное соединение с Apple или Google и получает через него push-уведомления для всех приложений.
- Приложение. Оно зарегистрировалось для уведомлений и владеет токеном, на который адресовано push-уведомление.
Третий пункт объясняет, почему push почти не расходует батарею. Телефон никогда не опрашивает ваш сервер. Одно соединение, общее для всех приложений, остаётся открытым, и служба push-уведомлений отправляет по нему данные, когда есть что доставить.
Шаг 1: устройство получает токен
Когда приложение регистрируется для удалённых уведомлений, ОС передаёт ему токен: непрозрачный адрес «это приложение на этом устройстве». Приложение отправляет токен на ваш сервер, а сервер его сохраняет.
- Токен устройства APNs привязан к приложению и устройству. Apple рекомендует не кешировать его в приложении: он меняется при восстановлении из резервной копии, переходе на новое устройство или переустановке ОС.
- Токен регистрации FCM играет ту же роль на Android, и FCM обновляет его по собственному расписанию.
Токены постоянно устаревают. Поддержание сохранённых токенов в актуальном состоянии — значительная часть работы с push-уведомлениями.
Шаг 2: ваш сервер подтверждает, кто он
APNs
APNs работает по HTTP/2 поверх TLS 1.2 или новее: api.push.apple.com для продакшена и api.sandbox.push.apple.com для сборок в разработке, порт 443 или 2197. Есть два способа аутентификации:
- По токену. В вашем аккаунте разработчика Apple создаётся ключ подписи
.p8, которым подписывается короткий JWT с алгоритмом ES256; в нём указаны Team ID и ID ключа. Apple требует обновлять JWT не чаще раза в 20 минут и не реже раза в 60. Если отправить старый, вы получите403 ExpiredProviderToken; если обновлять слишком часто, получите429 TooManyProviderTokenUpdates. - По сертификату. Один клиентский TLS-сертификат на приложение, действует год, потом его нужно продлевать.
Используйте аутентификацию по токену. Один ключ подходит для всех ваших приложений и не истекает каждый год.
FCM
HTTP v1 API FCM принимает короткоживущий OAuth 2.0 access token от сервисного аккаунта Google с областью firebase.messaging. Старый «legacy» API со статическим серверным ключом объявлен устаревшим в 2023 году и отключён с июля 2024 года, поэтому код, который всё ещё отправляет Authorization: key=..., больше не работает.
Шаг 3: запрос
Отправка в APNs
Каждое push-уведомление — это HTTP/2 POST на /3/device/<device token> с несколькими заголовками, которые меняют способ обработки:
curl --http2 \
-H "authorization: bearer $APNS_JWT" \
-H "apns-topic: com.example.alerts" \
-H "apns-push-type: alert" \
-H "apns-priority: 10" \
-d '{"aps": {"alert": {"title": "Backup failed", "body": "db-01: pg_dump exited with code 1"}, "sound": "default", "interruption-level": "time-sensitive"}}' \
"https://api.push.apple.com/3/device/$DEVICE_TOKEN"
apns-topic— это bundle ID вашего приложения.apns-push-typeопределяет тип уведомления:alertдля видимого уведомления,backgroundдля тихого push с данными и несколько других.apns-priority:10— доставить немедленно,5— доставить с учётом энергосостояния устройства,1— экономить энергию и не будить устройство.apns-expirationзадаёт, как долго APNs должен пытаться доставить.0означает одну попытку без хранения.apns-collapse-idпозволяет новому уведомлению заменить старое с тем же идентификатором.
Полезная нагрузка — это JSON со словарём aps, и её размер ограничен 4 КБ (5 КБ для VoIP).
Отправка в FCM
FCM принимает одно JSON-сообщение в запросе:
curl -X POST "https://fcm.googleapis.com/v1/projects/$PROJECT_ID/messages:send" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"message": {
"token": "DEVICE_REGISTRATION_TOKEN",
"notification": { "title": "Backup failed", "body": "db-01: pg_dump exited with code 1" },
"android": { "priority": "high", "notification": { "channel_id": "alerts_high" } }
}
}'
Сообщение с notification отображается системой, когда приложение в фоне. Сообщение с data передаётся приложению для обработки. В обоих случаях ограничение полезной нагрузки — 4 096 байт.
Шаг 4: доставка или ожидание
Если телефон в сети, push-уведомление идёт по открытому соединению и появляется почти мгновенно. Если нет:
- APNs хранит уведомление до 30 дней, в зависимости от
apns-expiration, но сохраняет только одно уведомление на приложение и устройство. Если отправить пять, пока телефон в режиме полёта, он, скорее всего, получит последнее. Apple даже не гарантирует, что это будет самое новое. - FCM хранит сообщения в течение их времени жизни: по умолчанию четыре недели, максимум 28 дней. Сворачиваемые сообщения заменяют друг друга, до четырёх ключей сворачивания на устройство.
Приоритет влияет и на время доставки. На iOS push-уведомления с приоритетом 5 и 1 могут группироваться, притормаживаться или отбрасываться. На Android сообщения с приоритетом normal могут ждать, пока устройство выйдет из Doze, а с приоритетом high доставляются сразу. FCM также следит за тем, как используется эта привилегия: сообщения с высоким приоритетом, которые не приводят к видимому уведомлению, со временем могут тихо понизиться до normal.
Насколько громко: уровни прерывания и каналы
Доставка — одно дело. Издаёт ли телефон звук — другое, и платформы обрабатывают это по-разному.
iOS (15 и новее) присваивает каждому уведомлению уровень прерывания:
passiveдобавляет уведомление в список, не включая экран и не воспроизводя звук.active— значение по умолчанию.time-sensitiveможет пробиться через Фокусирование и сводку уведомлений. Пользователи могут отключить это для каждого приложения.criticalвсегда воспроизводится, даже в режиме «Не беспокоить» и при включённом переключателе беззвучного режима. Для него нужно право (entitlement), которое Apple выдаёт по запросу после проверки.
Android (8 и новее) помещает каждое уведомление в канал, и канал определяет важность: звук, вибрацию, всплывающее уведомление, поведение в режиме «Не беспокоить». Приложение создаёт каналы, но когда канал существует, его поведение принадлежит пользователю. Приложение не может изменить его позже.
Это правило имеет реальные последствия. Когда мы добавили в Pocket Alert критические оповещения, которые звучат даже в беззвучном режиме, существующий канал критических уведомлений нельзя было задним числом переключить на звук будильника. Решением стал второй канал с новым идентификатором. Сервер выбирает его только для сборок приложения, которые его создают, потому что отправка в канал, которого приложение не создавало, означает, что уведомление вообще не будет показано.
На Android 13 и новее есть ещё один барьер: приложению нужно разрешение времени выполнения POST_NOTIFICATIONS, и при свежей установке уведомления остаются выключенными, пока пользователь его не выдаст.
Что ломается в продакшене
- Устаревшие токены. APNs отвечает
410 Unregisteredна токен, который больше не действителен. Прекратите отправку на него и удалите его. - Неверное окружение. Токен сборки для разработки, отправленный на продакшен-хост, завершится ошибкой
400 BadDeviceToken. - Слишком большая полезная нагрузка.
413 PayloadTooLarge, если превысить 4 КБ. Обычная причина — длинные строки логов в тексте оповещения. - Понижение приоритета. Сообщения Android с высоким приоритетом, которые ничего не показывают, теряют его.
- Выключенные уведомления. Push доставлен, но пользователь его не видит, потому что разрешение отклонено или канал отключён.
Короткий путь
Всё это стоит строить, когда приложение — ваш продукт и вы отправляете его пользователям. Для оповещений себе или команде это слишком много инфраструктуры: аккаунт разработчика на каждой платформе, ключи подписи, хранение токенов, два формата запросов и две модели приоритетов.
Сервис push-уведомлений запускает оба конвейера за вас. С Pocket Alert вы отправляете один запрос без собственных токенов и сертификатов:
curl -X POST https://api.pocketalert.app/v1/messages \
-H "Token: $PA_KEY" \
-H 'Content-Type: application/json' \
-d '{"title": "Backup failed", "message": "db-01: pg_dump exited with code 1", "level": "high"}'
Поле level преобразуется для каждой платформы:
silent— пассивное уведомление без звука на iPhone и отправка в беззвучный канал на Android.low— пассивное на iPhone и низкая важность на Android.default— обычное уведомление на обеих платформах.high— time-sensitive на iPhone и высокий приоритет на Android.criticalобходит режим «Не беспокоить» на Android. На iPhone он приходит как time-sensitive, а полноценный звук критических оповещений появится по мере того, как Apple будет выдавать право.
Подробнее об этом читайте в статье про критические оповещения, а об API — в статье что такое API push-уведомлений.
Частые вопросы
Гарантирует ли APNs доставку?
Нет. APNs и FCM работают по принципу «по возможности». APNs хранит для офлайн-устройства только последнее уведомление, и ни одна из служб не гарантирует, когда придёт сообщение. Документация Google идёт дальше и говорит, что FCM не следует использовать для экстренных оповещений, от которых зависит жизнь. Для вызова дежурных используйте push как самый быстрый канал, но не единственный.
Зачем нужны и APNs, и FCM?
iPhone принимают push-уведомления только через APNs. Android-устройства с сервисами Google Play получают их через FCM. Если ваши пользователи на обеих платформах, сервер работает с обеими, напрямую или через FCM, который может переслать сообщение в APNs.
Может ли FCM отправлять уведомления на iPhone?
Да. Вы загружаете ключ аутентификации APNs в Firebase, и FCM доставляет сообщения на iOS, передавая их в APNs. Сообщения с данными для устройств Apple нужно отправлять с обычным приоритетом.
Насколько большим может быть push-уведомление?
4 КБ для полезной нагрузки APNs (5 КБ для VoIP-push) и 4 096 байт для сообщения FCM. Длинный текст лучше хранить в приложении или в ссылке, а не в push-уведомлении.
Что такое токен устройства?
Адрес одного приложения на одном устройстве, который выдают Apple или Google. Ваш сервер отправляет на него push-уведомления. Он может измениться в любой момент, поэтому серверы должны принимать обновлённые токены и удалять те, которые APNs или FCM сообщают как недействительные.
Создайте бесплатный аккаунт Pocket Alert, чтобы не возиться с ключами и токенами, или сравните другие сервисы в разделе альтернативы.