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

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

はじめに

こんにちは。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 に関する実装を行っている方の参考になれば幸いです!