2016.04.26
iOS Walletを作ってみよう-前編
こんにちは。GMOインターネットの次世代システムのJ.Lです。
みなさんはiOSの「Wallet」をご存知でしょうか。もしかして、「Passbook」はご存知でしょうか。
飛行機のチケットやクーポンなどで使えるこのPassbookがApple Payとの関連性を強くするため、
iOS 9からは「Wallet」と名前が変更となりました。
では、そもそもWalletは何か、何ができるのか、Apple Payとはどのように統合されたのか調べましょう。
（Apple Payは現在（2016/4/4）まで日本ではサービスされてないため、Apple Payそのものとその関連付けられている機能は使えません。）
このブログでは前編と後編に分けてWalletの使い方を詳しく紹介します。
Walletとは
飛行機のチケットとかお店のポイントなどとして使える電子カードの一種です。日本ではお財布携帯がすでに広く普及されているかつ、外部とのインタフェースがバーコードのみであるため、普及はいまいちの状態です。ただし、今後Apple Payが普及された場合はNFC＋指紋認証で簡単かつ強いセキュリティを持つ強力な機能に変わると思います。（その前にApple Payがまず日本で使えるようになるかつApple Pay用の端末が普及される必要がありますが。。。）
そして、お財布携帯と同じくWalletの中に複数のカードを追加することができます。そして、そのカードをWalletでは「パス」と呼びます。そのパスをそれぞれ追加することで、Walletインタフェースを通じさまざまなことができます。これから具体的に何ができるかを説明します。
Walletにて使えるパスの配信は
まず、パスの配信のやり方について説明しましょう。パスは以下の３つの方法で配信可能です。
- Wallet対応アプリ
- ウェブサイト
- メール
Wallet対応アプリはWalletアプリ検索で検索可能です。
パスの作成
では、いったん簡単にパスを作ってみましょう。まずパスを作るためには、iOS Developer Programに加入する必要があります。もし、iOS Developer Programを持ってない方はこちらから登録してください。（有料）
パスID作成
お持ちの方はまず、Member Centerの「Pass Type IDs」に入りパスに使う「Pass Type ID」を発行しましょう。
Pass Type ID DescriptionはPassの簡単な説明を入力します。
Identifierは「pass.」で始まるユニークな値を設定してください。ドメインの逆順の名前をお勧めします。
その次は「Continue」をクリックするします。
次の画面で内容を確認し、問題なければ「Register」をクリックしてください。
次は「Done」をクリックしてパスID作成を完了してください。
パス証明書作成
次はパス用の証明書を作成します。この証明書は後でパスをラッピングする時やパスのアップデートをする際に利用しますので、必ず作成する必要があります。
証明書は以下の手順で作成可能です。
「Member CenterのiOS Pass Type IDs」から上の手順で作成したパスIDをクリックしてください。
パスIDの下に表示される「Edit」ボタンをクリックしてください。
「Create Certificate…」ボタンをクリックしてください。
「Continue」をクリックしてください。
次はCSRファイルの作成です。
Macの場合
Macの場合は「Keychain Access」アプリから簡単に作れます。
手順はウェブページに書いている通りに「Keychain Access」を起動し、メニューの「Keychain Access」→「証明書アシスタント」→「認証局に証明書を要求…」をクリックします。
「ユーザのメールアドレス」欄はご自身のメールアドレスを入力してください。
「通称」欄は区別できる名前を入れてください。（Keychain Accessの秘密鍵の名前がここで入れた値になります。）
「CA のメールアドレス」は空きのままで、「ディスクに保存」を選択し、「続ける」ボタンをクリックしてください。
作成されるCSRファイルを適当な場所に保存してください。
Linuxの場合
Linux以外の場合でもOpensslを利用すれば同じ手順で作成できると思います。
# 秘密鍵の作成 openssl genrsa -aes256 -out my_pass_key.pem 2048 # CSRの作成 - CSR作成時に入力する内容は適当な値を設定してください。 openssl req -new -key my_pass_key.pem -out my_pass.csr
CSRファイルアップロード
作成したCSRファイルを先ほどのMember Center画面にてアップロードしてください。
アップロードし、「Continue」をクリックすると署名された証明書がダウンロードできます。
証明書の作成はこれで完了です。
次にパス本体を作ってみましょう。
パス作成
パスの種類
パスの種類は以下の通りです。
- 航空券（主に出発地と目的地決まっている乗り物のチケット）
- クーポン
- イベントチケット
- 一般的なパス
- 店舗カード
各パスのレイアウトは以下のURLを参照してください。
パス作成
パスの本体はパスパッケージという拡張子が「pkpass」のファイルです。
ただし、その正体は「zip」ファイルであり、複数のファイルがzipで圧縮されています。（zipツールで普通に解凍できます。）
パスパッケージの中身は以下のようなファイルが存在します。
- イメージファイル（@2xファイルはレティーナ画面用）パスの種類によって使用するイメージが違いますので、詳しくは下で説明するパスのレイアウトを参照してください。
- background.png：パスのバックグラウンド表示に使用されるイメージ
- footer.png：バーコードの上に表示されるイメージ
- icon.png：パスのアイコン。通知やメール添付ファイルのアイコンとして表示される
- logo.png：パスの左上に表示されるロゴイメージ
- strip.png：パスの真ん中あたりに表示するメインイメージ
- thumbnail.png：メンバーシップカードなどに表示する写真イメージなど
- pass.jsonファイル
- パスの構造及び各種データを設定するファイル。JSON形式で作成する
- *.lprojフォルダ
- 多言語化対応する際に該当言語のフォルダを作成する。
- 中身は対応用のイメージファイルと他言語対応文字列データファイル（pass.strings）です。
- 「*」はISO 639-1の言語コードを設定します。
- manifest.jsonファイル
- パッケージの中の全てのファイル（manifest.jsonとsignature以外）のHashコードをJSON形式で保存
- signatureファイル
- パスの妥当性チェック用の署名ファイル
イメージファイルは必要なファイルのみで構成できます。その他のファイルの中身について続けて説明します。
pass.json
パスの主な内容はpass.jsonにて定義します。形式は拡張子通りにJSONであります。
続けてpass.jsonにて定義可能なキーを説明します。
ちなみに、「必須」と書いてない項目についてはオプションですので、必要に応じて設定してください。
最上位レベルのキー
全てのパスに必須なキー
- description：必須。文字列。他言語対応可能。パスの説明
- formatVersion：必須。数値。1
- organizationName：必須。文字列。他言語対応可能。組織名
- passTypeIdentifier：必須。文字列。Member Centerにて登録した「Pass Type ID」
- serialNumber：必須。文字列。パスのシリアル番号。Pass Type IDに対してユニークである必要がある。
- teamIdentifier：必須。文字列。iOS Developer Programのteam ID証明書などから確認できる。
アプリ連動関連
- appLaunchURL：文字列。アプリ起動URL。パスからアプリを起動する際に使うURL。アプリはURLスキムの対応が必要
- associatedStoreIdentifiers：文字列のリスト。AppStoreに登録されているアプリのIdentifierのリスト。インストールされてない場合はApp Storeのリックが表示される。インストールされている場合はアプリ起動リンクが表示される
アプリに引き渡し情報
- userInfo：JSONデータ。アプリを起動する際に渡すデータ。パスでは表示しない
パスの有効・無効
- expirationDate：W3C Dateフォーマットの文字列。パスの有効期限
- voided：Boolean。trueの場合パスが無効
パス通知設定
- beacons：リスト。ビーコンデータのリスト。設定されているビーコンが端末から検知された際に通知が発生する
- locations：リスト。位置情報のリスト。該当の位置にいると端末が検知した場合通知を表示する。
- maxDistance：数値。locationsに設定されている位置情報から通知する距離（デフォルトの値とこの値中少ない方が適用される）
- relevantDate：W3C Dateフォーマットの文字列。通知を行う時間（映画開始時間など）
パスのタイプ
それぞれのレイアウトは上にあるレイアウトリンクを参照してください。
- boardingPass：パスデータ。搭乗券
- coupon：パスデータ。クーポン
- eventTicket：パスデータ。イベントチケット
- generic：パスデータ。一般的なパス
- storeCard：パスデータ。店舗カード
パスの表示関連
- barcode：バーコドデータ。iOS 9以降はDeprecated
- barcodes：バーコドデータのリスト。iOS 9から利用可能
- backgroundColor：カラーの文字列。ex）”rgb(255, 255, 255)”。パスの背景色
- foregroundColor：カラーの文字列。ex）”rgb(255, 255, 255)”。パスの表色
- groupingIdentifier：文字列。搭乗券とイベントチケットパスのみ利用可能。設定した場合は同じグループのパス同士でグルーピングされて表示される
- labelColor：カラーの文字列。ex）”rgb(255, 255, 255)”。ラベルの色。設定されてない場合は。適当な色で表示される。
- logoText：文字列。ロゴの文字列
- suppressStripShine：Deprecated
Web Service
- authenticationToken：文字列。Web Serviceを利用する際の認証トークン。詳しくは後編にて説明します。
- webServiceURL：文字列。Web Serviceで利用するサーバーURL。詳しくは後編にて説明します。
NFC
- nfc：NFCデータJSON。NFC（Apple Pay）を利用するサービスを提供する際に利用。storeCardパスのみ有効。本キーが有効になるためには「Enhanced Passbook/NFC」証明書が含まれている必要がある。詳しい情報は次のフォームにて問い合わせしてください。https://www.apple.com/support/apple-pay/feedback/
下位レベルキー
最上位のキーにて文字列やリスト以外の設定する部分や補足が必要な部分の説明です。
パスデータ
- auxiliaryFields：フィルドデータリスト。auxiliaryの表示位置についてはパスのレイアウトを参照してください。
- backFields：フィルドテータリスト。パスの裏面（ℹ︎ボタンをタップした時表示される画面）にて表示する情報
- headerFields：フィルドデータリスト。backの表示位置についてはパスのレイアウトを参照してください。
- primaryFields：フィルドデータリスト。primaryの表示位置についてはパスのレイアウトを参照してください。
- secondaryFields：フィルドデータリスト。secondaryの表示位置についてはパスのレイアウトを参照してください。
- transitType：文字列。boardingPassのパスのみ有効。次の何れかの値を設定する
PKTransitTypeAirPKTransitTypeBoatPKTransitTypeBusPKTransitTypeGenericPKTransitTypeTrain
ビーコンデータ
- major：16bitのunsigned integer。ビーコンのmajor
- minor：16bitのunsigned integer。ビーコンのminor
- proximityUUID：文字列。必須。ビーコンのUUID
- relevantText：文字列。該当のビーコンを検知した場合、ロック画面に表示する文字列
位置情報データ
- altitude：double。高度（m）
- latitude：double。緯度
- longitude：double。経度
- relevantText：文字列。該当の位置を検知した場合、ロック画面に表示する文字列
バーコードデータ
- altText：文字列。バーコードの近くに表示する人間が読める情報
- format：文字列。必須。バーコードのフォーマット。次の何れかを設定する
PKBarcodeFormatQR：QRコードPKBarcodeFormatPDF417：PDF417形式の2次元バーコードPKBarcodeFormatAztec：Aztec形式の2次元バーコードPKBarcodeFormatCode128：iOS 9以上。1次元バーコード。iOS 9以上でのみ表示可能であるため、barcodesの方で設定する必要がある
- message：文字列。必須。バーコードと一緒に表示する情報
- messageEncoding：IANA文字種の名前。必須。messageのエンコーディング。主に「iso-8859-1」を設定する
NFCデータ
- message：文字列。必須。Apple Payターミナルにて表示する文字列（64byte以下。オーバーされたデータのはターミナルにて省略される）
- encryptionPublicKey：文字列。暗号化に利用される公開キー。base64エンコーディングされた証明書（P-256グループのECDHアルゴリズムを利用）
フィルドデータ
- attributedValue：文字列。他言語対応可能。主に「a」タグのリンクの文字列を設定する。本キーが設定された場合はvalueキーの値を上書きする
- changeMessage：文字列。他言語対応可能。変更する値が含まれているメッセージを設定する変更される部分は「%@」と設定し、valueキーの値がその場所に設定される
- 例）「ゲートが%@に変更されました」
- dataDetectorTypes：文字列のリスト。以下のいずれかを設定した場合valueの値が該当するかを検知する。本キーが設定されてない場合は全て有効となる。全て無効にする場合は空のリストを設定する
- PKDataDetectorTypePhoneNumber：電話番号→タップすると発信可能になる
- PKDataDetectorTypeLink：リンク→Safariで表示するリンク
- PKDataDetectorTypeAddress：住所→マップに表示するリンク
- PKDataDetectorTypeCalendarEvent：カレンダーイベント→カレンダーにイベントを追加するリンク
- key：文字列。必須。パスデータ全体でユニークな値
- label：文字列。他言語対応可能。表示するラベル文字列
- textAlignment：文字列。文字列の寄せ。以下の何れかを設定。デフォルトは「PKTextAlignmentNatural」
- PKTextAlignmentLeft：左寄せ
- PKTextAlignmentCenter：中央
- PKTextAlignmentRight：右寄せ
- PKTextAlignmentNatural：デフォルト
- value：文字列またはISO 8601形式のDateの文字列、数値。必須。他言語対応可能。フィルドの値
Dateスタイル
フィルドデータのValueがDate形式の場合、以下のキーで表示をカスタマイズできる
- dateStyle：文字列。以下の何れかを設定する
- PKDateStyleNone
- PKDateStyleShort
- PKDateStyleMedium
- PKDateStyleLong
- PKDateStyleFull
- ignoresTimeZone：Boolean。trueの場合、機器のタイムゾーンを無視し、valueに設定されているタイムゾーンで表示する。デフォルトはfalse
- isRelative：Boolean。trueの場合、相対時間（xx分前）として表示する。デフォルトはfalse
- timeStyle：文字列。dateStyleと同じ
数値スタイル
フィルドデータのValueが数値の場合、以下のキーで表示をカスタマイズできる
- currencyCode：文字列。通貨単位。ISO 4217のcurrency codeを設定する
- numberStyle：文字列。以下のいずれかを設定する
- PKNumberStyleDecimal：10進数表示。1234.5678→1234.5678
- PKNumberStylePercent：パーセント。
1234.5678→123457% - PKNumberStyleScientific：正規化表示。
1234.5678→1.234568E+003 - PKNumberStyleSpellOut：文字列で表示。
1234.5678→one thousand two hundred thirty-four point five six seven eight
*.lproj
他言語対応ファイル
イメージ（同じファイル名）やpass.jsonの中の文字列（pass.strings）を含んだフォルダ
pass.jsonの他言語対応の場合は他言語対応する箇所にキーを設定し、pass.stringsに該当のキーとその値を設定する
例）”MESSAGE_1″ = “こんにちは”;
manifest.json
本ファイルとsignatureファイル以外のすべてのファイルに対するHash値をJSON形式で保存するファイル
ファイルのHash値は以下のコマンドで取得できます。
$ openssl sha1 icon.png
signature
minifest.jsonに対してAppleから発行された証明書で署名した署名データが格納されているファイル
署名は以下のコマンドで取得可能
$ openssl smime -binary -sign -certfile WWDR.pem -signer passcertificate.pem -inkey passkey.pem -in manifest.json -out signature -outform DER -passin pass:12345
※ WWDR.pemは中間証明書であり以下のURLから取得できる
Apple PKI のWWDR Certificate (Expiring 02/07/23)
※ passcertificate.pemファイルはAppleから発行された証明書ですが、ダウンロードしたファイルはDER形式であるため以下のコマンドでPEMに変換できる
$ openssl x509 -inform DER -in pass.cer -outform PEM -out passcertificate.pem
※ passkey.pemは秘密鍵ファイル
※ pass:12345の「12345」の部分は秘密鍵のパスである
パスパッケージの生成
上のファイルすべてをzipで固めその拡張子を「pkpass」としてください。
パスの配信
メール
メールでの配信の場合、該当機器のメールアカウントにパスパッケージを添付するだけで良いです。
ウェブサイト
ウェブサイトから配信する場合は、パスパッケージファイルをダウンロードすることが出来れば十分です。
ただし、ダウンロードレスポンスヘッダの「Content-Type」に「application/vnd.apple.pkpass」を設定する必要があります。
アプリ
アプリからの配信は後編を参照してください。
まとめ
Walletのパスを作る方法に関して説明しました。後編ではアプリからのパス配信やWeb Serviceを利用しパスの更新などを行う方法に関して説明します。
次世代システム研究室では、アプリケーション開発や設計を行うアーキテクトを募集しています。アプリケーション開発者の方、次世代システム研究室にご興味を持って頂ける方がいらっしゃいましたら、ぜひ 募集職種一覧からご応募をお願いします。
グループ研究開発本部の最新情報をTwitterで配信中です。ぜひフォローください。
Follow @GMO_RD
