[iOS] Apple Payで使う連絡先情報とバリデーションついて

はじめに

こんにちは。CX事業本部の平屋です。

本記事では、Apple Payで使う連絡先情報とバリデーションついて調べた結果を紹介します。

連絡先情報とバリデーションにフォーカスした記事になってます。Apple Payの実装の基本については以下の記事などを参考にしてください。

[iOS 10] アプリを Apple Pay に対応させるために必要な実装について

検証環境

• macOS Mojave 10.15.2
• Xcode Version 11.3.1
• iPhone XS, iOS 13.3.1

使用する連絡先の項目

ペイメントシート作成時の 配送用の連絡先情報 として、以下の5つの項目を指定して検証を行いました。

日本語表記	英語表記
姓名	name
姓名 (フリガナ)	phoneticName
メールアドレス	emailAddress
電話番号	phoneNumber
住所	postalAddress

目次

• 連絡先の項目について
• バリデーションについて
• その他

連絡先の項目について

連絡先の項目は複数あり、各項目は複数の場所で入力/編集できます。また、ユーザーが入力/選択した値は最終的にアプリの実装側から取得できます。

どんな項目があるか、それぞれの項目はどこで入力/編集できるか、実装から取得する場合にどのプロパティを使うのか、ということを見ていきます。

ペイメントシート上に表示される項目

[はじめに] > [検証環境] に記載している5つの項目を指定してペイメントシートを作成した場合、以下の12項目がペイメントシート上の[配送先]および[連絡先]セルに表示されます。

	項目
#1	姓
#2	姓 (フリガナ)
#3	名
#4	名 (フリガナ)
#5	郵便番号
#6	都道府県
#7	郡/市区町村
#8	以降の住所
#9	建物名、部屋番号 (オプション)
#10	国
#11	メールアドレス
#12	電話番号

実装に関して、ペイメントリクエスト作成時に以下のように指定しました。

let request = PKPaymentRequest()

// ...

// 配送先のフィールドのタイプを指定
request.requiredShippingContactFields = [.name,
                                         .phoneticName,
                                         .emailAddress,
                                         .phoneNumber,
                                         .postalAddress]

各アプリで入力可能な項目

連絡先の各項目はペイメントシート、Walletアプリ、設定アプリで入力/編集できます。

以下の表は、それぞれの項目がどこで入力/編集できるかをまとめたものです。

	項目	ペイメントシート	Walletアプリ	設定アプリ
#1	姓	◯	◯	◯
#2	姓 (フリガナ)	◯	✕	✕
#3	名	◯	◯	◯
#4	名 (フリガナ)	◯	✕	✕
#5	郵便番号	◯	◯	◯
#6	都道府県	◯	◯	◯
#7	郡/市区町村	◯	◯	◯
#8	以降の住所	◯	◯	◯
#9	建物名、部屋番号 (オプション)	◯	◯	◯
#10	国	◯	◯	◯
#11	メールアドレス	◯	✕	◯
#12	電話番号	◯	✕	◯

入力/編集方法

各アプリで入力/編集を行うには以下の操作を行います。

• ペイメントシート
  • [配送先]または[連絡先]セルをタップする
  • 詳細画面が表示されるので、そこから編集または新規追加を行う
• Walletアプリ
  • 対象のクレジットカードをタップする
  • 右上の[...]アイコンをタップする
  • [請求先住所]セクションのセルをタップする
  • 請求先住所の一覧が表示されるので、編集または新規追加を行う
• 設定アプリ
  • [WalletとApple Pay]をタップする
  • [配送先住所]、[メール]、[電話]のいずれかをタップする
  • 編集または新規追加を行う

アプリ側の実装で使用するプロパティ

アプリのユーザーが配送用の連絡先情報として入力/選択した情報は、ユーザーの認証完了後に呼ばれるpaymentAuthorizationViewController(_:didAuthorizePayment:handler:)で取得できます。各項目ごとのプロパティはpayment.shippingContactの中にあります。

例えば、姓 を取得する場合は以下のように実装します。

func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: PKPayment, handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
    let contact = payment.shippingContact!
    print("name.familyName:\(contact.name!.familyName!)")

    // ...
}

各項目と実装で使用するプロパティの対応関係は以下の通りです。

	項目	プロパティ
#1	姓	name.familyName
#2	姓 (フリガナ)	phoneticRepresentation.familyName
#3	名	name.givenName
#4	名 (フリガナ)	phoneticRepresentation.givenName
#5	郵便番号	postalAddress.postalCode
#6	都道府県	postalAddress.state
#7	郡/市区町村	postalAddress.city
#8	以降の住所	postalAddress.street
#9	建物名、部屋番号 (オプション)	postalAddress.street
#10	国	postalAddress.country
#11	メールアドレス	emailAddress
#12	電話番号	phoneNumber

• [以降の住所]と[建物名、部屋番号]はpostalAddress.streetに\n区切りで格納されるようです。
  • https://developer.apple.com/documentation/contacts/cnpostaladdress/1403414-street

バリデーションについて

ペイメントシート表示時のバリデーション

このバリデーションはPassKit フレームワーク側が行い、エラーメッセージもこのフレームワーク側が提供するものが表示されます。

例えば、そもそも住所自体が設定されていない場合、ペイメントシートが表示された時点で以下のようになります。

[配送先]セルをタップし、住所を入力してペイメントシートに戻ってくると、支払いに進むことができるようになります。

ユーザー認証後のバリデーション

ユーザーがFace IDなどで認証した後のタイミングで、ユーザーが配送用の連絡先情報として入力/選択した情報を取得し、バリデーションを行うことができます。

バリデーション自体はアプリ側で行います。有効な値でない場合、PassKit フレームワークが用意している仕組みを使用して、ペイメントシートシートにエラーを表示することができます。

以下の例では、名前をバリデーションし、有効な値でない場合はフレームワーク側にエラーを渡しています。エラーオブジェクトは、バリデーションエラーを作成するメソッドpaymentContactInvalidError(withContactField:localizedDescription:)を使用して作成できます。第一引数にはどのフィールドが無効であるかを指定し、第二引数にはペイメントシートに表示するメッセージを指定します。

エラーが複数ある場合は重要度順にソートして、システム側に渡すようにします。(https://developer.apple.com/documentation/passkit/pkpaymentauthorizationresult/2867897-errors)

func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: PKPayment, handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) {
    let contact = payment.shippingContact!

    // ここで取得した値をバリデーションする...
    let isValidName = Validator.isValidName(contact.name)

    guard isValidName else {
        // 対象フィールドを指定してerrorを生成し
        let error = PKPaymentRequest.paymentContactInvalidError(withContactField: .name, localizedDescription: "無効な名前です!")

        // ステータスfailureとエラーを指定してPKPaymentAuthorizationResultを作成し、completionの引数に指定する
        completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
    }

    // ...
}

各項目とフィールドの対応関係

バリデーションエラーを作成するメソッドで指定するフィールドに関して、連絡先の各項目とフィールドの対応関係は以下の通りになります。フィールドは、ペイメントシート作成時に[配送用の連絡先情報]として指定できる項目と同じです。

	項目	フィールド
#1	姓	name
#2	姓 (フリガナ)	phoneticName
#3	名	name
#4	名 (フリガナ)	phoneticName
#5	郵便番号	postalAddress
#6	都道府県	postalAddress
#7	郡/市区町村	postalAddress
#8	以降の住所	postalAddress
#9	建物名、部屋番号 (オプション)	postalAddress
#10	国	postalAddress
#11	メールアドレス	emailAddress
#12	電話番号	phoneNumber

ペイメントシート表示

ユーザー認証後にシステムにバリデーションエラーを渡した場合の表示は以下の通りです。以下の[詳細]列の画面に表示する赤字のエラーメッセージは、アプリ側で指定できます。(このメッセージはpaymentContactInvalidError(withContactField:localizedDescription:)の引数に指定します。)

エラー対象のフィールド: name (姓名)

ペイメントシート	詳細
編集

エラー対象のフィールド: phoneticName (姓名フリガナ)

ペイメントシート	詳細
編集

エラー対象のフィールド: postalAddress (住所)

ペイメントシート	詳細
編集

エラー対象のフィールド: emailAddress (メールアドレス)

ペイメントシート	詳細

エラー対象のフィールド: phoneNumber (電話番号)

ペイメントシート	詳細

その他

連絡先(自分)で入力している値の利用

連絡先アプリ内に「自分」という連絡先があり、この連絡先には自分の情報を入力できます。この連絡先に姓名、フリガナ、住所を入力すると、ペイメントシートでの住所の選択肢に自分の自宅が現れ、配送先として選択できるようになるようです。

ペイメントシート	詳細
連絡先アプリ内の自分の情報

さいごに

本記事では、Apple Payで扱う連絡先情報とバリデーションついて調べた結果を紹介しました。Apple Pay に関する実装を行っている方の参考になれば幸いです!