تعديلات على واجهات برمجة تطبيقات Web Payments

اطّلِع على آخر المعلومات حول "الدفعات على الويب".

Eiji Kitamura

Danyao Wang

Rouslan Solomakhin

أصبحت ميزة "الدفعات على الويب" متاحة للجميع في المتصفّحات منذ عام 2016. تتوفّر الآن الميزة الأساسية Payment Request API على متصفّحات متعدّدة: Chrome وSafari وEdge وستتوفّر قريبًا على Firefox. إذا كنت حديث العهد بميزة "الدفعات على الويب"، يمكنك الاطّلاع على "نظرة عامة على الدفع على الويب" لبدء استخدام هذه الميزة.

منذ إطلاق واجهة برمجة تطبيقات طلب الدفع وواجهة برمجة التطبيقات لمعالج الدفع، تم إجراء بعض التغييرات على مواصفات كل منهما. لن تؤدي هذه التغييرات إلى تعطُّل التعليمة البرمجية العاملة، لكننا نوصي بالبحث عنها. تلخّص هذه المشاركة هذه التعديلات وستستمر في تجميع تغييرات واجهات برمجة التطبيقات هذه.

الطريقة الجديدة: hasEnrolledInstrument()

في الإصدار السابق من Payment Request API، تم استخدام canMakePayment() للتحقّق من توفُّر وسيلة الدفع للمستخدم. في تعديل قيد الإصدار مؤخرًا على المواصفات، تم استبدال canMakePayment() بعلامة hasEnrolledInstrument() بدون تغيير وظيفتها.

تستخدم الطريقة hasEnrolledInstrument() إجماع من جميع المتصفّحات الرئيسية. نفَّذ Chrome هذه الطريقة في الإصدار 74، وWebkit وGecko يتضمّنان أخطاء تتعلّق بالتنقّل، ولكنهما لم نفِّذَا الطريقة حتى حزيران (يونيو) 2019.

لاستخدام طريقة hasEnrolledInstrument() الجديدة، استبدِل الرمز الذي يبدو على النحو التالي:

// Checking for instrument presence.
request.canMakePayment().then(handleInstrumentPresence).catch(handleError);

باستخدام رمز يبدو على النحو التالي:

// Checking for instrument presence.
if (request.hasEnrolledInstrument) {
  // hasEnrolledInstrument() is available.
  request.hasEnrolledInstrument().then(handleInstrumentPresence).catch(handleError);
} else {
  request.canMakePayment().then(handleInstrumentPresence).catch(handleError);
}

لم يعُد canMakePayment() يتحقّق من توفّر الأداة.

بما أنّ hasEnrolledInstrument() يتولّى الآن التحقّق من أدوات الدفع الخاصة بالمستخدم، canMakePayment() تم تعديله للتحقّق فقط من توفّر تطبيق الدفع.

يرتبط هذا التغيير في canMakePayment() بتنفيذ hasEnrolledInstrument(). واعتبارًا من حزيران (يونيو) 2019، تم تنفيذه في Chrome 74 ولكن ليس في أي متصفِّحات أخرى. تأكَّد مما إذا كانت الطريقة hasEnrolledInstrument() متاحة في متصفّح المستخدم قبل محاولة استخدامها.

// Checking for payment app availability without checking for instrument presence.
if (request.hasEnrolledInstrument) {
  // `canMakePayment()` behavior change corresponds to
  // `hasEnrolledInstrument()` availability.
  request.canMakePayment().then(handlePaymentAppAvailable).catch(handleError);
} else {
  console.log("Cannot check for payment app availability without checking for instrument presence.");
}

تمّت إزالة languageCode من طريقة الدفع basic-card

تمت إزالة PaymentAddress.languageCode من عناوين الشحن وعناوين إرسال الفواتير في basic-card. لن تتأثر عناوين إرسال الفواتير الخاصة بطرق الدفع الأخرى (مثل Google Pay)

تم تنفيذ هذا التغيير في الإصدار 74 من Chrome وFirefox وSafari.

يقبل PaymentRequest.show() الآن detailsPromise اختياريًا.

يسمح PaymentRequest.show() للتاجر بعرض واجهة مستخدم لطلب الدفع قبل معرفة المبلغ الإجمالي النهائي. أمام التاجر عشر ثوانٍ لحلّ detailsPromise قبل انتهاء مهلة الانتظار. هذه الميزة مخصّصة لإجراء جولة سريعة من جانب الخادم.

تم شحن هذه الميزة في Chrome 75 وSafari.

// Not implemented in Chrome 74 and older.
// There's no way to feature-detect this, so check a few
// older versions of Chrome that you're seeing hit your servers.
if (/Chrome\/((6[0-9])|(7[0-4]))/g.exec(navigator.userAgent) !== null) {
  return;
}

// Supported in Chrome 75+.
request.show(new Promise(function(resolveDetailsPromise, rejectDetailsPromise) {
  // Find out the exact total amount and call
  // `resolveDetailsPromise(details)`.
  // Use a 3 second timeout as an example.
  window.setTimeout(function() {
    resolveDetailsPromise(details);
  }, 3000); // 3 seconds.
}))
.then(handleResponse)
.catch(handleError);

PaymentRequestEvent.changePaymentMethod()

تتيح ميزة Payment Handler API PaymentRequestEvent.changePaymentMethod() لمعالِجات الدفع (مثل Google Pay) لتشغيل معالج الحدث onpaymentmethodchange. يقدّم changePaymentMethod() وعدًا يتم ربطه بردّ التاجر مع تعديل معلومات الأسعار (على سبيل المثال، إعادة احتساب الضرائب).

يتوفّر كلّ من حدثَي PaymentRequestEvent.changePaymentMethod() وpaymentmethodchange في الإصدار 76 من Chrome، وقد نفّذ Webkit حدث paymentmethodchange في ميزة معاينة التكنولوجيا.

// In service worker context, `self` is the global object.
self.addEventListener('paymentrequest', (evt) => {
  evt.respondWith(new Promise((confirmPaymentFunction, rejectPaymentFunction) => {
    if (evt.changePaymentMethod === undefined) {
      // Not implemented in this version of Chrome.
      return;
    }
    // Notify merchant that the user selected a different payment method.
    evt.changePaymentMethod('https://paymentapp.com', {country: 'US'})
    .then((responseFromMerchant) => {
      if (responseFromMerchant === null) {
        // Merchant ignored the 'paymentmethodchange' event.
        return;
      }
      handleResponseFromMerchant(responseFromMerchant);
    })
    .catch((error) => {
      handleError(error);
    });
  }));
});

مثال من التاجر:

if (request.onpaymentmethodchange === undefined) {
  // Feature not available in this browser.
  return;
}

request.addEventListener('paymentmethodchange', (evt) => {
  evt.updateWith(updateDetailsBasedOnPaymentMethod(evt, paymentDetails));
});

تحسين التطوير المحلي

يضيف الإصدار 76 من Chrome تحسينَين صغيرَين لزيادة إنتاجية المطوّرين. إذا كانت بيئة التطوير المحلية تستخدم شهادة موقَّعة ذاتيًا، يمكنك الآن استخدام الخيار --ignore-certificate-errors في سطر الأوامر للسماح لمتصفّح Chrome باستخدام واجهات برمجة التطبيقات Web Payments في بيئة التطوير. إذا كنت تُطوّر باستخدام خادم ويب محلي لا يتيح استخدام بروتوكول HTTPS، يمكنك أيضًا استخدام العلامة --unsafely-treat-insecure-origin-as-secure=<origin> لجعل Chrome يتعامل مع مصدر HTTP على أنّه HTTPS.