透過 Android 付款應用程式提供運送和聯絡資訊

如何更新 Android 付款應用程式,以便透過 Web Payments API 提供運送地址和付款者的聯絡資訊。

Sahel Sharify
Sahel Sharify

透過網路表單輸入運送地址和聯絡資訊,可能會讓客戶感到不便。這可能會導致錯誤並降低轉換率。

因此,Payment Request API 支援要求運送地址和聯絡資訊的功能。這麼做有以下多項好處:

  • 使用者只要輕觸幾下,就能選擇正確的地址。
  • 系統一律會以標準格式傳回地址。
  • 你就比較不會提交錯誤的地址。

瀏覽器可以將收貨地址和聯絡資訊的收集工作延後交由付款應用程式處理,以提供統一的付款體驗。這項功能稱為委派

在可行情況下,Chrome 會將收集客戶運送地址和聯絡資訊的作業,委派給叫用的 Android 付款應用程式。委派作業可減少結帳時的摩擦。

商家網站可根據消費者選擇的運送地址和運送選項,動態更新運送選項和總價。

運送選項和運送地址即將變更。瞭解這項功能如何動態影響運送選項和總價。

如要在現有的 Android 付款應用程式中新增委派支援功能,請實作下列步驟:

  1. 宣告支援的委派作業
  2. 剖析 PAY 意圖額外資料,以便取得必要的付款選項
  3. 在付款回應中提供必要資訊
  4. [選用] 支援動態流程
    1. 通知商家使用者所選付款方式、運送地址或運送選項的變更
    2. 接收商家提供的更新後的付款資料 (例如,根據所選運送選項費用調整後的總金額)

宣告支援的委派

瀏覽器必須知道付款應用程式可提供的其他資訊清單,才能將資訊的集合委派給應用程式。在應用程式的 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 是商家指定運送選項的可包裝陣列。這個參數只會在 paymentOptions.requestShipping == true 時存在。

val shippingOptions: List<ShippingOption>? =
    extras.getParcelableArray("shippingOptions")?.mapNotNull {
        p -> from(p as Bundle)
    }

每個運送選項都是 Bundle,其中包含下列鍵。

  • id:運送選項 ID。
  • label:向使用者顯示的運送選項標籤。
  • amount:運費組合,其中包含 currencyvalue 鍵,並含有字串值。
    • currency 會顯示運費的幣別,以 ISO4217 格式正確格式表示的 3 個英文字母代碼
    • 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:使用者選取的運送選項 ID。當 paymentOptions.requestShipping 為 true 時,這應該是非空白字串。

驗證付款回應

如果從叫用的付款應用程式收到的付款回應活動結果設為 RESULT_OK,Chrome 就會檢查其額外資訊中是否有必要的額外資訊。如果驗證失敗,Chrome 會從 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 服務。如要使用此服務,請建立含有以下內容的兩個 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 版本 套件名稱
穩定 "com.android.chrome"
Beta 版 "com.chrome.beta"
開發 "com.chrome.dev"
Canary 版 "com.chrome.canary"
"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 應為商家指定的運送選項之一的 ID。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 仍在等待商家回應先前的變更 (例如進行中的變更事件)。
  • 付款應用程式提供的運送選項 ID 不屬於任何商家指定的運送選項。

接收商家提供的最新付款詳細資料

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:包含 currencyvalue 鍵的組合,兩個鍵都含有字串值
  • shippingOptions - 運送選項的 parcelable 陣列
  • error:包含一般錯誤訊息的字串 (例如 changeShippingOption 未提供有效的運送選項 ID)
  • stringifiedPaymentMethodErrors:代表付款方式驗證錯誤的 JSON 字串
  • addressErrors:包含選用鍵的組合,與運送地址和字串值相同。每個鍵都代表與運送地址對應部分相關的驗證錯誤。

缺少的鍵代表其值未變更。