APNS: що це, як влаштований Apple Push Notification Service та як він працює

Що таке APNS?

Apple Push Notification Service (APNS) — це власний сервіс Apple для маршрутизації push-сповіщень від сервера застосунку до пристроїв користувачів. На відміну від FCM, APNS не підтримує Android або інші платформи — він повністю прив'язаний до екосистеми Apple.

Сервіс працює через постійне TLS-з'єднання, яке кожен пристрій Apple встановлює з серверами APNS при запуску. Це з'єднання підтримується у фоновому режимі та використовується для доставки сповіщень з мінімальною затримкою.

APNS бере на себе всю інфраструктуру доставки: шифрування, автентифікацію, пріоритезацію та повторне надсилання у разі недоступності пристрою. Розробнику потрібно лише надати правильно сформований payload та дійсний push token.

Еволюція APNS

Спочатку APNS працював через бінарний протокол на портах 2195–2196. З 2015 року Apple перевела сервіс на сучасний протокол HTTP/2, який підтримує мультиплексування, стиснення заголовків та серверні push-сповіщення. HTTP/2 став обов'язковим з червня 2020 року.

Як працює Apple Push Notification Service?

Процес доставки push-сповіщення через APNS складається з п'яти етапів: реєстрація пристрою, отримання push token, надсилання запиту сервером, маршрутизація APNS та доставка на пристрій.

• Реєстрація — при запуску застосунок викликає registerForRemoteNotifications, система зв'язується з APNS
• Токен — APNS повертає пристрою push token — унікальний рядок, що ідентифікує застосунок на пристрої
• Надсилання — сервер застосунку надсилає POST-запит на https://api.push.apple.com з токеном та payload
• Маршрутизація — APNS знаходить пристрій за токеном та доставляє повідомлення через TLS-з'єднання
• Обробка — iOS/macOS показує сповіщення або передає його в застосунок залежно від стану

Якщо пристрій недоступний (вимкнено або немає мережі), APNS зберігає останнє повідомлення для кожного застосунку та доставляє його при відновленні з'єднання. Максимальний термін зберігання — 4 тижні, після чого повідомлення видаляється.

Автентифікація в APNS: Token та Certificate

Apple підтримує два способи автентифікації сервера застосунку при надсиланні push-сповіщень. Кожен спосіб має свої особливості щодо терміну дії, управління та зручності використання.

Token-based автентифікація — рекомендований Apple спосіб з 2019 року. Ви створюєте один ключ p8 в Apple Developer Console, завантажуєте його на сервер та підписуєте ним кожен APNS-запит. Ключ не закінчується та працює для всіх застосунків вашого облікового запису.

Який спосіб автентифікації обрати

Для нових проєктів Token-based автентифікація однозначно краща: один ключ p8 на весь обліковий запис, безстроковий, без прив'язки до середовища. Certificate-based (.p12) все ще використовується в застарілих проєктах, але вимагає щорічної заміни та окремих сертифікатів для Sandbox та Production. Враховуйте термін дії сертифіката при плануванні CI/CD.

Типи push-сповіщень APNS

APNS підтримує три типи push-сповіщень, які відрізняються за поведінкою на пристрої та вимогами до атрибутів запиту. Вибір типу залежить від UX-сценарію та терміновості повідомлення.

• Alert — стандартне сповіщення із заголовком, текстом та опціональними кнопками дій
• Background — тиха доставка даних (silent push) без показу користувачу, обробляється в application:didReceiveRemoteNotification
• VOIP — спеціальний тип для VoIP-застосунків (PushKit), доставляється одразу навіть при закритому застосунку

Для Background сповіщень необхідно вказати ключ content-available: 1 та встановити пріоритет 5 (енергоефективна доставка). Система може обмежити кількість фонових сповіщень, якщо застосунок не обробляє їх своєчасно.

Налаштування пріоритету доставки

APNS підтримує два значення пріоритету: 10 (негайна доставка) та 5 (енергоефективна). Для alert-сповіщень використовуйте 10 — користувач повинен отримати їх одразу. Для background-сповіщень використовуйте 5 — система може затримати доставку для економії батареї. Некоректний пріоритет для background може призвести до відхилення сповіщення APNS.

Формат корисного навантаження APNS

APNS приймає payload у форматі JSON з максимальним розміром 4 КБ для звичайних сповіщень та 5 КБ для VOIP. Payload містить обов'язковий словник aps з налаштуваннями відображення та опціональні кастомні поля.

{
    "aps": {
        "alert": {
            "title": "Нове повідомлення",
            "body": "У вас 3 непрочитаних чати"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

Ключ thread-id об'єднує сповіщення в групи в Центрі сповіщень iOS. Ключ category пов'язує сповіщення з UNNotificationCategory для показу кнопок дій. Без цих ключів всі сповіщення відображаються окремо.

Кастомні поля в APNS-пейлоаді

Окрім обов'язкового словника aps, APNS-пейлоад може містити будь-які кастомні поля на верхньому рівні. Ці поля доступні застосунку через словник userInfo при обробці сповіщення. Кастомні дані зручні для передачі ідентифікаторів сутностей, екранів або посилань. Максимальний розмір пейлоаду — 4 КБ, тому уникайте передачі великих обсягів даних через push; завантажуйте їх через API після відкриття сповіщення.

Приклад надсилання через HTTP/2 API

Для надсилання push-сповіщення на сервері необхідно виконати POST-запит до APNS endpoint з коректними заголовками автентифікації. Нижче наведено приклад на Node.js з використанням Token-based автентифікації.

const http2 = require("http2")
const fs = require("fs")
const jwt = require("jsonwebtoken")

const token = jwt.sign(
    { iss: "TEAM_ID", iat: Math.floor(Date.now() / 1000) },
    fs.readFileSync("AuthKey.p8"),
    { algorithm: "ES256", keyid: "KEY_ID" }
)

const payload = JSON.stringify({
    aps: { alert: { title: "Привіт!", body: "Тестовий push" } }
})

const client = http2.connect(
    "https://api.push.apple.com"
)

const req = client.request({
    ":method": "POST",
    ":path": "/3/device/DEVICE_PUSH_TOKEN",
    "authorization": "bearer " + token,
    "apns-push-type": "alert",
    "apns-topic": "com.example.app",
    "apns-priority": "10"
})
req.end(payload)

req.on("response", (headers) => {
    if (headers[":status"] === 200) {
        console.log("Push успішно надіслано")
    }
})

Після надсилання APNS повертає HTTP-статус 200 при успішній доставці або код помилки з описом у тілі відповіді. Важливо обробляти помилки token-unregistered (410) — такий токен слід видалити з сервера, оскільки застосунок було видалено з пристрою.

Помилки APNS та їх обробка

APNS повертає HTTP-статуси для кожного запиту надсилання. Успішна доставка — статус 200. Помилки вимагають різних стратегій обробки. BadDeviceToken (400) або Unregistered (410) — токен пристрою застарів, його потрібно видалити з сервера. PayloadTooLarge (413) — перевищено ліміт 4 КБ, скоротить пейлоад.

Помилка TooManyRequests (429) — перевищено ліміт запитів. APNS встановлює квоту на кількість надсилань за секунду. При отриманні 429 необхідно впровадити експоненційну затримку (exponential backoff) та повторити надсилання. Рекомендується не перевищувати 100 запитів за секунду на одне з'єднання HTTP/2.

Помилки на стороні APNS — 500 та 503 (Internal Server Error / Service Unavailable). Це тимчасові збої інфраструктури Apple. В таких випадках повторюйте надсилання із затримкою 1–5 секунд, не більше 3 спроб. Постійні помилки 5xx при повністю робочому сервері — рідкісне явище, зазвичай пов'язане з проблемами TLS-з'єднання.

Для Production-середовища обов'язково реалізуйте логування всіх помилок APNS із зазначенням токена, коду помилки та часу. Це допоможе швидко виявити проблеми з сертифікатами, квотами або конкретними токенами пристроїв. Регулярно перевіряйте термін дії сертифікатів, якщо використовуєте Certificate-based автентифікацію.