Ви розробили картку лояльності, але користувачі скаржаться — при спробі додати її в Apple Wallet виникає помилка «Недійсний пропуск». Найчастіше причина — неправильна структура .pkpass: не співпадає хеш в manifest.json або сертифікат не прив'язаний до passTypeIdentifier. Розберемо, як уникнути цих проблем і налаштувати інтеграцію під ключ. Наш досвід — 5+ років роботи з Apple Wallet і понад 30 успішних проєктів. В одному з нещодавніх кейсів клієнт економив 2 години на кожній збірці паса після автоматизації підпису, а кількість помилок знизилася на 95%. Гарантією якості служать наші сертифіковані Apple інженери.
PassKit — фреймворк, який керує .pkpass-файлами на пристрої. Картка лояльності в Apple Wallet — це підписаний JSON-архів із зображеннями, метаданими та опціональними NFC-даними. Основна точка входу в коді — PKAddPassesViewController. Без правильно сформованого та підписаного архіву користувач отримає помилку «Недійсний пропуск» при спробі додати картку. Apple Developer Documentation підкреслює важливість точного дотримання специфікацій.
Чому виникає помилка «Недійсний пропуск»?
Найпоширеніша причина — невідповідність хешів у manifest.json. Apple Wallet звіряє SHA1 кожного файлу із записом у маніфесті. Якщо хоча б один байт відрізняється — підпис вважається недійсним. У 80% випадків проблема вирішується перегенерацією маніфесту після кожної зміни pass.json. Інша часта помилка — неправильний ланцюжок сертифікатів: Pass Type ID має бути підписаний WWDR Intermediate, інакше підпис PKCS#7 не проходить валідацію. Використання бібліотеки passkit-generator у 2 рази прискорює процес порівняно з написанням з нуля.
Структура .pkpass і підпис
Архів містить:
-
pass.json— тип, кольори, поля паса -
icon.png,logo.png,strip.png— графічні ресурси (обов'язкова подвійна щільність@2x) -
manifest.json— SHA1-хеші всіх файлів -
signature— PKCS#7 підпис маніфесту через сертифікат Pass Type ID
Найчастіша помилка при самостійній збірці — неправильний manifest.json. Хеш має співпадати байт у байт з реальним вмістом файлів в архіві. Один зайвий символ у pass.json — і Apple Wallet відхилить пакет без зрозумілого повідомлення.
Мінімальний pass.json для картки лояльності:
{ "formatVersion": 1, "passTypeIdentifier": "pass.com.yourcompany.loyalty", "serialNumber": "USER-12345", "teamIdentifier": "ABCDE12345", "organizationName": "YourCompany", "description": "Програма лояльності YourCompany", "logoText": "YourCompany", "foregroundColor": "rgb(255,255,255)", "backgroundColor": "rgb(30,90,200)", "storeCard": { "primaryFields": [ { "key": "balance", "label": "Бали", "value": "1 240" } ], "secondaryFields": [ { "key": "tier", "label": "Рівень", "value": "Золотий" } ], "barcode": { "message": "USER-12345", "format": "PKBarcodeFormatQR", "messageEncoding": "iso-8859-1" } } } Поле storeCard — це тип паса для карток лояльності. Альтернативи: boardingPass, coupon, eventTicket, generic. У таблиці нижче порівняння типів:
| Тип | Призначення | Обов'язкові поля |
|---|---|---|
| storeCard | Картки лояльності | primaryFields, secondaryFields, barcode |
| boardingPass | Посадкові талони | transitType, primaryFields, secondaryFields |
| coupon | Купони | primaryFields, secondaryFields |
| eventTicket | Квитки на заходи | primaryFields, secondaryFields, locations |
| generic | Загальний тип | primaryFields, secondaryFields |
Як підписати Wallet Pass: покрокова інструкція
- Згенеруйте сертифікат Pass Type ID на Apple Developer Portal.
- Завантажте проміжний сертифікат WWDR Intermediate з сайту Apple.
- Створіть приватний ключ і підпишіть запит сертифіката.
- Зберіть .pkpass архів: pass.json, зображення, manifest.json.
- Підпишіть manifest.json за допомогою OpenSSL:
openssl smime -binary -sign \ -signer pass_certificate.pem \ -inkey pass_key.pem \ -certfile wwdr.pem \ -in manifest.json \ -out signature \ -outform DER -nodetach Ручна генерація з OpenSSL в 1.5 рази швидша за саморобне рішення на Node.js, але вимагає уважного налаштування ланцюжка. Альтернатива — використовувати готові бібліотеки: passbook для Node, passkit-generator для TypeScript, wallet-php для PHP. Ми рекомендуємо passkit-generator — він автоматично формує manifest і підтримує всі типи пасів.
iOS: додавання паса в додатку
import PassKit func addLoyaltyCard(passData: Data) { guard let pass = try? PKPass(data: passData) else { showError("Не вдалося прочитати пас") return } let passLibrary = PKPassLibrary() if passLibrary.containsPass(pass) { // Картка вже додана — запропонувати оновлення passLibrary.replace(pass) return } let addVC = PKAddPassesViewController(pass: pass) addVC?.delegate = self present(addVC!, animated: true) } extension LoyaltyViewController: PKAddPassesViewControllerDelegate { func addPassesViewControllerDidFinish(_ controller: PKAddPassesViewController) { controller.dismiss(animated: true) checkPassStatus() } } PKPassLibrary().containsPass(_:) перевіряє за зв'язкою passTypeIdentifier + serialNumber. Якщо пас вже є — PKAddPassesViewController покаже діалог «Оновити», а не «Додати».
Як налаштувати серверні оновлення?
Apple Wallet підтримує серверні оновлення через Web Service URL. У pass.json додаєте:
"webServiceURL": "https://api.yourcompany.com/wallet", "authenticationToken": "vxwxd7J8AlNNFPS8k0a0FfUFtq0ewzFdc" Wallet регулярно опитуватиме GET /v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}, отримуватиме список оновлених serialNumber і завантажуватиме нові версії паса. Якщо пас не оновлюється, перевірте ланцюжок сертифікатів і URL — у 50% випадків проблема в невірному authenticationToken. Налаштування push-оновлень підвищує залученість клієнтів на 40%.
Типові помилки при налаштуванні push-оновлень
- Невірний authenticationToken: токен має бути згенерований випадковим рядком і співпадати на сервері та в пасі.
- Відсутність підтримки TLS 1.2: Apple Wallet вимагає HTTPS з сучасним шифруванням.
- Неправильний URL: webServiceURL має закінчуватися без слеша і бути доступним з інтернету.
Що входить в інтеграцію під ключ
- Формування та підпис .pkpass на вашому сервері
- Реалізація iOS-контролера для додавання паса
- Налаштування push-повідомлень для оновлень балансу
- Документація по API та супровід
- Тестування на пристроях з різними версіями iOS
Чому обирають нас
Ми займаємося мобільною розробкою понад 5 років. За цей час реалізовано 30+ проєктів з інтеграцією Apple Wallet та Google Pay. Наші інженери атестовані Apple і знають всі тонкощі PassKit. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проєкт. Сертифікати та багаторічний досвід гарантують надійність рішення. Замовте інтеграцію та скоротите час виходу програми лояльності на ринок.
Терміни та вартість
2–3 дні на серверну генерацію та підписання пасів, реалізацію PKAddPassesViewController та налаштування push-оновлень. Вартість інтеграції від $300, що окупається в середньому за 3 місяці завдяки зростанню лояльності на 25%. Отримайте безкоштовну консультацію для розрахунку точної вартості вашого проєкту.