Интеграция Apple Wallet для пропусков и бейджей в мобильном приложении
Пропуск сотрудника или участника конференции — это generic-тип .pkpass. Generic — самый гибкий тип: нет строгих ограничений на семантику полей, структура определяется задачей. Для корпоративных пропусков часто добавляют фото сотрудника через thumbnail.png (90×90 @1x, 180×180 @2x) — оно отображается в правом углу карточки.
pass.json для пропуска
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.yourcompany.badge",
"serialNumber": "BADGE-EMP-1042",
"teamIdentifier": "ABCDE12345",
"organizationName": "YourCompany",
"description": "Пропуск сотрудника",
"foregroundColor": "rgb(255,255,255)",
"backgroundColor": "rgb(0,80,160)",
"generic": {
"primaryFields": [
{ "key": "name", "value": "Иван Петров", "label": "Сотрудник" }
],
"secondaryFields": [
{ "key": "department", "value": "Разработка", "label": "Отдел" },
{ "key": "access", "value": "A, B, C", "label": "Зоны доступа" }
],
"auxiliaryFields": [
{ "key": "role", "value": "Senior Developer", "label": "Должность" }
],
"backFields": [
{ "key": "emergency", "label": "Экстренная связь", "value": "+7 (495) 123-45-67" },
{ "key": "valid", "label": "Действителен до", "value": "31.12.2024" }
],
"barcode": {
"message": "BADGE-EMP-1042",
"format": "PKBarcodeFormatQR",
"messageEncoding": "iso-8859-1"
}
}
}
thumbnail.png добавляется просто как файл в архив — PassKit подхватывает его автоматически по имени.
NFC для контроля доступа
Generic-пасс поддерживает NFC через поле nfc в pass.json — только для устройств с iOS 13+:
"nfc": {
"message": "BADGE-EMP-1042-NFC-TOKEN",
"encryptionPublicKey": "base64-encoded-ec-public-key"
}
NFC-ридер на турникете считывает зашифрованное message. Но есть ограничение: NFC в Wallet для стороннего ридера работает только через Apple's Value Added Services Program — требует партнёрского соглашения с Apple. Без программы NFC-функция пасса не активируется.
Альтернатива без партнёрства — QR-сканер. Работает надёжно, требует лишь камеру на входе.
Управление жизненным циклом пропуска
Пропуск сотрудника имеет чёткий цикл: выдача → работа → отзыв (увольнение, смена должности). Отзыв реализуется двумя способами:
Через expirationDate — пасс автоматически становится недействительным. Подходит для временных пропусков (конференция, подрядчик).
Через voided: true с push-обновлением — для немедленного отзыва. Сервер получает событие (HR-система, увольнение) → отправляет APN push → устройство скачивает обновлённый пасс с voided: true → Wallet отображает пропуск как недействительный.
Сервер при скачивании обновлённого пасса должен вернуть HTTP 200 с новым .pkpass. Если вернуть HTTP 304 — устройство ничего не обновит.
Временные пропуска для мероприятий
Бейдж участника конференции — та же логика, но relevantDate выставляется на первый день мероприятия, expirationDate — на последний. Можно добавить расписание дня через backFields:
"backFields": [
{ "key": "schedule", "label": "Программа", "value": "09:00 Регистрация\n10:00 Keynote\n14:00 Воркшопы" }
]
Интеграция с HR-системой
Пропуск должен автоматически создаваться при найме и отзываться при увольнении. Webhook от HR-системы (1С, Bamboo HR, SAP) → сервер генерирует .pkpass и отправляет сотруднику email со ссылкой.
Для интеграции через email: ссылка вида https://api.yourcompany.com/badges/{token}.pkpass — iOS открывает через Safari и предлагает «Добавить в Wallet». MIME-тип ответа должен быть application/vnd.apple.pkpass.
При смене должности — не отзыв пасса, а его обновление: PATCH-запрос на web-сервис URL обновляет поля department и role. Wallet подтягивает изменения автоматически.
Сроки
1–3 дня: генерация пропусков с thumbnail, настройка пуш-обновлений при отзыве, опционально NFC через Value Added Services. Стоимость рассчитывается индивидуально.