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

البقاء على اطّلاع على كل جديد في دفعات الويب.

Eiji Kitamura

Danyao Wang

Rouslan Solomakhin

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

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

طريقة جديدة: 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، تم تنفيذها في الإصدار 74 من Chrome ولكن ليس في أي متصفّحات أخرى. تأكّد من توفّر الطريقة 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.

أصبحت الآن خدمة detailsPromise اختيارية في "PaymentRequest.show()".

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

أصبحت هذه الميزة متوفّرة في الإصدار 75 من Chrome و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 في Chrome 76، وقد نفّذ 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));
});

تطوير محلي محسَّن

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