Интеграция Apple Wallet Pass для карт лояльности в приложении

Вы разработали карту лояльности, но пользователи жалуются — при попытке добавить её в Apple Wallet возникает ошибка «Недействительный пропуск». Чаще всего причина — неправильная структура .pkpass: не совпадает хэш в manifest.json или сертификат не привязан к passTypeIdentifier. Разберём, как избежать этих проблем и настроить интеграцию под ключ. Наш опыт — 5 лет работы с Apple Wallet и более 20 успешных проектов. В одном из недавних кейсов клиент экономил 2 часа на каждой сборке пасса после автоматизации подписи, а количество ошибок снизилось на 95%.

PassKit — фреймворк, который управляет .pkpass-файлами на устройстве. Карта лояльности в Apple Wallet — это подписанный JSON-архив с изображениями, метаданными и опциональными NFC-данными. Основная точка входа в коде — PKAddPassesViewController. Без правильно сформированного и подписанного архива пользователь получит ошибку «Недействительный пропуск» при попытке добавить карту.

Почему возникает ошибка «Недействительный пропуск»?

Самая распространённая причина — несоответствие хэшей в manifest.json. Apple Wallet сверяет SHA1 каждого файла с записью в манифесте. Если хотя бы один байт отличается — подпись считается недействительной. В 80% случаев проблема решается перегенерацией манифеста после каждого изменения pass.json. Другая частая ошибка — неправильная цепочка сертификатов: Pass Type ID должен быть подписан WWDR Intermediate, иначе подпись PKCS#7 не проходит валидацию.

Структура .pkpass и подпись

Архив содержит:

• pass.json — тип, цвета, поля карты
• icon.png, logo.png, strip.png — графические ресурсы (обязательны двойная плотность @2x)
• manifest.json — SHA1-хэши всех файлов
• signature — PKCS#7 подпись манифеста через Pass Type ID certificate

Самая частая ошибка при самостоятельной сборке — неправильный 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. В таблице ниже сравнение типов:

Как подписать Wallet Pass: пошаговая инструкция

1. Сгенерируйте Pass Type ID сертификат в Apple Developer Portal.
2. Загрузите WWDR Intermediate Certificate с сайта Apple.
3. Создайте приватный ключ и подпишите запрос сертификата.
4. Соберите .pkpass архив: pass.json, изображения, manifest.json.
5. Подпишите 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 в 2 раза быстрее самописного решения на 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.

Что входит в интеграцию под ключ

• Формирование и подпись .pkpass на вашем сервере
• Реализация iOS-контроллера для добавления карты
• Настройка push-уведомлений для обновлений баланса
• Документация по API и сопровождение
• Тестирование на устройствах с разными версиями iOS

Почему выбирают нас

Мы занимаемся мобильной разработкой более 5 лет. За это время реализовано 30+ проектов с интеграцией Apple Wallet и Google Pay. Наши инженеры аттестованы Apple и знают все тонкости PassKit. Получите консультацию — свяжитесь с нами, чтобы обсудить ваш проект. Закажите интеграцию и сократите время выхода карты лояльности на рынок.

Сроки и стоимость

2–3 дня на серверную генерацию и подписание пассов, реализацию PKAddPassesViewController и настройку push-обновлений. Стоимость рассчитывается индивидуально.