Table of Contents

Что такое PassKit API?

Рамки Apple PassKit - это полный набор инструментов и услуг, которые позволяют разработчикам iOS создавать, распространять и управлять цифровыми пропусками для Apple Wallet. Пасс может быть посадочным талоном, билетом на мероприятие, картой лояльности, подарочной картой, купоном или любым другим типом учетных данных, которые извлекают выгоду из безопасного хранения на устройстве пользователя. API PassKit обрабатывает все, от генерации пропусков и подписи до обновлений в режиме реального времени с помощью push-уведомлений. Для авиакомпаний, платформ для билетов и организаторов мероприятий API PassKit стал фактическим стандартом для устранения бумажных документов и обеспечения без трения мобильного опыта.

Каждый пропуск упакован в файл — подписанный ZIP-архив, содержащий данные JSON, изображения и строки локализации. Когда пользователь открывает этот файл (через ссылку, электронную почту или загрузку в приложении), iOS проверяет подпись и представляет пропуск в Кошельке. С этого момента пропуск живет на устройстве, может обновляться по воздуху и работает даже в автономном режиме для критической информации, такой как штрих-коды или QR-коды.

Как работает PassKit API

Pass File Структура файла

Файл является стандартным ZIP-архивом, который должен содержать по меньшей мере манифест, (список всех файлов с их хэшами SHA-1) и файл подписи (. Файл определяет весь контент прохода: поля заголовка, первичные поля, вторичные поля, вспомогательные поля, штрих-коды и тип транзита для посадочных талонов. Изображения (логотип, значок, фон, полоса и т.д.) размещаются в подкаталогах для каждого разрешения дисплея (например, для 1x, для 2x, для 3x).

Подписание и распределение

Apple требует, чтобы все пропуска были криптографически подписаны с использованием сертификата, выданного разработчиком (полученного через Портал разработчика Apple). Подпись проверяет подлинность и целостность пропуска. После подписания пропуск может быть размещен на сервере и распределен по URL-адресу, который запускает установку кошелька. Альтернативно, пропуски могут быть отправлены в виде вложений электронной почты, встроенных в QR-коды или выталкиваемые непосредственно из вашего приложения с использованием [[FLT: 9]] или современного [[FLT: 10]].

Обновления в реальном времени с помощью Push

Одной из самых мощных функций PassKit является возможность обновления пропусков после выдачи. При обновлении шлюзов или билета сервер может отправить на устройство пользователя тихое push-уведомление. Затем устройство извлекает новый файл из зарегистрированного URL-адреса веб-сервиса. Пропуск в кошельке легко заменяется, и пользователь сразу видит обновленную информацию. Для посадочных талонов это означает, что изменения шлюза, переназначение сидений или задержки отражаются автоматически, не требуя от пользователя повторно открывать приложение.

Поток push-обновлений требует веб-сервиса, который соответствует спецификации Apple: служба должна выставлять конечные точки для получения последнего пропуска, серийных номеров и регистрации удаленного устройства. Обычно это реализуется на вашем бэкэнде с использованием Node.js, PHP, Python или любого стека, который может обрабатывать HTTP-запросы.

Ключевые преимущества для управления посадочным талоном и билетами

Удобство пользователя и снижение трения

Хранение посадочного талона или билета в Apple Wallet устраняет необходимость перебора бумажной версии или сохранения стороннего приложения открытым. Пропуски доступны с экрана блокировки (через геозону, уведомление на основе времени или ручной кран) и могут быть быстро отсканированы на воротах, турникетах или точках входа. Для авиакомпаний это ускоряет посадку. Для мест проведения мероприятий это уменьшает линии в окнах вызова.

Надежные, всегда доступные данные

После загрузки пропуска изображение штрих-кода и ключевая информация хранятся локально. Даже если устройство теряет сотовую связь, пропуск остается сканируемым. Это имеет решающее значение в аэропортах, стадионах и транзитных узлах, где покрытие сети может быть нечетким. Пропуск также появляется на экране блокировки, когда приближается соответствующая дата / время, благодаря интеллекту Apple.

Динамические обновления без действий пользователя

При push-уведомлениях на основе обновлений любое изменение содержания пропуска может быть отражено сразу. Для задержки рейса в обновлениях пропуска указывается предполагаемое время вылета; для фестиваля на билете появляется смена сцены. Пользователям не нужно ничего обновлять или загружать вручную. Это уменьшает запросы поддержки и улучшает общий опыт.

Усиление безопасности и борьба с мошенничеством

Пропуски Apple Wallet подписаны сертификатом разработчика, поэтому можно обнаружить подделку. Кроме того, пропуски могут включать в себя уникальный серийный номер, который можно проверить на серверной стороне. Для высокоценных событий вы можете объединить PassKit с проверками на стороне сервера — например, отмену пропуска удаленно, если он возвращается, а затем нажатие обновленной версии с «отсутствующим» статусом. Штрих-коды также могут периодически регенерироваться, чтобы предотвратить повторное использование скриншотов, хотя это чаще встречается с динамическими системами штрих-кода.

Пройти Создание и дизайн

Определение полей Pass

Содержимое пропуска разбивается на логические группы: поля заголовка (например, «Boarding Pass»), первичные поля (например, «Gate A12»), вторичные поля (например, «Seat 23A»), вспомогательные поля (например, «Frequent Flyer Number») и задние поля (например, «Frequent Flyer Number») и дополнительные атрибуты (например, стиль даты, стиль номера или стиль валюты. Для посадочных талонов вы также устанавливаете на PKTransitTypeAir, PKTransitTypeTrain и т. Д., Что влияет на визуальную компоновку и вид билета на экран блокировки.

Штрих-коды и QR-коды

Каждый пропуск должен включать по крайней мере один объект штрих-кода. Вы можете использовать , , или (последние два являются общими для посадки авиакомпании. (последние два являются общими для посадки авиакомпании). Значение штрих-кода — обычно номер билета или код подтверждения — закодировано в изображение во время генерации пропуска. Для повышения безопасности вы можете создать одноразовый штрих-код на сервере и включить его в пропуск, а затем нажать обновление, чтобы аннулировать старый после сканирования. Однако большинство авиакомпаний и платформ событий используют статический идентификатор пассажира в сочетании с проверкой на стороне сервера.

Визуальный дизайн руководящие принципы

Apple предоставляет сильные рекомендации по дизайну, чтобы убедиться, что пропуски выглядят согласованно на разных устройствах. Логотип должен быть простым и центрированным, фон должен дополнять штрих-код, а полосовые изображения (необязательно) могут добавить фирменный вкус. Вам нужно предоставлять изображения с несколькими разрешениями (1x, 2x, 3x) для всех плотностей экрана. С ростом больших iPhone макет пропуска адаптируется автоматически, но необходимо тщательное тестирование на разных размерах экрана.

Для практического примера правильно структурированного пропуска JSON см. официальную документацию Apple Создание пропуска .

Локализация

Пропуски могут быть локализованы путем включения подкаталогов, специфичных для языка (например, , )) в пакет . может ссылаться на эти локализованные строки для полевых этикеток и значений. Это особенно важно для международных авиакомпаний и организаторов глобальных мероприятий, которые хотят представить информацию о билетах на предпочтительном языке пользователя.

Распределение пропусков пользователям

Прямое добавление in-App

Если ваше приложение является основной точкой касания, вы можете программно добавить пропуск в кошелек, используя (iOS 6+) или более современную (iOS 12+). Файл пропуска должен сначала быть загружен с вашего сервера (как NSData) и затем представлен пользователю. Стандартный поток: пользователь покупает билет или регистрируется, ваше приложение извлекает подписанный и показывает кнопку «Добавить в кошелек». Нажатие на него открывает кошелек с предварительным просмотром, и пользователь подтверждает.

Электронная почта и веб-распространение

Для пользователей, у которых не установлено приложение (или которые предпочитают не использовать его для управления пропусками), можно отправить ссылку на файл или разместить прямую ссылку для загрузки на веб-сайте. Когда пользователь нажимает ссылку на устройстве iOS, Safari автоматически открывает кошелек и предлагает добавить пропуск. Вы также можете использовать Universal Links для улучшения опыта. Этот метод широко используется авиакомпаниями, которые отправляют пропускные ссылки в письмах с подтверждением бронирования.

QR-код или сканирование штрих-кода

Другой распространенный шаблон - вставить URL-адрес, указывающий на файл в QR-код. При сканировании с приложением Camera, iOS отображает баннер Wallet в верхней части экрана. Нажатие на него добавляет пропуск. Это идеально подходит для прогулок по билетам в кассах мероприятий или киосках самообслуживания в аэропортах. Для получения более подробной информации об этом подходе обратитесь к руководству Добавление пропуска в Wallet .

Обновление пропусков в реальном времени

Push-Based Update Architecture

Чтобы включить автоматические обновления, вы должны внедрить простой веб-сервис, который может вызывать Apple Wallet. Сервис должен отображать три конечных точки:

  1. Получить последнюю версию пропуска (называется Wallet, когда он получает push-уведомление).
  2. Получите серийные номера для устройства (используются при первоначальной регистрации и для обнаружения изменений).
  3. Регистрация и нерегистрация (хранит токены устройств для push-уведомлений).

Когда пропуск нуждается в обновлении, ваш сервер отправляет push-уведомление (с использованием APN) на зарегистрированные устройства. Затем устройство запрашивает веб-службу для нового файла . Если версия пропуска изменилась, Кошелек загружает и заменяет старый пропуск бесшумно. Обновленный контент (например, новый шлюз, новое время отправления, статус пустоты) мгновенно виден пользователю.

Когда использовать обновления

К числу случаев общего использования относятся:

  • Изменения в воротах, задержки или отмены
  • Перепланировка мероприятия или изменения места проведения
  • Модернизация или понижение сидений
  • Проверка билета (например, сканирование при входе отмечает пропуск в том виде, в котором он используется)
  • Обновления безопасности (например, замена штрих-кода после попытки сканирования)

Обратите внимание, что каждый пропуск может быть обновлен только с использованием того же сертификата, который использовался для его первоначального подписания. Вы не можете изменить тип пропуска или идентификатор организации после выдачи.

Лучшие практики для реализации

Безопасность и доверие

  • Держите свой сертификат подписи и закрытый ключ в безопасной серверной среде, а не в коде на стороне клиента.
  • Проверяйте все входящие запросы на регистрацию push, чтобы предотвратить впрыск токена.
  • Используйте HTTPS для всех взаимодействий между вашим сервером и кошельком Apple.
  • Рассмотрите возможность использования одноразовых штрих-кодов или краткосрочных идентификаторов для событий с высокой степенью безопасности.
  • Ограничение скорости реализации на конечных точках вашего веб-сервиса.

Пользовательский опыт

  • Показать опцию «Добавить в кошелек» в наиболее подходящий момент — после подтверждения покупки, после регистрации или в начале дня мероприятия.
  • Используйте четкий, высококонтрастный стиль для штрих-кодов и убедитесь, что они соответствуют минимальным требованиям к размеру (не менее 2 дюймов в печатных эквивалентах).
  • Держите проход простым: избегайте загромождения ненужными полями. Вид экрана блокировки должен показывать три наиболее важных фрагмента информации.
  • Пропуск тестов на реальных устройствах с разными версиями iOS.Симулятор может отображать пропуска, но вы не можете тестировать push-обновления или фактическое сканирование там.

Интеграция с Backend

Ваша служба генерации пропусков должна быть идемпотентной и масштабируемой. Используйте базу данных для отображения серийного номера пропуска каждого пользователя на их событие или бронирование рейса. Храните токены устройства для push-обновлений. Многие команды используют библиотеки, такие как Swift-Protobuf или существующие помощники на стороне сервера (например, ]Passbook PHP библиотека ) для обработки генерации .pkpass. Независимо от языка, всегда проверяйте, что сгенерированный ZIP-файл при подписании правильно открывается на тестовом устройстве.

Тестирование и QA

Apple предоставляет инструмент тестирования Wallet Pass в Xcode, который может проверить структуру вашего . Используйте его перед распространением пропусков. Кроме того, проверьте полный жизненный цикл: добавьте пропуск → обновление через push → удалите пропуск. Тест с плохими сетевыми условиями для обеспечения работы автономного отображения штрих-кода. Имитация push-уведомлений с использованием инструментов APN для проверки правильного ответа конечных точек вашего веб-сервиса.

Примеры реального мира и примеры использования

Авиакомпании и аэропорты

Все крупные авиакомпании — Delta, United, Emirates и многие другие — используют PassKit для посадочных талонов. Пассажиры могут зарегистрироваться через приложение авиакомпании, добавить посадочный талон в кошелек и использовать его на протяжении всего путешествия. Изменения ворот и перераспределение мест выдвигаются автоматически. Некоторые авиакомпании даже используют пропуск для отображения доступа к лаунджу или приоритетного статуса посадки. Пассажирский талон также может использоваться для проверки мешков на сумках самообслуживания. Согласно отраслевым отчетам, авиакомпании, которые принимают пропуска кошелька, видят более низкий встречный трафик и более высокие показатели удовлетворенности клиентов.

Билеты на мероприятия

Ticketmaster, Live Nation и многие фестивальные приложения поддерживают пропуска Apple Wallet. Поклонники покупают билет, получают пропуск с вращающимся QR-кодом (для предотвращения мошенничества) и используют его для входа. Пасс также может включать дополнительные покупки, такие как парковка или VIP-обновления. Во время мероприятия организаторы могут продвигать обновления об изменениях расписания, картах мест или предупреждениях о погоде. Это снижает необходимость в бумажных вывесках и объявлениях на месте.

Общественный транспорт и парковка

Городские транзитные агентства (такие как MTA в Нью-Йорке или TfL в Лондоне) экспериментировали с PassKit для ежемесячных пропусков или одноместных билетов. Некоторые приложения для парковки используют кошельки в качестве цифровых разрешений на парковку, которые могут быть проверены правоохранительными органами. Транзитные пропуска пользуются той же возможностью толкания в реальном времени - например, если железнодорожная линия нарушена, пропуск может предложить альтернативные маршруты.

Ограничения и соображения

Хотя PassKit является мощным, у него есть ограничения, которые разработчики должны планировать для:

  • iOS только: Пропуски не могут быть добавлены к устройствам Android.Если ваша аудитория является кроссплатформенной, вы должны предложить альтернативу (например, PDF или мобильный билет на веб-сайте).
  • Никакого взаимодействия Bluetooth или NFC (по умолчанию): Пассы не поддерживают NFC, если вы не встраиваете сеанс NFC нативного приложения.
  • Задержка обновления push: Пока push-уведомления быстры, устройство должно быть онлайн, чтобы получить триггер. Если пользователь находится в автономном режиме во время обновления, пропуск будет оставаться несвоевременным, пока они не подключатся.
  • Память и хранение: Каждый пропуск невелик (обычно 30–80 КБ), но если вы выдаете миллионы пропусков, ваш push-сервис должен обрабатывать высокую параллель.
  • Сертификат продления: Срок действия сертификатов подписи истекает каждый год или два. Вы должны убедиться, что ваш сервер обновляет сертификат до истечения срока действия, иначе все пропуски, подписанные старым сертификатом, перестанут обновляться (они все равно будут работать, но новые толчки не сработают).

Заключение

API iOS PassKit обеспечивает надежный, безопасный и удобный для пользователя способ управления посадочными талонами и билетами в Apple Wallet. Используя создание пропусков, подписание, распространение и push-обновления в режиме реального времени, разработчики могут обеспечить бесперебойное путешествие или событие, которое информирует пользователей, не требуя постоянного участия в приложении. Внедрение PassKit требует тщательного внимания к рекомендациям Apple по дизайну и безопасности, а также надежной инфраструктуре на стороне сервера, но отдача в удовлетворенности клиентов и операционной эффективности значительна.

Для дальнейшего чтения обратитесь к документации Apple PassKit и PassKit Programming Guide. Эти ресурсы охватывают ключи JSON, спецификации изображения и протокол push-обновления в исчерпывающих деталях.