Apple pass type id

Apple Wallet. Что это такое и как интегрировать в него свою карту

Руководитель отдела мобильной разработки

Принято считать, что Wallet — не самый популярный сервис в СНГ. Но уже во втором проекте подряд заказчик ставит задачу «Сделать интеграцию с Wallet». Поэтому я решил написать эту статью, чтобы рассказать о сервисе в целом и показать, как интегрировать в него свой продукт.

Что такое Wallet? Он позволяет держать в телефоне различного вида карты (билеты, скидочные карты и т.п.), облегчая жизнь пользователям продукта. Более того, есть возможность актуализировать информацию о карте посредством push-уведомлений, но это тема для отдельной статьи. Но если у вас есть карта/билет/абонемент, которые можно интегрировать в телефон, то для этого есть решение! Как это сделать — читайте ниже.

Как правило, за создание карты отвечает ваш сервер. Приложение получает карту в виде .pkpass файла и уже через приложение пользователь может добавить карту в Wallet.

Структура карты

Что же представляет собой карта с точки зрения разработчика? Карта — это архив с расширением .pkpass. Он содержит в себе все данные, необходиимые для отображения и работы карты. Содержимое архива — в таблице ниже.

Существуют следующие типы карт:

• Посадочный билет: на самолет или поезд. Обычно купон работает на одну поездку;
• Купон: для купонов и специальных предложений;
• Билет на событие: может работать как для одного события, так и для целого сезона;
• Скидочная карта: карты лояльности, скидочные или подарочные карты;
• Карта общего вида: если ничего из вышеперечисленного не подходит под ваш случай: например, карта для поездок на метро или пропуск в спортзал.

Рассмотрим схематично внешний вид разных карт. Картинки лучше называть так, как это указано в таблице выше.

Билет на событие

Обязательные поля. Содержат Pass Type ID, Team ID, название организации и т.п. Ключи для связанных приложений. Нужны для отображения приложений, которые нужно «ассоциировать» с картой.

Ключи «срока годности» карточки.

Ключи актуальности. Например, координаты местности, где карта может быть использована, или начало события, для которого она предназначена.

Ключ стиля. В начале статьи были перечислены 5 видов карт для Wallet. Каждому из них соответствует свой стиль. Такой ключ должен быть строго один.

Ключи визуального оформления карты. Помимо очевидного, содержат в себе информацию о штрихкоде, отображаемом на карте.

Ключи web-сервисов. Вы можете использовать web-сервисы для взаимодействия с картой, например, автоматически ее обновлять.

NFC-ключи. Содержат дополнительную информацию для Apple Pay транзакции.

Теперь обо всем подробнее.

Обязательные поля

Ключи для связанных приложений

Ключи стиля

JSON в данном случае имеет следующий вид:

Значение по ключу value может быть как числовым, так и строковым. Однако currencyCode вместе со строковым значением использовать не получится. Что касается auxiliaryFields и secondaryFields, их может быть несколько, и стоит следить за длиной строк, которые в них используются.

Ключи визуального оформления

Баркод

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

Локация

Эти ключи отвечают за локацию, в пределах которой карта может быть использована.

Оборотная сторона

На оборотной информационной части можно разместить дополнительную информацию: условия использования, политику автообновления, контактные данные и ссылку на приложение, к которому относится карта. На рисунке представлено соответствие полей в pass.json и внешнего вида обратной стороны карты. Если в value-поле есть ссылки, номера телефона и т.п., они подсветятся автоматически.

Создание карты. Часть 2

Итак, картинки готовы, pass.json сформирован, осталось собрать все это вместе. Для этого заполним manifest.json (см. таблицу 1), куда необходимо включить все картинки и pass.json. Получается примерно так:

С этого момента менять ничего не нужно, поскольку SHA будет некорректным, в случае изменений необходимо сгенерировать SHA заново.

Далее нужно создать Pass Type ID в кабинете разработчика и сделать для него сертификат. Процедура должна быть более-менее знакомая, если ранее вы создавали, например, Provisioning профили.

Далее заходим в ключницу (Keychain) и экспортируем оттуда Apple Worldwide Developer Relation Certificate (WWDR) как .pem.

Оттуда же экспортируем созданный Pass Type ID как .p12. На этом этапе ключница попросит вас ввести пароль для сертификата. При этом пароль вводить необязательно. Обратите внимание, что все дальнейшие действия надо производить в одной папке, где уже должны лежать manifest.json, pass.json и картинки.

Теперь необходимо сгенерировать подпись, которой будем подписывать архив. Для начала экспортируем Pass Type ID и ключ к нему как .pem.

Теперь мы готовы к генерации подписи. Сделаем это командой:

Итак, у нас все готово, осталось только собрать архив, делаем это командой:

Обращаю внимание, что тут должны быть перечислены все файлы, в которые вы хотите включить архив данных для карты(.pkpass). В итоге мы получим .pkpass файл, который можно открывать на компьютере. Мы увидим превью карты, внешний вид которой может отличаться от вида на телефоне. Все это можно сделать чуть проще. Apple предоставляет утилиту signpass (Apple Wallet sample meterials), которая берет на себя все подсчеты SHA (файл manifest.json можно не делать самостоятельно) и работу по созданию подписей. Чтобы ей воспользоваться, нужно собрать проект и поместить файл signpass в папку со всеми необходимыми ресурсами.

В целом структура должна выглядеть примерно так:

Далее выполняем команду:

Wallet — это название папки, в которой лежат все ресурсы. На выходе получаем файл wallet.pkpass. Его содержимое можно посмотреть, разархивировав wallet.pkpass.

Не исключено, что создание pkpass будет вынесено на бэкенд, в таком случае надо будет передать разработчикам WWDR, сертификат для Pass Type ID в виде .p12 и пароль от него.

Интеграция с приложением

Для того чтобы приложение имело возможность добавлять карты в Wallet, необходимо включить эту возможность в App ID и также включить эту возможность в Capabilities в проекте.

Это необходимо для полноценной корректной работы с Wallet. В противном случае не получится считывать карты с Wallet и, например, не будет возможности понять, добавлена наша карта или нет. Также важно отметить, что team id в pass.json должен совпадать c team id, либо придется добавлять их вручную в entitlements и это может исправить ситуацию, но это я не проверял.

Добавление карты

Добавлять карты очень просто:

Однако, опять же, чаще .pkpass файл надо будет скачивать с вашего сервера. Стоит отметить, что PassKit выдает довольно читаемые ошибки, поэтому можно легко понять, что именно было сделано не так.

Получение информации о добавленных картах

Чтобы получить информацию о картах, имеющихся в Wallet и относящихся к вашему приложению, необходимо обратиться к объекту PKPassLibrary.

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

Проверка на уникальность

Поскольку в вашем сервисе, как правило карта привязана к аккаунту, в приложении скорее всего придется как-то определять принадлежность карты к текущему пользователю. Предлагаю делать это через serialNumber. Например, задавать в качестве serialNumber id пользователя или номер карты.

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

Apple предоставляет примеры pkpass для разных типов, можно ориентироваться на них. Apple Wallet samples Чтобы увидеть то, как выглядит карта, можно, добавить pkpass в проект (см. «Добавление карты»). Процесс добавления/удаления уже рассмотрен выше, осталось только напомнить, что приложение не будет видеть уже добавленные карты, если карта для Wallet создавалась на одном аккаунте разработчика, а сама разработка велась с другого аккаунта (актуально для аутсорс-компаний). При этом добавлять карты можно без проблем. Проверить, корректно ли закодирована информация в штрихкоде, можно с помощью любого сканера QR-кодов. И точно необходимо проверить корректность работы с настоящим сканером.

Заключение

В статье был рассмотрен процесс создания и дизайна карты, а также процесс интеграции c приложением и проблем, которые могут возникнуть. Я намерено не касался вопросов интеграции с веб-сервисами и обновления карт, и надеюсь сделать это в следующей статье.

Источник

Apple pass type id

Developer

Wallet Developer Guide

Building Your First Pass

In this tutorial, you download and edit a sample pass, build it, and view it in the iOS Simulator app.

Case Study: A Very Simple Coupon

As a candy shop owner, you want to email your customers a coupon for a free lollipop. You trust most of your customers, and you’re running the promotion only until the giant bucket of lollipops runs out, so you won’t need to prevent customers from using their coupons more than once. You just want to create a pass with the same information that you would include on a printed coupon—a description of the offer and some information about your store.

In this tutorial, you set up your environment for pass development, sign one of the sample passes, and then make some minor changes to that pass.

Creating and Populating the Pass Package

Passes are created as a package (also referred to as a bundle ) containing a pass.json file that defines the pass, and image assets such as the logo and the icon.

To create the pass package for your pass, do the following:

Make a new directory in the Documents folder called Lollipop.pass . Using the .pass extension is a best practice, showing that the directory is a pass package.

Download this book’s companion file (from the developer downloads area), and locate the coupon in the Sample Passes directory.

Open the raw pass package, and copy the files it contains to your Lollipop.pass directory.

Setting the Pass Type Identifier and Team ID

Every pass has a pass type identifier associated with a developer account. Pass type identifiers are managed in Member Center by a team admin. To build this pass, request and configure a pass type identifier. (You can’t use the pass type identifier that is already in the pass because it isn’t associated with your developer account.)

To register a pass type identifier, do the following:

Under Identifiers, select Pass Type IDs.

Click the plus (+) button.

Enter the description and pass type identifier, and click Submit.

To find your Team ID, do the following:

Open Keychain Access, and select your certificate.

Select File > Get Info, and find the Organizational Unit section under Details. This is your Team ID.

The pass type identifier appears in the certificate under the User ID section.

You can also find your Team ID by looking at your organization profile in Member Center.

Edit the pass.json file, and change the pass type identifier to the identifier you just set up. Then change the Team ID to match the values you just found (see Listing 3-1 ).

Listing 3-1Setting the pass type ID and Team ID

1. <
2. .
3. «passTypeIdentifier» : «
4. your pass type identifier
5. «,
6. «teamIdentifier» : «
7. your Team ID
8. «,
9. .
10. >

Signing and Compressing the Pass

As part of building your production environment, you will need to set up a system for automatically signing and compressing passes as described in Passes Are Cryptographically Signed and Compressed . For this tutorial, a very simple tool for signing passes is included.

To download your pass signing certificate, do the following:

Under Identifiers, select Pass Type IDs.

Select the pass type identifier, then click Edit.

If there is a certificate listed under Production Certificates, click the Download button next to it.

If there are no certificates listed, click the Create Certificate button, then follow the instructions to create a pass signing certificate.

To get the signpass tool, do the following:

Download this book’s companion file (from the developer downloads area), and locate the signpass project.

Open the project in Xcode, and build it.

Right-click on the signpass executable (in the Products folder in Xcode) and select Show in Finder.

Move the signpass executable to the Documents folder.

To sign and compress the pass, use the signpass tool to sign the pass package. In Terminal, run the following commands:

/Documents

./signpass -p Lollipop.pass

These commands create a signed and compressed pass named Lollipop.pkpass in the Documents folder. If the signpass command fails, make sure you are using your correct pass type identifier and check that the pass.json file contains valid JSON.

Changing the Offer

The sample pass is already a coupon, but it doesn’t have the right details for a candy store. First, change the description and organization name. In the pass.json file, find the keys from Listing 3-2 and change their values as shown.

Listing 3-2Setting the description and organization name

1. <
2. .
3. «description» : «Coupon for a free lollipop at Example Candy Store»,
4. «logoText» : «Example Candy Store»,
5. .
6. >

Next, the pass needs to describe the actual offer. This description requires three levels of keys, as shown in Listing 3-3 . At the top level, find the coupon key, which indicates that this pass is a coupon. Its value is a dictionary that describes the coupon. At the second level, find the primaryFields key, which shows text on the front of the pass for the offer. Its value is a dictionary that describes the contents of the field. At the third level, the key is a string that uniquely identifies the field within the pass, and the value and label contain text that appears on the pass. Change their values as shown in Listing 3-3 .

Listing 3-3Describing the offer

1. <
2. .
3. «description» : «Coupon for a free lollipop at Example Candy Store»,
4. «logoText» : «Example Candy Store»,
5. «coupon» : <
6. «primaryFields» : [
7. <
8. «key»: «offer»,
9. «value»: «Free lollipop»
10. «label»: «On July 29»
11. >
12. ]
13. >,
14. .
15. >

At the second level of the pass, find the auxiliaryFields and backFields keys. Delete these keys and their values.

Viewing the Pass

The simplest way to see what a pass looks like during development is in the iOS Simulator app. To view the pass, launch Simulator and drag the Lollipop.pkpass file into the Simulator window. It displays the pass and offers to add it to Wallet, as shown in Figure 3-1 .

Figure 3-1Viewing the finished pass

When you’re testing in the iOS Simulator app, errors are logged to the system log, which you can view with the Console app. If the pass isn’t displayed or if the system fails to add the pass to Wallet, check the log for a description of what went wrong.

Источник