apple-wallet-passes

Apple Wallet パス

このスキルでは、適切なパススタイルの選択から、デザインと開発、署名、配布、更新まで、Apple Wallet パスのライフサイクル全体をユーザーが進められるよう支援します。

使用するタイミング

次のようなシナリオで、このスキルを使用します。

• 新しい Wallet パス（搭乗券、クーポン、イベントチケット、ストアカード、汎用パス）の作成
• パスのレイアウトデザインと、適切なパススタイルの選択
• Apple 発行証明書を使ったパス署名の設定
• アプリ、メール、ウェブ経由でのパス配布
• プッシュ通知を使ったパス更新の実装
• NFC リーダーやバーコードスキャンの利用
• 「Add to Apple Wallet」バッジの追加
• Verify with Wallet API または ID Verifier の実装
• PassKit フレームワークまたは WalletPasses のドキュメントに関する質問

パススタイルの概要

Apple Wallet は 5 つのパススタイルに対応しています。適切なスタイルを選ぶことが重要です。スタイルによって、ビジュアルレイアウト、情報の階層、時間や場所との関連性の扱いが決まるためです。

スタイル	用途	例
搭乗券	旅行・交通機関	航空券、列車・バスの乗車券
クーポン	販促・割引	店舗クーポン、プロモーションオファー
イベントチケット	開催日時が決まっているイベント	コンサート、映画、スポーツのチケット
ストアカード	ロイヤルティ・特典	ロイヤルティカード、ギフトカード、会員証
汎用パス	その他すべて	会員証、引換券、保険証

スタイルは、関連性（時間枠と場所の半径）の解釈に影響します。搭乗券と映画チケットでは、関連性の時間枠が大きく異なります。実際の用途に合ったスタイルを必ず選んでください。

開発ワークフロー

ユーザーが現在どの段階にいるかに応じて調整しながら、次の手順を順に案内します。

1. パススタイルを選ぶ

どのような種類のパスを作成するのか、ユーザーに尋ねます。用途に基づいて適切なスタイルを選べるよう支援します。判断が難しい場合（例：ジムの会員証）は、ストアカードと汎用パスの違いを説明します。

2. パスをデザインする

• パスは、すべてのデバイスで見やすく、最適化され、見栄えのよいものにします
• デザインのベストプラクティスについては、ヒューマンインターフェイスガイドラインを案内します
• 主なデザイン上の検討事項：ロゴ、ストリップ画像、アイコン、関連するテキストフィールド、バーコードの配置

3. PassKit でパスを作成する

• パスの作成、配布、更新には PassKit フレームワークを使用します
• パスは、pass.json マニフェストとアセットを含む署名済みバンドル（.pkpass ファイル）です
• API の詳細については、PassKit のドキュメントを案内します
• ウェブでの配布については、WalletPasses のドキュメントを参照します

4. パスに署名する

パスは、デベロッパの Apple Developer アカウントに紐づく Apple 発行証明書で署名する必要があります。

伝えるべき重要事項：

• 証明書は証明書、識別子、プロファイルで管理します
• 適切なエンタイトルメントを持つ同じチームのアプリだけが、パスにアクセスできます
• 証明書の期限切れ：デバイス上にある既存のパスは引き続き動作しますが、新しいパスへの署名や更新の送信はできません
• 証明書の失効：パスは機能しなくなります。これは明確に区別して伝えるべき重要な点です

5. パスを配布する

配布方法は 3 つあります。

1. アプリ内 — PassKit API を使用して、「Add to Wallet」バッジとともにパスを表示します
2. メール — .pkpass ファイルを添付します。受信者はタップして追加できます
3. ウェブ — ダウンロード用にパスをホストし、「Add to Wallet」バッジを使用します

重要事項：

• ユーザーは関連アプリをインストールしなくてもパスを追加できます
• 関連アプリがある場合、ユーザーはパスから直接インストールできます
• iCloud により、ユーザーのすべてのデバイス間でパスが同期されます
• ブランド表記については、Add to Apple Wallet バッジのガイドラインを使用します

6. 更新パス

更新方法は 2 種類あります。

• プッシュ通知 — サーバーが更新通知を送信し、ユーザーはタップして変更内容を確認します
• プルして更新 — ユーザーがパスの裏面で手動更新します

よくある更新シナリオ：ゲートの変更、残高の調整、スケジュールの変更。

7. パスの受け付け／引き換え

引き換え方法は 3 種類あります。

方法	詳細
NFC	非接触で引き換えます。ユーザーはデバイスをリーダーにかざします。バーコードは必要ありません。Apple Pay のロイヤリティパスについては、ロイヤリティパスのドキュメントをご覧ください。
バーコード	QR、Aztec、PDF417 形式に対応しています。画面は縦向きに固定され、バックライトが強くなります。iPhone の画面では、レーザースキャナーより光学スキャナーのほうが適切に読み取れます。
テキストによる代替手段	バーコードの下に会員番号／アカウント番号が表示され、手動で入力できます。

8. ID 確認（任意）

ID 確認用の API は 2 種類あります。

• Verify with Wallet API — Wallet に保存された ID を使って、年齢または本人確認を行います。詳細はこちら
• ID Verifier — iPhone をモバイル ID リーダーとして使い、外部ハードウェアなしで対面確認を行います。詳細はこちら

よくある質問

ユーザーから次の質問があった場合は、以下のように回答してください。

「証明書の有効期限が切れるとどうなりますか？」 → デバイス上にある既存のパスは引き続き機能します。ただし、新しいパスへの署名や更新のプッシュはできなくなります。

「どのバーコード形式を使えばよいですか？」 → 最も汎用的なのは QR です。Aztec はコンパクトで、航空会社で使われています。PDF417 は一部のレガシーシステムで使われています。実際に使用するスキャン機器でテストしてください。

「アプリがなくても、ユーザーはパスを追加できますか？」 → はい。アプリをインストールしなくても、メールや Web 経由でパスを追加できます。

「パスのスキャンをテストするにはどうすればよいですか？」 → 実際に使用するハードウェアで必ずテストしてください。iPhone の画面は、レーザースキャナーより光学スキャナーのほうがはるかによく読み取れます。

リファレンス

詳しい技術情報については、references/passkit-technical.md をご覧ください。pass.json の 構造、サーバー側の更新フロー、コード例を説明しています。