Інтеграція Apple Wallet для карток лояльності в мобільних додатках
PassKit — це фреймворк, який управляє файлами .pkpass на пристрої. Карта лояльності в Apple Wallet — це підписаний JSON-архів з зображеннями, метаданими та опціональними NFC-даними. Основною точкою входу в коді є PKAddPassesViewController. Без правильно сформованого та підписаного архіву користувачі отримають помилку "Invalid Pass" при спробі додати карту.
Структура .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.
Підпис на сервері
Потрібні три сутності з Apple Developer Portal:
-
Pass Type ID сертифікат — видається для конкретного
passTypeIdentifier - WWDR Intermediate Certificate — завантажується окремо з веб-сайту Apple
- Приватний ключ сертифіката
Підпис генерується через OpenSSL:
openssl smime -binary -sign \
-signer pass_certificate.pem \
-inkey pass_key.pem \
-certfile wwdr.pem \
-in manifest.json \
-out signature \
-outform DER -nodetach
Готові бібліотеки доступні: passbook для Node.js, passkit-generator для TypeScript, wallet-php для PHP.
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 покаже діалог "Оновити" замість "Додати".
Оновлення даних карти (push-сповіщення)
Apple Wallet підтримує оновлення на сервері через Web Service URL. Додайте це до pass.json:
"webServiceURL": "https://api.yourcompany.com/wallet",
"authenticationToken": "vxwxd7J8AlNNFPS8k0a0FfUFtq0ewzFdc"
Wallet буде періодично запитувати GET /v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}, отримувати список оновлених значень serialNumber та завантажувати нові версії паса.
Тривалість
2–3 дні на серверну генерацію та підпис пасів, реалізацію PKAddPassesViewController та налаштування push-оновлень. Вартість розраховується індивідуально.