Web Payments API を使用して、配送先住所と支払人の連絡先情報を提供するように Android 決済アプリを更新する方法。
ウェブフォームで配送先住所と連絡先情報を入力するのは、お客様にとって手間がかかります。エラーが発生し、コンバージョン率が低下する可能性があります。
そのため、Payment Request API は、配送先住所と連絡先情報をリクエストする機能をサポートしています。これには複数のメリットがあります。
- ユーザーは数回タップするだけで正しい住所を選択できます。
- 住所は常に標準化された形式で返されます。
- 間違った住所を送信する可能性は低くなります。
ブラウザは、統一された支払いエクスペリエンスを提供するために、配送先住所と連絡先情報の収集を支払いアプリに延期できます。この機能は委任と呼ばれます。
Chrome は可能な限り、顧客の配送先住所と連絡先情報の収集を、呼び出された Android 支払いアプリに委任します。委任により、購入手続き時の負担が軽減されます。
販売者のウェブサイトでは、お客様が選択した配送先住所と配送オプションに応じて、配送オプションと合計金額を動的に更新できます。
既存の Android 支払いアプリに委任のサポートを追加するには、次の手順を実施します。
サポートされている委任を宣言する
ブラウザは、決済アプリが提供できる追加情報のリストを認識し、その情報の収集をアプリに委任できるようにする必要があります。サポートされている委任をアプリの AndroidManifest.xml で <meta-data>
として宣言します。
<activity
android:name=".PaymentActivity"
…
<meta-data
android:name="org.chromium.payment_supported_delegations"
android:resource="@array/supported_delegations" />
</activity>
<resource>
は、次の有効な値から選択した文字列のリストにする必要があります。
[ "payerName", "payerEmail", "payerPhone", "shippingAddress" ]
次の例では、配送先住所と支払人のメールアドレスのみを指定できます。
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="supported_delegations">
<item>payerEmail</item>
<item>shippingAddress</item>
</string-array>
</resources>
必要なお支払い方法について PAY
インテント エクストラを解析する
販売者は、paymentOptions
ディクショナリを使用して、必要な追加情報を指定できます。Chrome は、次のパラメータを Intent の追加情報として PAY
アクティビティに渡すことで、アプリが提供できる必須オプションのリストを取得します。
paymentOptions
paymentOptions
は、アプリが委任サポートを宣言している販売者指定の支払いオプションのサブセットです。
val paymentOptions: Bundle? = extras.getBundle("paymentOptions")
val requestPayerName: Boolean? = paymentOptions?.getBoolean("requestPayerName")
val requestPayerPhone: Boolean? = paymentOptions?.getBoolean("requestPayerPhone")
val requestPayerEmail: Boolean? = paymentOptions?.getBoolean("requestPayerEmail")
val requestShipping: Boolean? = paymentOptions?.getBoolean("requestShipping")
val shippingType: String? = paymentOptions?.getString("shippingType")
次のパラメータを含めることができます。
requestPayerName
- 支払人の氏名が必須かどうかを示すブール値。requestPayerPhone
- 支払人のスマートフォンが必須かどうかを示すブール値。requestPayerEmail
- 支払者のメールアドレスが必須かどうかを示すブール値。requestShipping
- 配送情報が必要かどうかを示すブール値。shippingType
- 配送の種類を示す文字列。配送のタイプは、"shipping"
、"delivery"
、"pickup"
のいずれかです。アプリは、ユーザーの住所や配送オプションの選択を求める際に、UI でこのヒントを使用できます。
shippingOptions
shippingOptions
は、販売者が指定した配送オプションの Parcelable 配列です。このパラメータは、paymentOptions.requestShipping ==
true
の場合にのみ存在します。
val shippingOptions: List<ShippingOption>? =
extras.getParcelableArray("shippingOptions")?.mapNotNull {
p -> from(p as Bundle)
}
各配送オプションは、次のキーを持つ Bundle
です。
id
- 配送オプションの識別子。label
- ユーザーに表示される配送オプションのラベル。amount
- 文字列値のcurrency
キーとvalue
キーを含む送料バンドル。selected
- 支払いアプリに配送オプションが表示されたときに、配送オプションを選択するかどうか。
selected
以外のキーはすべて文字列値を持ちます。selected
にはブール値があります。
val id: String = bundle.getString("id")
val label: String = bundle.getString("label")
val amount: Bundle = bundle.getBundle("amount")
val selected: Boolean = bundle.getBoolean("selected", false)
支払いレスポンスで必要な情報を提供する
アプリは、PAY
アクティビティへのレスポンスに必要な追加情報を含める必要があります。
そのためには、次のパラメータをインテントの追加情報として指定する必要があります。
payerName
- 支払人の氏名。paymentOptions.requestPayerName
が true の場合、空でない文字列にする必要があります。payerPhone
- 支払者の電話番号。paymentOptions.requestPayerPhone
が true の場合、空でない文字列にする必要があります。payerEmail
- 支払者のメールアドレス。paymentOptions.requestPayerEmail
が true の場合は、空でない文字列にする必要があります。shippingAddress
- ユーザーが指定した配送先住所。paymentOptions.requestShipping
が true の場合、これは空ではないバンドルである必要があります。バンドルには、物理アドレスのさまざまな部分を表す次のキーが必要です。city
countryCode
dependentLocality
organization
phone
postalCode
recipient
region
sortingCode
addressLine
addressLine
以外のすべてのキーは文字列値を持ちます。addressLine
は文字列の配列です。
shippingOptionId
- ユーザーが選択した配送オプションの識別子。paymentOptions.requestShipping
が true の場合、空でない文字列にする必要があります。
お支払いレスポンスの検証
呼び出された支払いアプリから受信した支払いレスポンスのアクティビティ結果が RESULT_OK
に設定されている場合、Chrome は追加情報が必要かどうかをそのエクストラで確認します。検証で不合格になると、Chrome は拒否された Promise を request.show()
から返し、次のいずれかのデベロッパー向けエラー メッセージが返されます。
'Payment app returned invalid response. Missing field "payerEmail".'
'Payment app returned invalid response. Missing field "payerName".'
'Payment app returned invalid response. Missing field "payerPhone".'
'Payment app returned invalid shipping address in response.'
'... is not a valid CLDR country code, should be 2 upper case letters [A-Z]'
'Payment app returned invalid response. Missing field "shipping option".'
次のコードサンプルは、有効なレスポンスの例です。
fun Intent.populateRequestedPaymentOptions() {
if (requestPayerName) {
putExtra("payerName", "John Smith")
}
if (requestPayerPhone) {
putExtra("payerPhone", "4169158200")
}
if (requestPayerEmail) {
putExtra("payerEmail", "john.smith@gmail.com")
}
if(requestShipping) {
val address: Bundle = Bundle()
address.putString("countryCode", "CA")
val addressLines: Array<String> =
arrayOf<String>("111 Richmond st. West")
address.putStringArray("addressLines", addressLines)
address.putString("region", "Ontario")
address.putString("city", "Toronto")
address.putString("postalCode", "M5H2G4")
address.putString("recipient", "John Smith")
address.putString("phone", "4169158200")
putExtra("shippingAddress", address)
putExtra("shippingOptionId", "standard")
}
}
省略可: 動的フローをサポートする
ユーザーがエクスプレス配送オプションを選択した場合や、ユーザーが国際配送オプションを選択したときに利用可能な配送オプションのリストや価格が変更された場合など、取引の合計金額が増加することがあります。アプリでユーザーが選択した配送先住所またはオプションを提供する場合、配送先住所またはオプションの変更を販売者に通知し、更新された支払い情報(販売者から提供)をユーザーに表示できる必要があります。
AIDL
新しい変更を販売者に通知するには、Chrome の AndroidManifest.xml で宣言されている PaymentDetailsUpdateService
サービスを使用します。このサービスを使用するには、次の内容の 2 つの AIDL ファイルを作成します。
app/src/main/aidl/org/chromium/components/payments/IPaymentDetailsUpdateService
package org.chromium.components.payments;
import android.os.Bundle;
interface IPaymentDetailsUpdateServiceCallback {
oneway void updateWith(in Bundle updatedPaymentDetails);
oneway void paymentDetailsNotUpdated();
}
app/src/main/aidl/org/chromium/components/payments/IPaymentDetailsUpdateServiceCallback
package org.chromium.components.payments;
import android.os.Bundle;
import org.chromium.components.payments.IPaymentDetailsUpdateServiceCallback;
interface IPaymentDetailsUpdateService {
oneway void changePaymentMethod(in Bundle paymentHandlerMethodData,
IPaymentDetailsUpdateServiceCallback callback);
oneway void changeShippingOption(in String shippingOptionId,
IPaymentDetailsUpdateServiceCallback callback);
oneway void changeShippingAddress(in Bundle shippingAddress,
IPaymentDetailsUpdateServiceCallback callback);
}
お客様が選択したお支払い方法、配送先住所、配送オプションの変更について販売者に通知する
private fun bind() {
// The action is introduced in Chrome version 92, which supports the service in Chrome
// and other browsers (e.g., WebLayer).
val newIntent = Intent("org.chromium.intent.action.UPDATE_PAYMENT_DETAILS")
.setPackage(callingBrowserPackage)
if (packageManager.resolveService(newIntent, PackageManager.GET_RESOLVED_FILTER) == null) {
// Fallback to Chrome-only approach.
newIntent.setClassName(
callingBrowserPackage,
"org.chromium.components.payments.PaymentDetailsUpdateService")
newIntent.action = IPaymentDetailsUpdateService::class.java.name
}
isBound = bindService(newIntent, connection, Context.BIND_AUTO_CREATE)
}
private val connection = object : ServiceConnection {
override fun onServiceConnected(className: ComponentName, service: IBinder) {
val service = IPaymentDetailsUpdateService.Stub.asInterface(service)
try {
if (isOptionChange) {
service?.changeShippingOption(selectedOptionId, callback)
} else (isAddressChange) {
service?.changeShippingAddress(selectedAddress, callback)
} else {
service?.changePaymentMethod(methodData, callback)
}
} catch (e: RemoteException) {
// Handle the remote exception
}
}
}
サービスの開始インテントに使用される callingPackageName
には、支払いリクエストを開始したブラウザに応じて、次のいずれかの値を指定できます。
Chrome チャンネル | パッケージ名 |
---|---|
Stable |
"com.android.chrome"
|
Beta |
"com.chrome.beta"
|
開発 |
"com.chrome.dev"
|
Canary |
"com.chrome.canary"
|
Chromium |
"org.chromium.chrome"
|
Google クイック検索ボックス(WebLayer 埋め込みツール) |
"com.google.android.googlequicksearchbox"
|
changePaymentMethod
ユーザーが選択したお支払い方法の変更を販売者に通知します。paymentHandlerMethodData
バンドルには、methodName
キーと省略可能な details
キーが含まれます。どちらも文字列値です。Chrome は、空でない methodName
を含む空でないバンドルをチェックし、検証に失敗した場合は、callback.updateWith
を介して次のいずれかのエラー メッセージを含む updatePaymentDetails
を送信します。
'Method data required.'
'Method name required.'
changeShippingOption
ユーザーが選択した配送オプションの変更について販売者に通知します。shippingOptionId
は、販売者が指定した配送オプションのいずれかの識別子にする必要があります。Chrome は空でない shippingOptionId
をチェックし、検証に失敗した場合は callback.updateWith
を介して次のエラー メッセージを含む updatePaymentDetails
を送信します。
'Shipping option identifier required.'
changeShippingAddress
ユーザーが指定した配送先住所が変更されたことを販売者に通知します。Chrome は、有効な countryCode
を含む空でない shippingAddress
バンドルをチェックし、検証に失敗した場合は、callback.updateWith
を介して次のエラー メッセージを含む updatePaymentDetails
を送信します。
'Payment app returned invalid shipping address in response.'
無効な状態に関するエラー メッセージ
Chrome は、変更リクエストの受信時に無効な状態を検出すると、除去された updatePaymentDetails
バンドルで callback.updateWith
を呼び出します。バンドルには、"Invalid state"
を含む error
キーのみが含まれます。無効な状態の例を次に示します。
- Chrome が以前の変更(進行中の変更イベントなど)に対する販売者の応答を待機している場合。
- 支払いアプリから提供された配送オプションの識別子が、販売者が指定した配送オプションのいずれにも属していない。
更新されたお支払い情報を販売者から受け取る
private fun unbind() {
if (isBound) {
unbindService(connection)
isBound = false
}
}
private val callback: IPaymentDetailsUpdateServiceCallback =
object : IPaymentDetailsUpdateServiceCallback.Stub() {
override fun paymentDetailsNotUpdated() {
// Payment request details have not changed.
unbind()
}
override fun updateWith(updatedPaymentDetails: Bundle) {
newPaymentDetails = updatedPaymentDetails
unbind()
}
}
updatePaymentDetails
は、PaymentRequestDetailsUpdate
WebIDL ディクショナリ(modifiers
フィールドを除去した後)と同等のバンドルで、次のオプション キーが含まれています。
total
-currency
キーとvalue
キーを含むバンドル。どちらのキーも文字列値を持ちます。shippingOptions
- 配送オプションの Parcelable 配列error
- 一般的なエラー メッセージを含む文字列(changeShippingOption
が有効な配送オプション ID を提供しない場合など)stringifiedPaymentMethodErrors
- お支払い方法の検証エラーを表す JSON 文字列addressErrors
- 配送先住所と文字列値と同じオプションのキーを含むバンドル。各キーは、配送先住所の対応する部分に関連する検証エラーを表します。
キーが存在しない場合は、値が変更されていないことを意味します。