Appleウォレット / Googleウォレットに チケットを保存する方法

iOSDC Japan 2024 day1での発表資料です。
補足記事: https://muno-92.hatenablog.com/entry/2024/09/01/184414

Transcript

1. Appleウォレット / Googleウォレットに チケットを保存する方法 2024/8/23 iOSDC Japan 2024 day1 muno92
2. 自己紹介 • 所属: スパイダープラス株式会社 • Webエンジニア • iOSDC Japan • 2023〜 コアスタッフ
3. iOSDC Japanのチケットを(Apple|Google) ウォレットに保存できるようにしました 3
4. Appleウォレット Googleウォレット 4
5. このウォレットの裏側について話します 5
6. 目次 • 前提 • 実装することになった経緯 • Googleウォレットへの保存方法 • Appleウォレットへの保存方法 • まとめ
7. 目次 • 前提 • 実装することになった経緯 • Googleウォレットへの保存方法 • Appleウォレットへの保存方法 • まとめ
8. Appleウォレット 搭乗券 クーポン 今回はこれ イベント • 様々な「パス」をiPhone・ Apple Watchに保存可能な サービス • ⚠ 一般的なパスは「他の種別 に当てはまらなかった」場合 のみ使用可 店舗カード その他の一般的なパス 画像: https://developer.apple.com/jp/wallet/ 8
9. Googleウォレット 小売 チケット 今回はこれ アクセス • 様々な「パス」をAndroidス マートフォン・スマートウォッ チに保存可能なサービス • ⚠ 汎用パスは「他の種別に当 てはまらなかった」場合のみ使 用可 健康 汎用パス 画像: https://developers.google.com/wallet?hl=ja 9
10. fortee (フォルテ) https://fortee.jp • カンファレンス支援システム • iOSDC Japanを始め、様々 なカンファレンスの運営に 使用されている • Webアプリケーション (PHP製) • iOSDC Japan 委員長の長谷 川さんが開発 10
11. この発表のターゲット • Appleウォレット・Googleウォレットのパス実装方法に興味が ある人 • Appleウォレットのパスは作った事があるけどGoogleウォレッ トのパスを作った事はない人（or その逆） 11
12. 話すこと 話さないこと • Webアプリケーションから • スマートフォンアプリからパ パスを保存する方法 • パスの構成、基本的な考え方 スを保存する方法 • 特定のプログラミング言語に 依った実装方法 12
13. この発表のゴール • Appleウォレット・Googleウォレットの基本的な考え方を理解 する • パスの実装方法にイメージが湧くようになる • 「Appleウォレット対応だけじゃなくGoogleウォレット対応も したいよね？」など言われても手が動くようになる 13
14. 目次 • 前提 • 実装することになった経緯 • Googleウォレットへの保存方法 • Appleウォレットへの保存方法 • まとめ
15. iOSDC Japan 2023 • forteeのチケットページをブラウザで開いてQRコードを提示 • 受付用QRコードの提示に手間取る人もいた • アンケート「(要約) Appleウォレットに追加できると良いか も」 15
16. 数週間後 16
17. 🤔「Appleウォレットの実装ってどんな感 じなんだろう？」 17
18. Apple Developer Program (有料) • そっ閉じ • Googleウォレットの実装方法を調べてみることに 18
19. https://codelabs.developers.google.com/add-to-wallet-web?hl=ja#0 Node.jsで実装するチュートリアルがあった 19
20. それらしいデザインのパスに 20
21. forteeに移植してみる • 思っていたよりすんなり移植でき、本格的な実装へ 21
22. 目次 • 前提 • 実装することになった経緯 • Googleウォレットへの保存方法 • Appleウォレットへの保存方法 • まとめ
23. パスが保存されるまでの流れ 1. 作りたいパスに応じた情報を登録する • イベント毎にパスクラスを登録 • 参加者毎にパスオブジェクトを登録 2. パス保存用のURLを発行する • URLにアクセスしたアカウントの端末にパスが保存される 23
24. パスクラスとパスオブジェクト • パスクラス • テンプレートのようなもの • 参加者共通の情報を保持 • パスオブジェクト • 参加者固有の情報を保持 24
25. パスクラス (イメージ) logo issuerName eventName cardRowTemplateInfos object.textModulesData['name'] object.ticketNumber パスオブジェクト への参照 heroImage 25
26. パスオブジェクト (イメージ) 26
27. 実装 • 事前準備（後述）で設定した情報を元に認証 • パスクラス・パスオブジェクトの登録 • パス保存用URLの発行 • 保存するパス情報をJWTで付与 • 「ウォレットに追加ボタン」を設置 27
28. 事前準備 1. Google Wallet API 発行者アカウント登録 2. Google Cloudの任意のプロジェクトでGoogle Wallet APIを有効化 3. 2番のプロジェクトでサービスアカウント（アプリケーション用の アカウント）を作成 4. Google Pay and Wallet Consoleで3番のアカウントを承認 https://developers.google.com/wallet/tickets/events/getting-started/onboarding-guide 28
29. パスクラスの登録 1. パスクラスの情報を組み立て 2. パス登録用Web APIにPOST 29
30. パスクラスの情報を組み立て (全体) • パスクラスの送信形式 • Web APIに直接POSTする場合は JSON • SDK経由の場合はJSONをラップ したクラス 30
31. パスクラスの情報を組み立て (1/3) • クラスID: イベント（本編、懇親 会など）毎に一意な値 • reviewStatusにACCEPTEDは指 定できない。登録後、自動で ACCEPTEDに変更される。 31
32. パスクラスの情報を組み立て (2/3) • 自由に使える表示領域に参加者名・チケット番 号への参照を指定 • 参照先textModulesDataの指定方法はインデッ クス指定・id指定が使える • ⚠ id指定の場合、シングルクオートで囲っ た場合しか動かなかったので注意 • (PHP用SDK限定の可能性も無くはない) 32
33. パスクラスの情報を組み立て (3/3) • 画像はURLで指定するので、 インターネット上に公開され ていなければいけない • ローカル環境で指定する 画像も • （伏線） 33
34. パスオブジェクトの登録 • オブジェクトID: 参加者毎に一意 な値 34
35. パス保存用URLの発行 • "https://pay.google.com/gp/v/save/{JWT}" にアクセスすると パスが保存される • JWTの中身 • パスクラス、パスオブジェクト、ウォレット発行用アカ ウントの秘密鍵で作成した署名 35
36. 「Googleウォレットに追加」ボタン • ブランドガイドラインに沿って設置 • このページから画像をダウンロード可能 • ローカライズされたボタンの使用やサイ ズ、周辺との間隔など • 🚫 独自ボタンの作成 https://developers.google.com/wallet/tickets/events/resources/brand-guidelines 36
37. 審査 • 事業者情報登録後、パスの使用用途などスクショを添えてメー ルで提出 https://developers.google.com/wallet/tickets/events/test-and-go-live/ request-publishing-access 37
38. 審査で指摘された内容 38
39. 🚫 汎用パスを使う • 汎用パスを「何にでも使えるパス」だと勘違いしていた • イベントチケットパスを使わなければいけないと指摘あり • 明示的に指摘してくれたとも言える 39
40. 🚫 "Add to Google Wallet"ボタン • 日本語化されたボタンを使っていなかった • "It appears the button being used in your screenshot is incorrect and we ask that you correct this to re ect our Brand Guidelines." 何がどうincorrectなのかの記載は無く、ローカライズ対応が 指摘箇所かもしれないと修正したら審査を通った 40 fl •
41. 本番で動かしたらエラー • 400エラー • • Request contains an invalid argument これだけ 41
42. 本番で動かしたらエラー • 400エラー • • Request contains an invalid argument これだけ • → パスに差し込む画像のURL組み立て処理が間違っていた • ローカル環境では画像を固定していたので気づけず（伏線回収） 42
43. 完成 43
44. 動作確認 • Androidスマートフォン • ブラウザ • 簡易的な閲覧は可能 44
45. デバッグ • 何かしら間違っていた場合はWeb APIからエラーが返ってくる • レスポンスボディにエラーメッセージが記載される 45
46. パスの更新 • PUT / PATCH APIを叩くだけで簡単に更新可能 • パスオブジェクトの削除は無い • キャンセル時など • stateをINACTIVEに変更すれば無効化される 46
47. Googleウォレットまとめ • パスの情報は参加者共通のパスクラスと参加者固有のパスオブ ジェクトに分けて登録する • パスの登録・更新ともにWeb API経由で可能 • 費用は掛からないが初期導入時に審査がある 47
48. 目次 • 前提 • 実装することになった経緯 • Googleウォレットへの保存方法 • Appleウォレットへの保存方法 • まとめ
49. パスが保存されるまでの流れ 1. 作りたいパスの情報を埋め込んだpkpassファイルを参加者毎に生成する 2. pkpassファイルをiPhoneに送る • ファイルダウンロード、メール添付など • pkpassファイルを受け取るとウォレットに保存される https://developer.apple.com/documentation/walletpasses/creating-the-source-for-a-pass https://developer.apple.com/documentation/walletpasses/building-a-pass 49
50. pkpassファイル • 実態はzipファイル • パス情報 • パスに表示する画像 • 改ざん検知のためのハッシュ • 署名 50
51. パス情報 (pass.json) • パスに表示される情報や裏 側でOSに伝えるためのメタ データを格納 51
52. ハッシュ (manifest.json) • zip内にある各ファイルのSHA-1 ハッシュを格納。ファイルが改ざ んされてハッシュが一致しないと 以下のようなエラーが出る。 • "Invalid data error reading pass XXX. For le pass.json, manifest's listed SHA1 hash YYY doesn't match computed hash, ZZZ" fi 52
53. 署名 (signature) • manifest.jsonをPKCS #7 分離形式で署名したファイル • Apple Developerに登録されたアカウントによって作成された パスである事を証明 53
54. 実装 1. Apple Developerから証明書を作成 2. pass.jsonを作成 3. 必要な画像を配置 4. pass.json・画像のSHA-1ハッシュを計算しmanifest.jsonを作成 5. manifest.jsonに署名 6. zip圧縮し、拡張子をpkpassに変更 7. 「Appleウォレットに保存」ボタンを設置 54
55. 証明書の作成 1. CSR (Certi cate Signing Request。証明書署名要求)を作成 • 署名時に秘密鍵が必要になるので、CSR生成時に秘密鍵も作成しておく • 例) openssl req -new -key cert.key -out cert.csr -sha256 2. Apple Developer上 1. Pass Type Identi erを作成 2. CSRをアップロードし、証明書を作成 https://developer.apple.com/documentation/walletpasses/building-a-pass fi fi 55
56. pass.jsonを作成 • イベント情報・参加者情 報・証明書に紐づく開発者 情報の全てを埋め込み • イベントチケットであると ウォレットに伝えるには "eventTicket"の設定が必要 56
57. 必要な画像の配置 • icon: どの種類のパスでも必須 • "Customize the look of your pass by using images for a logo and other items. All passes require an icon" • メールに添付された場合の画像表示や、通知で使用される • その他の画像: パスの種類やレイアウトに応じて必須 • イベントパスのレイアウトは2種類 57
58. イベントパスのレイアウト (Layout 1) 58
59. イベントパスのレイアウト (Layout 2) 59
60. イベントパスで必要な画像ファイル • icon • Layout 1の場合 • background or thumbnail • Layout 2の場合 ←こちらを使用 • strip (横長の画像) 60
61. Layoutはどうやって決まる？ "An event ticket can display logo, strip, background, or thumbnail images. However, if you supply a strip image, don’t include a background or thumbnail image." 🤔 https://developer.apple.com/design/human-interface-guidelines/wallet 61
62. Layoutはどうやって決まる？ "An event ticket can display logo, strip, background, or thumbnail images. However, if you supply a strip image, don’t include a background or thumbnail image." 意訳) background imageかthumbnail imageがあればLayout 1 に、strip imageがあればLayout 2になります。 https://developer.apple.com/design/human-interface-guidelines/wallet 62
63. manifest.jsonに署名 • 例) openssl smime -sign -in manifest.json -inkey 秘密鍵のパス -signer 証明書のパス -cert le 中間証明 書のパス -out signature -outform DER • 署名に必要なファイル • Apple Developerから発行した証明書 • 証明書に紐づく秘密鍵 • WWDR中間証明書 https://developer.apple.com/jp/help/account/reference/wwdr-intermediate-certi cates/ のG4 fi fi 63
64. zip圧縮し、拡張子をpkpassに変更 • ⚠ .DS_Storeなど、不要な・manifest.jsonに記載されていない ファイルはzipに含めない • 存在するとパス閲覧時にエラーが発生する 64
65. 「Appleウォレットに追加」ボタン • ガイドラインに沿って設置 • このページから画像をダウンロード可能 • ローカライズされたボタンの使用やサイ ズ、周辺との間隔など • 🚫 独自ボタンの作成 https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/ 65
66. 完成 66
67. 動作確認 • iPhone (実機、シミュレータ) • Mac • pkpassファイルの簡易的な閲覧は可能 67
68. デバッグ • パスの形式が間違っていても画面上には何もエラーが表示されない • Mac上だとConsole.appでログを確認しないとエラーが分からない • ログが出力されるプロセス • Macで直接パスを開いている場合: Pass Viewer • シミュレータ上のiPhoneでパスを開いている場合: PassBook 68
69. デバッグ 69
70. パスの更新 (fortee未対応) • Push通知を使ってパスの更新も可能 • Googleウォレットに比べるとフローが複雑 70
71. 更新フロー https://developer.apple.com/documentation/walletpasses/adding-a-web-service-to-update-passes 71
72. 更新フロー ①パスを保存 ②端末情報をサーバーに登録 https://developer.apple.com/documentation/walletpasses/adding-a-web-service-to-update-passes 72
73. 更新フロー ①パスを保存 ②端末情報をサーバーに登録 ③Push通知を送信 ④更新可能なパスの一覧を問い合わせ https://developer.apple.com/documentation/walletpasses/adding-a-web-service-to-update-passes 73
74. 更新フロー ①パスを保存 ②端末情報をサーバーに登録 ③Push通知を送信 ④更新可能なパスの一覧を問い合わせ ⑤更新するパスを要求 ⑥pkpassファイル https://developer.apple.com/documentation/walletpasses/adding-a-web-service-to-update-passes 74
75. Appleウォレットまとめ • パスの情報は参加者毎に全情報を埋め込む • パス追加時はpkpassファイルを生成するだけ • 更新時はWeb APIやPush通知を使ったフローを踏む • 有料のApple Developer Programへの登録が必要 • 逆に言えばそれだけ。パス作成時に審査は無い 75
76. メタデータの活用 (fortee未対応) • パスのメタデータを適切に設定するとウォレットがより便利に • イベント開催間際の通知 • イベント終了後にパスを期限切れに • 開始時間・会場の両方に近づいたらiPhoneのロック画面にパスを表示 • etc https://developer.apple.com/documentation/walletpasses/supporting-semantic-tags-in-wallet-passes https://developer.apple.com/documentation/walletpasses/showing-a-pass-on-the-lock-screen https://developers.google.com/wallet/tickets/events/use-cases/upcoming-noti cation fi 76
77. 目次 • 前提 • 実装することになった経緯 • Googleウォレットへの保存方法 • Appleウォレットへの保存方法 • まとめ
78. 比較 Appleウォレット Googleウォレット ・複数。「その他」あり パスの種別 ・複数。「その他」あり 参加者毎に独立 パスの情報 参加者共通項目あり pkpassファイルを作成 パスの新規登録 POST API 複雑 パスの更新 PUT / PATCH APIを叩くだけ パス内に直接格納 (ローカルで開発しやすい) 画像 同じ 違い有 URL指定 （ローカルで開発しにくい） 有料 ※1 費用 無料 なし 審査 初期導入時あり ※1: Apple Developer Programに既に入っていれば実質無料 違い大 78
79. まとめ • Appleウォレット・Googleウォレットにパスを保存するとQRコードの提示に始ま り、様々な点で便利になる • Appleウォレット、Googleウォレットにパスを保存するのは意外と難しくない（特 に新規登録） • 2つのウォレットはパスの種類の分類やメタデータの活用など、似ている点もあるの で応用が効く • 片方を実装したことがある人ならもう片方も実装してみると面白いのでオススメ 79
80. 良きウォレットライフを 80
81. ご清聴ありがとうございました 81
82. 補足) スマートウォッチへの保存方法 • • Apple Watch • Webサイトからパスを追加する場合：iPhone経由 • メールやメッセージからパスを追加する場合：直接 Wear OS スマートウォッチ • Androidスマートフォン経由 https://support.apple.com/ja-jp/guide/watch/apd4362807a0/watchos https://support.google.com/googlepixelwatch/answer/14260807? hl=ja&ref_topic=12652267&sjid=11192229721491948574-AP 82
83. 補足) JWT • • JSON Web Tokensの略。RFC 7519で定義された形式 • コンパクトでURLセーフ • ドットで区切られたヘッダー / ペイロード / 署名からなる文字列 ペイロード • JSON形式のパスクラス・オブジェクトをbase64エンコード 83
84. JWT生成の実装例 (PHP) 84
85. 補足) PKCS #7 • PKCS (Public Key Cryptography Standards、公開鍵暗号標準) の7番目 • データの暗号化や署名に使われるRFC 2315で定義された形式 • 署名データの形式には3パターンある 85
86. 補足) 署名データの形式 • 分離(Detached)形式 ← Appleウォレットで使用 • 署名対象データから独立して署名データを作成する形式 • 電子署名されたメールをS/MIME非対応のメーラーでも読み取れるようにする目的などで使用 • 内包(Enveloping)形式 • 署名データの中に署名対象データを格納する形式 • 包含(Enveloped)形式 • 署名対象データの中に署名データを格納する形式 86
87. 余談) fortee特有の事情 ①〜③ 87
88. ① forteeでの実装方針 • 必須 • 受付用QRコード • チケット番号 (QRコードを読めない • やらない • パスに埋め込んだカンファレンス・ イベント情報の更新 • 時の照合用) • チケット販売を開始する頃には確 定しているはず 頑張ってはやらない • パスに埋め込んだチケット参加者情 報の変更の更新 88
89. ② 参加者名にAttendeeと出る場合がある • forteeの場合、チケットの項目 に参加者名があるとは限らない ので、無い場合はAttendee表記 にしている • iOSDC Japanなら懇親会など 89
90. ③ AppleウォレットでLayout 2を選択 ❌ • カンファレンスやイベントによっては参加者情報にアイコン を保持していないため 90
91. 参考記事 • https://developer.apple.com/jp/wallet/ • https://developer.apple.com/documentation/walletpasses • https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/ • https://developer.apple.com/design/human-interface-guidelines/wallet • https://developer.apple.com/documentation/walletpasses/supporting- semantic-tags-in-wallet-passes 91
92. 参考記事 • https://developers.google.com/wallet • https://developers.google.com/wallet/tickets/events • https://developers.google.com/wallet/tickets/events/resources/brand- guidelines • https://developers.google.com/wallet/tickets/events/use-cases/upcoming- noti cation • https://github.com/google-wallet/rest-samples fi 92