Web Payments API की मदद से, शिपिंग का पता और पेमेंट करने वाले की संपर्क जानकारी देने के लिए, Android पेमेंट ऐप्लिकेशन को अपडेट करने का तरीका.
वेब फ़ॉर्म के ज़रिए शिपिंग पता और संपर्क जानकारी डालना, ग्राहकों के लिए एक मुश्किल काम हो सकता है. इससे गड़बड़ियां हो सकती हैं और कन्वर्ज़न रेट कम हो सकता है.
इसलिए, पेमेंट का अनुरोध एपीआई में, शिपिंग पते और संपर्क जानकारी का अनुरोध करने की सुविधा काम करती है. इसके कई फ़ायदे हैं:
- उपयोगकर्ता सिर्फ़ कुछ टैप करके, सही पता चुन सकते हैं.
- पता हमेशा स्टैंडर्ड फ़ॉर्मैट में दिखाया जाता है.
- गलत पता सबमिट करने की संभावना कम होती है.
एक जैसा पेमेंट अनुभव देने के लिए ब्राउज़र, किसी पेमेंट ऐप्लिकेशन में शिपिंग पता और संपर्क जानकारी इकट्ठा करने को रोक सकते हैं. इस सुविधा को डेलिगेशन कहा जाता है.
जब भी हो सके, Chrome, खरीदार के शिपिंग पते और संपर्क जानकारी को इकट्ठा किए गए, Android पेमेंट ऐप्लिकेशन में भेज देता है. इस सुविधा को इस्तेमाल करने से, चेकआउट के दौरान आने वाली दिक्कतें कम हो जाती हैं.
व्यापारी या कंपनी की वेबसाइट, शिपिंग के विकल्पों और कुल कीमत को डाइनैमिक तौर पर अपडेट कर सकती है. यह जानकारी, खरीदार के शिपिंग पते और शिपिंग के विकल्प पर निर्भर करती है.
पहले से मौजूद Android पेमेंट ऐप्लिकेशन में डेलिगेशन सहायता जोड़ने के लिए, यह तरीका अपनाएं:
- इस्तेमाल किए जा सकने वाले ऐक्सेस का एलान करें.
- पेमेंट के ज़रूरी विकल्पों के लिए,
PAY
इंटेंट अतिरिक्त पार्स करें. - पेमेंट के जवाब में ज़रूरी जानकारी दें.
- [ज़रूरी नहीं] डाइनैमिक फ़्लो के साथ काम करें:
इस्तेमाल किए जा सकने वाले ऐक्सेस का एलान करें
ब्राउज़र को अतिरिक्त जानकारी की उस सूची की जानकारी होनी चाहिए जो आपका पेमेंट ऐप्लिकेशन दे सकता है, ताकि वह इकट्ठा की गई जानकारी आपके ऐप्लिकेशन को दे सके. साथ काम करने वाले डेलिगेशन की जानकारी अपने ऐप्लिकेशन के 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, ऐसे ज़रूरी विकल्पों की सूची उपलब्ध कराएगा जो आपका ऐप्लिकेशन उपलब्ध करा सकता है.
इसके लिए, इन पैरामीटर को 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"
हो सकता है. आपका ऐप्लिकेशन, उपयोगकर्ता का पता या शिपिंग के विकल्पों को पूछते समय, अपने यूज़र इंटरफ़ेस (यूआई) में इस संकेत का इस्तेमाल कर सकता है.
shippingOptions
shippingOptions
, व्यापारी/कंपनी/कारोबारी के बताए गए शिपिंग विकल्पों का कलेक्शन है. इसे पार्स किया जा सकता है. यह पैरामीटर सिर्फ़ तब उपलब्ध होगा, जब paymentOptions.requestShipping ==
true
.
val shippingOptions: List<ShippingOption>? =
extras.getParcelableArray("shippingOptions")?.mapNotNull {
p -> from(p as Bundle)
}
शिपिंग का हर विकल्प एक Bundle
है. इसमें ये कुंजियां शामिल हैं.
id
- शिपिंग विकल्प का आइडेंटिफ़ायर.label
- उपयोगकर्ता को दिखाया जाने वाला शिपिंग विकल्प का लेबल.amount
- शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क का वह बंडल जिसमें स्ट्रिंग वैल्यू के साथcurrency
औरvalue
कुंजियां होती हैं.currency
, शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क की मुद्रा दिखाता है. यह ISO4217 फ़ॉर्मैट में तीन अक्षर वाले कोड के तौर पर होता है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
सही होने पर, यह स्ट्रिंग खाली नहीं होनी चाहिए.payerPhone
- पैसे चुकाने वाले का फ़ोन नंबर.paymentOptions.requestPayerPhone
सही होने पर, यह स्ट्रिंग खाली नहीं होनी चाहिए.payerEmail
- पैसे चुकाने वाले का ईमेल पता.paymentOptions.requestPayerEmail
सही होने पर, यह एक ऐसी स्ट्रिंग होनी चाहिए जो खाली न हो.shippingAddress
- उपयोगकर्ता का दिया गया शिपिंग पता.paymentOptions.requestShipping
के सही होने पर, यह खाली बंडल होना चाहिए. बंडल में नीचे दी गई कुंजियां होनी चाहिए, जो घर या ऑफ़िस के पते के अलग-अलग हिस्सों को दिखाती हों.city
countryCode
dependentLocality
organization
phone
postalCode
recipient
region
sortingCode
addressLine
addressLine
के अलावा, बाकी सभी कुंजियों में स्ट्रिंग की वैल्यू होती हैं.addressLine
, स्ट्रिंग का कलेक्शन होता है.
shippingOptionId
- उपयोगकर्ता के चुने गए शिपिंग विकल्प का आइडेंटिफ़ायर.paymentOptions.requestShipping
सही होने पर, यह स्ट्रिंग खाली नहीं होनी चाहिए.
पेमेंट के जवाब की पुष्टि करें
अगर शुरू किए गए पेमेंट ऐप्लिकेशन से मिले पेमेंट के जवाब की गतिविधि की वजह से,
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")
}
}
ज़रूरी नहीं: डाइनैमिक फ़्लो में मदद करें
कभी-कभी लेन-देन की कुल लागत बढ़ जाती है. जैसे, जब उपयोगकर्ता एक्सप्रेस शिपिंग का विकल्प चुनता है या जब उपयोगकर्ता अंतरराष्ट्रीय शिपिंग पता चुनता है, तो उपलब्ध शिपिंग विकल्पों की सूची या उनकी कीमतों में बदलाव होता है. जब आपका ऐप्लिकेशन उपयोगकर्ता का चुना हुआ शिपिंग पता या विकल्प उपलब्ध कराता है, तो यह व्यापारी को शिपिंग पते या विकल्प में होने वाले किसी भी बदलाव के बारे में व्यापारी को सूचना देने वाला होना चाहिए.
एआईडीएल
कारोबारी को नए बदलावों के बारे में सूचना देने के लिए, Chrome की AndroidManifest.xml में दी गई PaymentDetailsUpdateService
सेवा का इस्तेमाल करें. इस सेवा का इस्तेमाल करने के लिए, इस कॉन्टेंट वाली
दो एआईडीएल फ़ाइलें बनाएं:
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"
|
बीटा |
"com.chrome.beta"
|
डेव |
"com.chrome.dev"
|
कैनेरी |
"com.chrome.canary"
|
Chromium |
"org.chromium.chrome"
|
Google Quick Search Box (एक Weblayer एम्बेडर) |
"com.google.android.googlequicksearchbox"
|
changePaymentMethod
व्यापारी/कंपनी को उपयोगकर्ता के चुने गए पेमेंट के तरीके में हुए बदलावों के बारे में सूचना देता है. paymentHandlerMethodData
बंडल में methodName
और वैकल्पिक details
कुंजी, दोनों शामिल हैं. साथ ही, दोनों में स्ट्रिंग की वैल्यू भी हैं. Chrome एक ऐसे बंडल की जांच करेगा जो खाली न हो methodName
और अगर पुष्टि नहीं हो पाती है, तो updatePaymentDetails
को नीचे दिए गए गड़बड़ी के किसी एक मैसेज के साथ callback.updateWith
भेजेगा.
'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
- शिपिंग के विकल्पों का कलेक्शन, जिसे पार्स किया जा सकता हैerror
- सामान्य गड़बड़ी के मैसेज वाली स्ट्रिंग (उदाहरण के लिए, जबchangeShippingOption
, शिपिंग के विकल्प के लिए मान्य आइडेंटिफ़ायर नहीं देता)stringifiedPaymentMethodErrors
- पैसे चुकाने के तरीके से जुड़ी गड़बड़ियां दिखाने वाली JSON स्ट्रिंगaddressErrors
- वैकल्पिक कुंजियों वाला बंडल, जो शिपिंग के पते और स्ट्रिंग की वैल्यू से मेल खाता हो. हर कुंजी, शिपिंग पते के संबंधित हिस्से से जुड़ी पुष्टि की गड़बड़ी के बारे में बताती है.
कुंजी के न होने का मतलब है कि उसकी वैल्यू में बदलाव नहीं हुआ है.