‫Google Pay API للويب 201: المستوى المتقدّم

1. مقدمة

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

أهداف الدورة التعليمية

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

المتطلبات

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

اتّباع الخطوات باستخدام Firebase Studio

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);
}

شرح الرمز البرمجي

تتلقّى طريقة المكتبة createButton() وسيطة إعداد ButtonOptions تتيح لك تحديد طريقة ظهور الزر وسلوكه.

3- عمليات معاودة الاتصال المتعلقة ببيانات الدفع

يوفّر لك برنامج الدفع آلية لتسجيل وظائف يتم تنفيذها عند وقوع أحداث معيّنة. الأول هو تفويض الدفع والثاني هو تغيير بيانات الدفع.

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

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

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

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

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

أخيرًا، ابحث عن التعليق // 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.'
    },
  ],
},

شرح الرمز البرمجي

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

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

يُستخدَم الأمر Authorize Payments لبدء عملية الدفع والاعتراف بحالة تفويض الدفع.

ابحث عن الدالة 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);
  });
}

شرح الرمز البرمجي

يتم استدعاء دالة رد الاتصال 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);
  });
}

شرح الرمز البرمجي

تستخدِم الدالة onPaymentDataChanged() IntermediatePaymentData كوسيطة. يتم استدعاء هذه الدالة عند تغيير عنوان الشحن أو خيارات الشحن في صفحة الدفع.
يجب أن تعرض الدالة onPaymentDataChanged() وعدًا يحلّ عنصر PaymentDataRequestUpdate الذي يحدّد معلومات المعاملة الجديدة وخيارات الشحن والخطأ لتعديل ورقة الدفع.
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