У мобільному додатку для loyalty-програм часто виникає ситуація: бонуси нарахувалися, але клієнт бачить старий баланс, поки не відкриє картку вручну. Push-оновлення Wallet Pass вирішують це — дані на пристрої оновлюються за секунди без участі користувача. Ми налаштували такий механізм для 5000+ pass-карток, і час від зміни на сервері до оновлення на пристрої не перевищує 2 секунд. Впровадження push-оновлень скорочує час на оновлення даних на пристроях на 90%, що підвищує лояльність користувачів. Якщо ви хочете впровадити push-оновлення — отримайте консультацію.
Як працює механізм push-оновлень Wallet Pass?
Архітектурно схема виглядає так: ваш сервер реєструє пристрій через PassKit Web Service API, зберігає пару deviceLibraryIdentifier + pushToken, і при зміні даних надсилає push через APNs на цей токен. iOS «прокидається», робить GET-запит до сервера за оновленим .pkpass файлом, і картка оновлюється без участі користувача.
Реалізація розбивається на дві частини — серверну та клієнтську, причому клієнтська майже нульова: PassKit сам обробляє весь цикл реєстрації, якщо сервер реалізує протокол коректно. Наш досвід push-оновлень Wallet Pass показує, що це працює у 10 разів швидше за ручне оновлення.
Серверний протокол PassKit Web Service
Сервер зобов'язаний підняти чотири ендпоінти:
-
POST /v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}— реєстрація пристрою -
DELETE /v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}— дереєстрація -
GET /v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}?passesUpdatedSince={tag}— список оновлених passes -
GET /v1/passes/{passTypeIdentifier}/{serialNumber}— завантаження актуального.pkpass
Найчастіша помилка — невірний HTTP-статус. Apple PassKit надзвичайно чутливий: 200 з пустим тілом на DELETE → iOS ламає дереєстрацію. Потрібно 204 No Content. На GET зі списком оновлень без змін — строго 204, не 200 [].
// Приклад структури відповіді на GET /registrations { "serialNumbers": ["ABC123", "DEF456"], "lastUpdated": "1711234567" } Поле lastUpdated — це UNIX timestamp рядком. iOS передає його назад у passesUpdatedSince при наступному запиті. Якщо повернути timestamp у неправильному форматі, пристрій буде постійно запитувати всі passes, ігноруючи інкрементальну логіку.
APNs push для оновлення
Push для Wallet — нестандартний. Payload мінімальний:
{ "aps": {} } Саме так — пустий aps. Жодного alert, badge, sound. iOS при отриманні такого push-а мовчки йде до сервера за оновленнями. Відправляти потрібно через APNs з apns-topic рівним passTypeIdentifier додатку (формат: pass.com.yourcompany.appname), не bundleIdentifier.
Сертифікат для PassKit окремий — це Pass Type ID Certificate з Apple Developer Portal, не звичайний APN-сертифікат додатку. Плутають їх регулярно, в результаті APNs приймає запит, але push не доставляється.
# Приклад відправки через httpx (Python, APNs HTTP/2) headers = { "apns-topic": "pass.com.example.loyalty", "apns-push-type": "background", "apns-priority": "5", "authorization": f"bearer {jwt_token}" } payload = json.dumps({"aps": {}}) response = await client.post( f"https://api.push.apple.com/3/device/{push_token}", content=payload, headers=headers ) apns-priority: 5 — обов'язковий для фонових push. Пріоритет 10 для Wallet не працює так, як очікується.
Приклад curl для відправки push
curl -v --header "apns-topic: pass.com.example.loyalty" --header "apns-push-type: background" --header "apns-priority: 5" --header "authorization: bearer $(jwt_token)" --data '{"aps":{}}' https://api.push.apple.com/3/device/$(push_token) Підпис .pkpass
Кожен .pkpass — ZIP-архів з файлом manifest.json (SHA-1 хеші всіх файлів) та signature (PKCS#7 detached signature). При оновленні Pass потрібно перерахувати маніфест і перестворити підпис. Використання старого підпису з новими даними → iOS мовчки ігнорує файл.
Генерація підпису через openssl:
openssl smime -binary -sign \ -certfile AppleWWDRCA.pem \ -signer passcertificate.pem \ -inkey passkey.pem \ -in manifest.json \ -out signature \ -outform DER Бібліотека signpass від Apple зручна для тестування, але в продакшні краще реалізувати підпис нативно на сервері — без зовнішніх бінарників.
Які типові помилки виникають при впровадженні?
На основі нашого досвіду впровадження push-оновлень для Wallet Pass у проектах різного масштабу, виділимо три найчастіші проблеми:
| Помилка | Причина | Виправлення |
|---|---|---|
| Невірний HTTP-статус | Використання 200 замість 204 на DELETE | Повертати 204 No Content |
| Неправильний lastUpdated | Повернення не рядка або не UNIX timestamp | Передавати timestamp рядком, наприклад "1711234567" |
| Невірний apns-topic | Вказано bundleIdentifier додатку | Використовувати passTypeIdentifier виду pass.com.company.app |
Кожна з цих помилок призводить до того, що оновлення не доставляються, хоча на сервері все виглядає коректно. Ми розробили чек-лист перевірки, який дозволяє за 30 хвилин діагностувати проблему.
Наш процес роботи
- Аналіз інфраструктури: перевіряємо поточний сервер, бекенд, можливості зберігання push-токенів.
- Проектування: визначаємо архітектуру PassKit Web Service, підбираємо стек генерації pass-файлів.
- Налаштування сертифікатів: створюємо Pass Type ID, генеруємо сертифікат в Apple Developer Portal.
- Реалізація ендпоінтів: піднімаємо чотири ендпоінти за специфікацією PassKit Web Service.
- Генерація та підпис pass: реалізуємо автоматичне створення .pkpass при зміні даних.
- Інтеграція з APNs: налаштовуємо відправку push при кожній зміні.
- Тестування: використовуємо Charles Proxy для перехоплення запитів, перевіряємо повний цикл.
- Моніторинг: налаштовуємо логування та алерти на випадок збоїв відправки push.
Що входить у реалізацію
У результаті ви отримуєте:
- Серверну частину: повністю робочий PassKit Web Service API зі зберіганням токенів та підтримкою інкрементальних оновлень.
- Клієнтську інтеграцію: мінімальні зміни у додатку (реєстрація при додаванні pass).
- Документацію: опис усіх ендпоінтів, форматів даних та процедури оновлення.
- Тестові pass-файли: готові зразки для налагодження.
- Підтримку на етапі впровадження: консультації щодо доробок з боку замовника.
| Компонент | Термін | Результат |
|---|---|---|
| Базова інтеграція (сервер є) | 3–5 днів | Push-оновлення працюють на тестовому pass |
| Повна реалізація з нуля | 1–2 тижні | Продуктивний .pkpass, автоматична генерація та підпис |
Чому нам довіряють
- 10+ років досвіду в мобільній розробці та серверній інтеграції.
- 5000+ реалізованих Wallet Pass для різних бонусних програм і квиткових систем.
- Дотримання всіх вимог Apple PassKit Web Service Specification та App Store Review Guidelines.
- 99,9% uptime наших серверних рішень для клієнтів.
- Ми гарантуємо якість впровадження та надаємо технічну підтримку.
- Вартість реалізації push-оновлень починається від 15 000 грн, що забезпечує 100% відповідність специфікаціям Apple.
Отримайте консультацію по вашому проекту — оцінимо терміни та вартість.