Designing and Creating Pass for Apple Wallet

What is Apple Wallet?

Wallet application on iPhone, iPod Touch and Apple Watch devices is an ecosystem where users can store cards, road and event tickets, and Pass types such as gift cards. Since the wallet can also be triggered by location and time, Passes can be brought at the time and location specified on the user’s screen, for example when the user enters the airport or a store. In addition, Passes can be updated with push notification, for example, we can inform the user when there is a change on the Pass, and the user can update the Pass information through this notification.

Pass Types and Appearances

Type of pass determines the pattern of the ticket’s general appearance and information placement. The most distinctive visual change for different Pass types is the top corner of the tickets. Event tickets have a small cutout at their top corner, while coupons have a perforated style.

Pass types are part of the API given to us. Therefore, we cannot change existing types or add new types.

Copyright ® by Apple

• Boarding tickets are identified by the boardingPass key. This Pass type is suitable for public transport systems such as plane, train, bus tickets. Typically, each pass corresponds to a single journey with a specific start and end point.
• Coupons are defined with the coupon key. This Pass type is eligible for coupons, special offers and other discounts.
• Event tickets are identified with the eventTicket key. This type of Pass is suitable for situations that require access to events such as concerts, movies, shows or sports events. Typically, each pass corresponds to a specific event, but can also be used as disposable entries for seasonal events.
• Store cards are identified by the storeCard key. This Pass type is suitable for store membership cards, discount cards, point cards or gift cards. Typically, it is used in situations such as paying with a card defined to the user by a store or gaining a discount. If the user’s account contains a balance, we can show the current balance on the Pass.
• Generic cards are identified with the generic key. This type of Pass is suitable for all cards that are not suitable for the available types, e.g. gym membership cards, cloakroom tickets, public transport cards with balance.

Design of Pass

Pass type key is a dictionary that contains the fields of the content of the ticket. As an example, the dictionary structure of a pass in transit ticket type, created with temporary data, is as follows:

In this way, it is stated how the areas to be included in the Pass will be positioned and which images will be used.

Table below shows the supported images in each Pass type and the number and placement of the fields that can be found in the Pass.

Figür 4.2 Boarding Pass — Figür 4.3 Coupon Pass — Figür 4.6 Store Cards (Copyright ® Apple)

Figür 4.4 Event Pass — Figür 4.5 Generic Pass (Copyright ® Apple)

Pass type determines the maximum area to be displayed on the front of the ticket:

• Generally, a Pass contains up to 3 header fields, a single primary field, up to 4 secondary fields, and up to 4 auxiliary fields.
• Boarding passes can contain up to 2 extra primary fields and up to 5 auxiliary fields.
• Coupon, store cards, and generic cards with square barcodes can contain up to 4 secondary and ancillary fields in total.

Number of fields shown on the pass depends on the length of the text in each field. If there is too much text, some fields may not be displayed.

Context of Pass

Fields with Text

Information shown on the pass is divided into fields. Each field is defined by a dictionary. This dictionary contains the value and label, a unique key, and optionally information on how to display these values.

Primary fields will be displayed directly on the Pass and contain the most important information. Secondary fields contain less priority information and auxiliary fields contain the least priority information. The header areas are the most prominent as it is the only area that can be seen when the passes are stacked, so the header area should be used sparingly.

A Pass with simple fields

Ordering between the field lists is not important, but the order of the fields within the list is. In other words, if we write the primary field before or after the secondary field while creating the file, it will not change the appearance of the Pass, but if we put the seat number field before or after the passenger name field, it will change the order of these two fields.

Format Supported Fields

There are three types of formats that can be applied to a field: alignment, date format, number format:

• To apply an alignment format to a field, the alignment key must be given a value.
• To use date format, the keys dateStyle and timeStyle must be given values.
• To use currency or other number format, the key currencyCode or numberStyle must be given a value.

You can review the Field Dictionary Keys page for the keys that can be used in the fields and the possible values ​​of these keys.

The Back Side of the Pass that Offers Extra Space for Long Texts

Area on the front of the pass is special, so the number of areas is limited, and their content should be kept as short as possible. On the back side of the pass, as many fields as needed can be added, and the content of these fields can be as long as necessary. If there is too much content to show, we can add this information to the back of the card and allow the user to view the information easily by swiping.

Back of the Pass offers an area to add extra content that too long to fit on the front and doesn’t need to appear on the front, such as terms and conditions, full location’s address, customer service number, or website address.

Just like primaryFields and auxiliaryFields, the backFields we add can be used like this:

Texts in the fields on the back side of the pass scans through data detectors for URL and phone numbers and are displayed as live addresses. Users can open addresses in Safari or search for phone numbers. Lines in this area also support line breaks (used with \n in JSON).

Barcodes

In the most common uses, barcodes contain a unique ID that is used to check information such as balance, coupon details or ticket validity.

To add a barcode to the pass, a high-level barcodes key must be created in JSON. This value is a string containing dictionary and defines the barcode to be displayed.

Each barcode dictionary specifies the format of the barcode, the message to be displayed and the encoding used by the message. Optional alternate text is also displayed near the barcode and contains information to be entered manually if the barcode cannot be read.

An example barcode definition for Pass:

PKBarcodeFormatPDF417 or PKBarcodeFormatAztec can be used for different barcode types.

Customized Pass Colors

By default, the Wallet app chooses the background and text color for Pass. To override this color selection and use our own colors, we need to specify a high-level RGB color on the JSON, for example rgb(0, 255, 0). We can change the three colors at will:

• Background color is the color used for the front and back of the Pass. If we have specified a background image, the defined color is ignored. The background color is defined by the backgroundColor key.
• Foreground color is used for the content of the fields on the front of the Pass and is defined by the foregroundColor key.
• Label color is used for the labels of the fields on the front of the Pass and is defined by the labelColor key.

Using Images with Pass

Pass layout allocates a certain area for the images to be used on the front. Images scale with the amount of aspect ratio to fill the space allotted to them. Images with aspect ratios different from the space allocated to them are cut after scaling. The areas reserved for images are as follows:

• Background image (background.png) is displayed on the entire front face, behind the content. The expected image is 180 x 220. The image is slightly cut off and blurred on all edges.
• Footer image (footer.png) is displayed near the barcode. The space allocated for this image is 286 x 15.
• Icon (icon.png) is shown when the Pass is displayed on the lock screen or in apps like Mail. The icon image must be 29 x 29 in size.
• Logo image (logo.png) is displayed in the upper left corner, next to the logo text. The space allocated for this image is 160 x 50; narrower is recommended in most cases.
• Strip image (strip.png) is displayed behind the primary fields. On iPhone 6 and iPhone 6 Plus (and higher) devices, the space allocated for this image is 375 x 98 for event tickets, 375 x 144 for gift cards and coupons, and 375 x 123 for other cases.
• Thumbnail image (thumbnail.png) is displayed next to the front face fields. The space allocated for this image is 90 x 90. The aspect ratio must be between 2:3 and 3:2, otherwise the image will be cut off.

Dimensions given above are absolute. On non-retina displays, each size corresponds to exactly 1 pixel. The original, @2x and @3x versions of the image must be included in the package to support displays with retina display.

Show Pass on Lock Screen with Relevance Information

By specifying where or when the pass is valid, users can easily access their tickets. To use this feature, we need to specify the validity conditions of the Pass, for example, the gym membership card is related to the gym to which it is valid, while the pass is related to the departure time of the plane.

To take advantage of the feature, a time and place must be specified in the Pass. Then, according to these settings, the Wallet application finds out whether the user is close to the specified point according to the type of Pass and determines that it should be displayed on the lock screen.

Relevance information is passive — It helps users find them when they need them by showing them on the lock screen based on their relevance. It does not send any notifications or alerts.

Top-level relevantDate key must be valued to specify the relevant date. Each Pass can contain a single relevance date. The value of this key is in the form of a W3C timestamp, either the full date plus hours and minutes, or the full date plus hours, minutes and seconds. For more details, see Time and Date Formats — W3C.

Top level locations key must be valued to indicate the relevant location. Each Pass can contain up to 10 location information. The value of this key is the dictionary array containing latitude, longitude, and optionally altitude details.

Pass Example with Relevant Location and Date Information

For Passes with relevant locations, an explanation should be provided stating why the Pass is related to the location it is located. This description can be a simple text like “You are close to the store”, or it may contain directions for the user to find the store. This description should not include the name of the organization or any guidelines, for example “You can redeem this coupon at XYZ store”.

Creation of Pass

Passes are created as packages. The pass.json file defines the Pass and the images to be used such as logos and icons.

To create a pass package:

• Create a folder named Event.pass on the desktop.
• Download the template files from the Apple Developer portal and locate the Sample Passes folder.
• Locate the folder of the Pass type you want to create and copy its contents into the Event.pass folder you created.

Determining Pass Type Identifier and Team ID

Each Pass has a Pass Type Identifier associated with an Apple Developer Account. This information is managed by the account manager within the Member Center. To build the pass, this identifier must be created.

To create a Pass Type Identifier:

• Visit the Certificates, Identifiers & Profiles — Identifiers page.
• Press Plus button and continue after selecting Pass Type IDs from the list.
• Fill the Description and Identifier areas (e.g.: EventPass — pass.com.example.event-pass) and create the identifier.

To find your Team ID:

• Visit the Member Center and open Membership section..
• Get the id on Team ID section.

Update the pass.json file with Team ID and Pass Type Identifier.

Signing and Compressing the Pass File

All Passes must be cryptographically signed and compressed as specified. For this step we need to use a simple tool offered by Apple.

To download your Pass Signing Certificate:

• Visit the Certificates, Identifiers & Profiles — Certificates page.
• Press Plus button and continue after selecting Pass Type ID Certificate from Services section.
• Name the certificate. (e.g.: EventPass)
• Select the Identifier you created in the previous step from the Pass Type ID list. (pass.com.example.event-pass if you followed the steps exactly) and continue.
• Upload your Certificate Signing Request file (click to learn how) and continue.
• Generate and download your certificate and open the downloaded certificate file to add it to Keychain Access.

To download the signpass tool offered by Apple:

• Download the template files from the Apple Developer portal and find the signpass project.
• Open the project in Xcode and build.
• Right-click the signpass executable (in the Products folder on Xcode) and navigate to the file location in the Finder.
• Move the signpass file to Desktop.

Use the signpass tool to sign and compress the Pass we created. Run the following commands on the terminal screen, in order:

cd Desktop

./signpass -p Event.pass

These command will create Event.pkpass that is signed and compressed to your Desktop. If the signpass command fails, make sure you are using the correct Pass Type Identifier and check if the pass.json file’s JSON syntax is valid.

Completed Pass: