Apple wallet is the new name for Apple Passbook in iOS 9.0. Wallet is the digital representation of wallet. It can hold all user’s tickets, boarding pass, coupons and event tickets at one place. Based on relevance by location, date and beacons, pass appears on lock screen. Thus helps the users to conveniently use passbook.

This  article explains

  • Structure of passbook.
  • How to design passbook based on usage?
  • How to sign, compress and distribute passbook?

Apple express Wallet as “Everything in your pocket”. This description stands true as you can hold passes from local coffee shops coupons to airlines ticket. All your passes are placed in Wallet application.

Get started:

Based on usage, passes can be of different type: PKPassTypeBarcode, PKPassTypePayment and PKPassTypeAny. Based on design, passes are of different type: Boarding pass, Store card pass, Event tickets pass, Coupon pass and Generic pass.

pass.png

What makes pass a pass is pass.json. Pass(.pkpass) file is a zipped package which contains pass.json, manifest.json, signature and other asset files needed by pass.

Pass can be localised using .lproj files. They are designed in a way to adjust all devices, iCloud and smart watch. Yes you heard it right, same pkpass file is used to view pass in smart watch. But few fields are removed in smart watch. So we have to be careful in placing our important information in right place.

Structure of passbook:

Download sample passbook from here.

pkpass file is the bundle package of pass. It contains pass.json, image assets, manifest, signature and files required for localisation. pass.json is the file which makes pass a pass.

Screen Shot 2015-12-16 at 5.15.20 PM

Pass type identifier is similar to bundle identifier. It is used to define category of pass. A single app can have multiple pass type identifier based on their needs. Pass type identifier and serial number uniquely identifies the pass. If two pass have same pass type identifier and serial number, they are identified to be same pass. Team identifier identifies the issuer of the pass. You can identify your team identifier from member center. Member center -> your account displays your team id. This is your team identifier.

team_identifer.png

FormatVersion is the version of the file format. Description is the brief description about the pass. Giving good description helps voiceover users to identify the pass. OrganizationName is the organization name. This appears in the lock screen when pass is shown in lock screen based on relevance.

{
 "formatVersion" : 1,
 "passTypeIdentifier" : "pass.XXXXXXX",
 "serialNumber" : "gT6zrHkaW",
 "teamIdentifier" : "XXXXXXXXXX",
 "organizationName" : "ITechRoof",
 "description" : "Sample pass",
 "boardingPass" : {
    <<field dictionaries>>
 }
}

These are essential information for the pass. Based on design of the pass, we can use boardingPass/coupon/eventTicket/storeCard/generic. Different pass have different dictionary parameters. For demo purpose, we are using boardingPass in this article. Different pass have different layout. To learn more about layout of different pass, refer this link.
struture.png You can change the foreground color and background color of front page of pass. In boarding pass, transitType field tells about medium of transportation namely: PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric and PKTransitTypeTrain. Header fields are used to display organization name and gate number in case of boarding pass.

Primary fields displays more important information. Generally primary fields are used to specify  arrival & departure location.
"primaryFields" : [
  {
   "key" : "depart",
   "label" : "Gangotri Circle",
   "value" : "BTM"
  },
  {
   "key" : "arrive",
   "label" : "Embassy Golf Links",
   "value" : "EGL"
  }
 ]
Secondary & Auxiliary fields displays less important informations like passenger name, date, time of boarding.
 "secondaryFields" : [
  {
   "key" : "passenger",
   "label" : "PASSENGER",
   "value" : "Kiruthika"
   }
 ],
 "auxiliaryFields" : [
  {
   "label" : "TIME",
   "key" : "boardingTime",
   "value" : "2:25 PM",
   "changeMessage" : "Boarding time changed to %@."
  }
]
Front page of the pass is not scrollable. So display only vital information to avoid congestion. Back page of the pass is scrollable. You can use to display all your other information. Smart watch don’t display your  back page.
"backFields" : [
  {
   "key" : "terms",
   "label" : "TERMS",
   "value" : "Your long info"
  }
 ]

Barcode are used to verify the pass. In smart watch, barcode is rotated 90 degree horizontally. Barcode can be used in following format: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec and PKBarcodeFormatCode128.

"barcode" : {
  "message" : "Hello World",
  "format" : "PKBarcodeFormatQR",
  "messageEncoding" : "iso-8859-1"
 }

RelevantDate and locations are used for relevance of the pass. When user reaches particular locations or time, pass is shown on the lock screen for easier access.

WebServiceURL and AuthenticationToken are used for updating the pass from web end. We will be dealing with this in the later article.

To know more about dictionary keys, refer here.

Sign, compress and distribute passbook:

First thing first. Create pass type ID in your developer portal. This is your pass type identifier. Download your pass certificate to your local keychain.

Screen Shot 2015-11-18 at 2.34.57 PM

Export this certificate as certificate.p12 in your directory where pass.json is placed. Don’t give any password while exporting.

Screen Shot 2015-12-17 at 1.44.31 PM.png

Export WWDR certificate to the same folder as WWDR.pem.

Screen Shot 2015-12-17 at 1.43.24 PM.png

To cryptographically sign your pass, you need openssl in your system. Download openssl from here if you dont have it on your system.

Now generate manifest.json by placing key as path to the file and value as sha value of the file. To get sha of each file, use below command

 openssl sha file.ext
 openssl sha pass.json

Dont change anything on that file after generating sha. If you change anything, sha will be changed. So you have to generate it again.

Lets export the pass certificate as passcertificate.pem and passkey.pem.

openssl pkcs12 -in certificate.p12 -clcerts -nokeys -out passcertificate.pem -passin pass:
openssl pkcs12 -in certificates.p12 -nocerts -out passkey.pem -passin pass: -passout pass:12345

Now we are ready to generate the signature. Use the following command to generate signature.

openssl smime -binary -sign -certfile WWDR.pem -signer passcertificate.pem -inkey passkey.pem -in manifest.json -out signature -outform DER -passin pass:12345

Last and final step is to compress the pass. Use following command to compress the pass:

zip -r boardingPass.pkpass manifest.json pass.json signature logo.png logo@2x.png icon.png icon@2x.png

.pkpass file will be generated in your folder. Double click on the file to view the pass. Pass viewer works from OSX 10.8.2. Email as attachment and view it in mail app or safari if you are not able to preview through pass viewer.

Now what are you waiting for?  Start exploring different type of passbook. If you find this article useful, share it with your friends. Happy coding 🙂

Advertisements