Apple wallet developer guide

Apple wallet developer guide

Wallet helps people view and manage passes, which are digital representations of information that is otherwise printed on small pieces of paper or plastic and kept in a physical wallet. People use passes for common activities, such as boarding a plane, attending a concert, or receiving a discount. Wallet also stores credit, debit, and other cards that work with Apple Pay. For developer guidance, see PassKit and Wallet Passes.

People typically add passes to Wallet for convenience, but passes outside of Wallet remain readily available. When you tag a pass with descriptive information, the system can offer it to people when it’s relevant, regardless of where it exists.

Adding and Removing Passes

Offer to add new passes to Wallet. When people do something that results in a new pass — like checking into a flight, purchasing an event ticket, or registering for a store reward program — you can present system-provided UI that helps them add the pass to Wallet with one tap (for developer guidance, see addPasses(_:withCompletionHandler:)). If people want to review a pass before adding it, you can display a custom view that displays the pass and provides an Add to Apple Wallet button; for developer guidance, see PKAddPassesViewController.

Help people add a pass that they created outside of your app. If people create a pass using your website or another device, suggest adding it to Wallet the next time they open your app. If people decline your suggestion, don’t ask them again.

Add related passes as a group. If your app generates multiple passes, like boarding passes for a multi-connection flight, add all passes at the same time so people don’t have to add each one individually. If people can receive a group of passes from your website — such as a set of tickets for an event — bundle them together so that people can download all of them at one time. For developer guidance, see Distributing and Updating a Pass.

Display an Add to Apple Wallet button to let people add an existing pass that isn’t already in Wallet. If people previously declined your suggestion to add a pass to Wallet — or if they removed it — a button makes it easy to add it if they change their minds. You can display an Add to Apple Wallet button wherever the corresponding pass information appears in your app. For developer guidance, see PKAddPassButton. You can also display an Add to Apple Wallet badge in an email or on a webpage; for guidance, see Add to Apple Wallet Guidelines.

Let people jump from your app to their pass in Wallet. Wherever your app displays information about a pass that exists in Wallet, you can offer a link that opens it directly. Label the link something like “View in Wallet.”

Consider hiding expired passes. In iOS 15 and later, Wallet automatically hides expired passes to reduce crowding, while also providing a button that lets people revisit them. To ensure the system hides passes appropriately, set the expiration date, relevant date, and voided properties of each pass correctly; for developer guidance, see Pass.

Always get people’s permission before deleting a pass from Wallet. For example, you could include an in-app setting that lets people specify whether they want to delete passes manually or have them removed automatically. If necessary, you can display an alert before deleting a pass.

Making Relevant Passes Available

Help the system suggest a pass on the Lock Screen when it’s contextually relevant. Ideally, passes automatically appear when they’re needed so people don’t have to manually locate them. When you supply information about when and where your pass is relevant, the system can display a link to it on the lock screen when people are most likely to want it. For example, a gym membership card could appear on the lock screen as people enter the gym. For developer guidance, see Showing a Pass on the Lock Screen.

Updating Passes

Update passes as needed. Physical passes don’t typically change, but a digital pass should reflect updates to events. An airline boarding pass, for example, should automatically update to display flight delays and gate changes.

Use change messages only for updates to time-critical information. A change message interrupts the user’s current workflow, so it’s essential to send one only when you make an update that people must know about. For example, people need to know when there’s a gate change in a boarding pass, but they don’t need to know when a customer service phone number changes. Never use a change message for marketing or other noncritical communication. You enable change messages on a per-field basis; for developer guidance, see Adding a Web Service to Update Passes.

Источник

Apple wallet developer guide

Developer

Wallet Developer Guide

Pass Design and Creation

The files that make up a pass are arranged in a package (also referred to as a bundle ) called the pass package. At the center of the pass is a JSON file named pass.json , which defines the pass. The JSON file contains information that identifies the pass, text that appears on the pass, and other information about the pass. Additionally, the package contains images and localization data. Figure 4-1 shows the directory structure for a sample pass that provides an icon, a logo, and a thumbnail. The pass is localized in English and Chinese, it has both at Retina and non-Retina sizes of the image assets, and the logo is localized.

Figure 4-1Directory structure of a sample pass

Pass creation consists mostly of writing the pass.json file and designing the required images. As a developer, you will spend most of your time editing the pass.json file. For more information, see PassKit Package Format Reference.

Passes Are Identified by Pass Type Identifier and Serial Number

The pass type identifier is conceptually similar to a bundle identifier or a class name. The value for the passTypeIdentifier key specifies the pass type identifier. It is a string you choose to define a class or category of passes. It always begins with pass. and uses reverse DNS style—for example, pass.com.example.membership-card . Use the Certificates, Identifiers & Profiles area of Member Center to register a pass type identifier. The pass type identifier must match the certificate used to sign the pass.

You determine the exact meaning of each pass type identifier. And because each app’s entitlements specify the pass types that the app can interact with, you can control which of your apps interact with which of your passes. You also use a different certificate for signing passes with different pass type identifiers. This means that different groups inside your company can work on their own passes without having to share infrastructure, certificates, or private keys.

The serial number is a string that uniquely identifies the pass within the scope of its pass type. The value for the serialNumber key in the pass specifies the serial number. The serial number is opaque to PassKit—you are free to assign it in whatever way makes sense. A monotonically increasing integer or a UUID are convenient ways to assign the serial number.

The combination of pass type identifier and serial number is used throughout PassKit to uniquely identify a pass. Two passes of the same type with the same serial number are understood to be the same pass, even if other information on them differs. For example, when a pass is updated, the new version has the same pass type identifier and serial number as the old version, so the new version replaces the old version.

The difference between pass type identifiers and serial numbers is similar to the difference between classes and instances of a class. Pass type identifiers designate an abstract kind of thing, and serial numbers identify a specific concrete thing. For example, suppose an airline is creating passes for boarding passes and for its loyalty card program. All of the boarding passes you create have the same pass type identifier because they’re all the same type of pass, but each one has its own serial number. Loyalty cards have a different pass type identifier than boarding passes, because they’re a different type of pass.

Required Information Is Provided by Top-Level Keys

In addition to the pass type identifier and serial number, there are several other keys that every pass contains.

The version of the file format is specified by the formatVersion key; its value is the number 1.

The team identifier is a series of letters and numbers issued to you by Apple. The value for the teamIdentifier key in the pass specifies the team identifier. It must match the Team ID of the certificate used to sign the pass. You can find your Team ID in Member Center, or you can find it in Keychain Access by looking at the Organizational Unit field of your certificate.

The organization name is displayed on the lock screen when your pass is relevant and by apps such as Mail which act as a conduit for passes. The value for the organizationName key in the pass specifies the organization name. Choose a name that users recognize and associate with your organization or company.

The description lets VoiceOver make your pass accessible to blind and low-vision users. The value for the description key in the pass specifies the description. The description should start with a high-level term such as “Membership card,” “Weekly coupon,” or “Bus ticket” followed by one or two small pieces of information, such as the coupon’s offer and the store where it’s valid. Don’t try to summarize the entire contents of the pass, but include enough detail to let users distinguish between passes of the same type.

Pass Style Sets the Overall Visual Appearance

The pass’s style determines the overall visual appearance of the pass and the template for placement of information on the pass. The most distinctive visual indication of the style is at the top edge of the pass. Event tickets have a small cutout, coupons have a perforated edge, and so on.

Unlike pass type identifiers, which you define, pass styles are part of the API, and so is their meaning. You can’t change them or add new ones. Pass type identifiers categorize passes in a very specific way; pass styles categorize passes in a much more general, high-level way.

You specify the pass style by providing the corresponding key at the top level of the pass.json file:

Boarding passes use the key boardingPass . This pass style is appropriate for passes used with transit systems such as train tickets, airline boarding passes, and other types of transit. Typically, each pass corresponds to a single trip with a specific starting and ending point.

Coupons use the key coupon . This pass style is appropriate for coupons, special offers, and other discounts.

Event tickets use the key eventTicket . This pass style is appropriate for passes used to gain entry to an event like a concert, a movie, a play, or a sporting event. Typically, each pass corresponds to a specific event, but you can also use a single pass for several events as in a season ticket.

Store cards use the key storeCard . This pass style is appropriate for store loyalty cards, discount cards, points cards, and gift cards. Typically, a store identifies an account the user has with your company that can be used to make payments or receive discounts. When the account carries a balance, show the current balance on the pass.

Generic passes use the key generic . This pass style is appropriate for any pass that doesn’t fit into one of the other more specific styles—for example, gym membership cards, coat-check claim tickets, and metro passes that carry a balance.

The value of the pass style key is a dictionary containing the fields that hold the pass content. Listing 4-1 shows a pass that uses the boarding pass style, with a placeholder for the field dictionaries.

Listing 4-1Partial pass showing top-level keys

1. <
2. «description» : «Boarding pass for October 4, San Francisco to London»,
3. «formatVersion» : 1,
4. «passTypeIdentifier» : «pass.com.example.boarding-pass»,
5. «serialNumber» : «123456»,
6. «boardingPass» : <
7. >
8. >
9. >

The pass style controls how fields are laid out and which images can be used. Table 4-1 shows the images supported by each pass style and the number and placement of fields for each pass style. Pass style also affects relevance information—for details, see Relevance Information Displays Passes on the Lock Screen .

Источник

Apple wallet developer guide

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.

Источник