‫Google Pay للويب 201: ميزات متقدّمة

1. مقدمة

هذا الدرس التطبيقي حول الترميز هو تكملة لدرس Google Pay API for Web 101: Basics (الجزء الأول من أساسيات Google Pay API للويب) ويعتمد على الرموز البرمجية المكتوبة في ذلك الدرس. لإكمال هذا الدليل التعليمي حول رموز البرامج، احرص على إكمال هذا الدليل أولاً.

المُعطيات

• كيفية تخصيص زر Google Pay
• كيفية بدء عملية الدفع
• كيفية الردّ على رسالة حالة تحصيل الرسوم
• كيفية التعامل مع تغييرات عنوان الشحن
• كيفية التعامل مع رموز تحصيل القيمة

المتطلبات

• محرِّر نصوص من اختيارك لتعديل ملفات HTML وJavaScript
• متصفّح الويب Google Chrome أو طريقة أخرى لاختبار موقع إلكتروني على الجهاز
• لاستخدام التطبيق في قناة الإصدار العلني، ستحتاج إلى merchantId في Google Pay. يستغرق التسجيل في Google Pay & Wallet Console دقيقة واحدة فقط، لذا ننصحك بإجراء ذلك الآن.

المتابعة باستخدام Project IDX

2. تخصيص الأزرار

في ما يلي نظرة عامة موجزة على ButtonOptions. يمكنك الرجوع إلى المستندات للحصول على شرح أكثر تفصيلاً.

الخيار	الضرورة	القيم
onClick	مطلوب	اسم معالِج أحداث JavaScript
allowedPaymentMethods	اختياريّ	PaymentMethod[]
buttonColor	اختياريّ	التلقائي، أسود، أبيض
buttonLocale	اختياريّ	رمز ISO 639-1 المكوّن من حرفَين تشمل اللغات المتوافقة الإنجليزية والعربية والأرمنية والبلغارية والكندية والتشيكية والدانمركية والألمانية واليونانية والإسبانية والإستونية والفنلندية والفرنسية والكرواتية والإندونيسية والإيطالية واليابانية والكورية والملايوية والهولندية والنرويجية والبولندية والبرتغالية والروسية والسلوفاكية والسلوفينية والصربية والسويدية والتايلاندية والتركية والبرتغالية والمملكة المتحدة والصينية.
buttonRadius	اختياريّ	من 0 إلى 100
buttonRootNode	اختياريّ	HTMLDocument أو ShadowRoot
buttonSizeMode	اختياريّ	ثابت، تعبئة
buttonType	اختياريّ	حجز، شراء، دفع، تبرع، طلب، دفع، عادي، اشتراك

ابحث عن طريقة renderGooglePayButton() في ملف main.js واستبدِلها بالرمز المدرَج هنا.

function renderGooglePayButton() {
  const button = getGooglePaymentsClient().createButton({
    buttonColor: 'default',
    buttonType: 'buy',
    buttonRadius: 4,
    buttonLocale: 'en',
    onClick: onGooglePaymentButtonClicked,
    allowedPaymentMethods: baseGooglePayRequest.allowedPaymentMethods,
  });

  document.getElementById(GPAY_BUTTON_CONTAINER_ID).appendChild(button);
}

شرح الرمز

1. تأخذ طريقة مكتبة createButton() مَعلمة إعداد ButtonOptions تتيح لك تحديد الشكل والسلوك المطلوبَين للزر.

3- عمليات استدعاء بيانات الدفع

يقدّم عملاء الدفعات آلية لك لتسجيل الدوالّ التي تريد التعامل معها عند حدوث أحداث معيّنة. الأول هو تحصيل الرسوم المؤقتة من حسابك والثاني هو تغيير بيانات الدفع.

1. ابحث عن التعليق // todo: paymentDataCallbacks في main.js واستبدِله بهذا الرمز.

   paymentDataCallbacks: {
     onPaymentAuthorized: onPaymentAuthorized,
     onPaymentDataChanged: onPaymentDataChanged
   },
   

2. بعد ذلك، ابحث عن قسم Event Handlers في main.js وألصِق الرمز التالي في نهاية القسم.

   function onPaymentAuthorized(paymentData) {
     // We'll fill this in later
   }
   
   function onPaymentDataChanged(intermediatePaymentData) {
     // We'll fill this in later
   }
   
   

3. أخيرًا، ابحث عن التعليق // todo: callbackIntents ضمن main.js واستبدِل التعليق بهذا الرمز. في هذا الدليل التعليمي حول الرموز البرمجية، سننفّذ جميع النوايا الأربع.

   callbackIntents: [
     'PAYMENT_AUTHORIZATION',
     'SHIPPING_ADDRESS',
     'SHIPPING_OPTION',
     'OFFER',
   ],
   shippingAddressRequired: true,
   shippingOptionRequired: true,
   shippingOptionParameters: {
     defaultSelectedOptionId: 'shipping-001',
     shippingOptions: [
       {
         id: 'shipping-001',
         label: '$0.00: Free shipping',
         description: 'Free Shipping delivered in 5 business days.'
       },
       {
         id: 'shipping-002',
         label: '$1.99: Standard shipping',
         description: 'Standard shipping delivered in 3 business days.'
       },
       {
         id: 'shipping-003',
         label: '$1000: Express shipping',
         description: 'Express shipping delivered in 1 business day.'
       },
     ],
   },
   

شرح الرمز

1. يحتوي الموقع PaymentDataCallbacks على موقعَين فرعيَّين، أحدهما لطلب إعادة الاتصال بشأن تفويض الدفع والثاني لطلب إعادة الاتصال بشأن تغيير بيانات الدفع.
2. في حال تنفيذ عمليات الاستدعاء، يكون العنصر onPaymentAuthorized مطلوبًا. يتمّ استدعاء دالة ردّ الاتصال هذه عندما تحتوي قائمة callbackIntents على PAYMENT_AUTHORIZATION في PaymentDataRequest.
3. ويكون onPaymentDataChanged اختياريًا. يتمّ استدعاء هذا المرجع الداعم عندما تحتوي قائمة callbackIntents على OFFER أو SHIPPING_ADDRESS أو SHIPPING_OPTION في PaymentDataRequest.
4. اضبط callbackIntents في PaymentDataRequest لتشغيل كلتا الدالتَين المرجعيتَين لهذا الدليل التعليمي.

4. تفويض الدفع

تُستخدَم ميزة "تفويض الدفعات" لبدء عملية الدفع والموافقة على حالة تفويض الدفع.

ابحث عن الدالة onPaymentAuthorized() في main.js التي أضفتها في الخطوة الأخيرة واستبدِلها بالرمز البرمجي التالي.

function onPaymentAuthorized(paymentData) {
  return new Promise(function(resolve, reject) {
    // Write the data to console for debugging
    console.log("onPaymentAuthorized", paymentData);

    // Do something here to pass token to your gateway

    // To simulate the payment processing, there is a 70% chance of success
    const paymentAuthorizationResult = (Math.random() > 0.3)
      ? {transactionState: 'SUCCESS'}
      : {
        transactionState: 'ERROR',
        error: {
          intent: 'PAYMENT_AUTHORIZATION',
          message: 'Insufficient funds',
          reason: 'PAYMENT_DATA_INVALID'
        }
      };

    resolve(paymentAuthorizationResult);
  });
}

شرح الرمز

1. يتم استدعاء دالة ردّ الاتصال onPaymentAuthorized() باستخدام وسيطة PaymentData ويجب أن تعرض عملية غير مكتملة. في هذا المثال، تختار الدالة عشوائيًا ما إذا كانت ستُعرِض رسالة نجاح أو خطأ. في مشروعك، ستستخدم هذه الفرصة لمعالجة المعاملة من خلال بوابتك باستخدام الرمز المميّز المتوفّر في paymentData في paymentData.paymentMethodData.tokenizationData.token.

5- تغيير بيانات الدفع

تتيح ميزة "تعديلات الأسعار الديناميكية" للتاجر تعديل خيارات الشحن ومعلومات المعاملات ديناميكيًا استنادًا إلى عنوان شحن محدّد. بالإضافة إلى ذلك، يمكنك تعديل معلومات المعاملات ديناميكيًا استنادًا إلى خيار الشحن الذي تم اختياره.

ابحث عن الدالة onPaymentDataChanged() في main.js التي أضفتها في الخطوة الأخيرة واستبدِلها بالرمز البرمجي التالي.

function onPaymentDataChanged(intermediatePaymentData) {
  return new Promise(function(resolve, reject) {
    let paymentDataRequestUpdate = {};

    // Write the data to console for debugging
    console.log("onPaymentDataChanged", intermediatePaymentData);

    switch(intermediatePaymentData.callbackTrigger)
    {
      case "INITIALIZE":
        // Handle initialize
        break;
      case "SHIPPING_ADDRESS":
        // Read intermediatePaymentData.transactionInfo
        // Read intermediatePaymentData.shippingAddress
        // Update paymentDataRequestUpdate.newTransactionInfo
        break;
      case "SHIPPING_OPTION":
        // Read intermediatePaymentData.transactionInfo
        // Read intermediatePaymentData.shippingOptionData
        // Update paymentDataRequestUpdate.newTransactionInfo
        // Update paymentDataRequestUpdate.newShippingOptionParameters
        break;
      case "OFFER":
        // Read intermediatePaymentData.offerData
        // Read intermediatePaymentData.transactionInfo
        // Update paymentDataRequestUpdate.newTransactionInfo
        // Update paymentDataRequestUpdate.newOfferInfo
        break;
      default:
        // Update paymentDataRequestUpdate.error
    }

    resolve(paymentDataRequestUpdate);
  });
}

قد يتم تشغيل دالة INITIALIZE لطلب معاودة الاتصال عدة مرات خلال مكالمة واحدة إلى loadPaymentData()، لذا عليك التأكّد من أنّه يمكنك معالجة مكالمات متعددة إليها. على سبيل المثال، عندما يغيّر المستخدم الحساب، يتم استدعاء onPaymentDataChanged() باستخدام INITIALIZE مرة أخرى مع البيانات من الحساب الجديد.

شرح الرمز

1. تستخدِم الدالة onPaymentDataChanged() الوسيطة IntermediatePaymentData. يتمّ استدعاء هذه الدالة عند تغيير عنوان الشحن أو خيارات الشحن في ورقة الدفع.
2. يجب أن تُرجع الدالة onPaymentDataChanged() وعدًا يحلّ عنصر PaymentDataRequestUpdate الذي يحدّد معلومات المعاملات الجديدة وخيارات الشحن والأخطاء لتعديل جدول الدفع.
3. redemptionCodes هي مجموعة من الرموز الترويجية التي يتم إدخالها في جدول الدفع. يشمل الرموز التي تمت الموافقة عليها من قبل.

6- الخاتمة

تهانينا على إكمال هذا الدرس التطبيقي حول الترميز. لقد تعلمت كيفية ...

تنفيذ المشروع

الاختبار باستخدام Google Chrome

باستخدام متصفّح الويب Google Chrome، افتح index.html باستخدام ملف > فتح ملف... من القائمة الرئيسية في Chrome. سينفِّذ Chrome main.js عند فتح المشروع بهذه الطريقة. قد لا تسمح متصفّحات الويب الأخرى بتنفيذ JavaScript.

– أو –

الاختبار باستخدام خادم ويب محلي

إذا كان لديك Python مثبَّتًا، يمكنك تشغيل python3 -m http.server من طلب سطر الأوامر في المجلد الجذر pay-web-101.

$ cd /your/path/to/pay-web-101
$ python3 -m http.server
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

بعد ذلك، يُرجى الانتقال إلى موقعك الإلكتروني على الرابط http://localhost:8000.

الخطوة التالية

• مراجعة قائمة التحقّق من الدمج

مراجع إضافية

• الانضمام إلى المحادثة في قناة#payments على Discord
• متابعة ‎@GooglePayDevs على X
• مشاهدة فيديوهات ذات صلة بخدمة Google Pay على YouTube