Назад в блог

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

Как работают 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, поэтому примеры взяты из того, что мы реально выпускаем.

Четыре участника

  1. Ваш сервер, который Apple называет провайдером. Он решает, что нужно отправить.
  2. Служба push-уведомлений, APNs или FCM. Она принимает запрос и маршрутизирует его.
  3. Устройство. Операционная система держит одно долгоживущее зашифрованное соединение с Apple или Google и получает через него push-уведомления для всех приложений.
  4. Приложение. Оно зарегистрировалось для уведомлений и владеет токеном, на который адресовано 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, чтобы не возиться с ключами и токенами, или сравните другие сервисы в разделе альтернативы.

Поделиться статьёй