أساسيات Google Pay API للويب

1. مقدمة

ما ستنشئه

عند الانتهاء من هذا الدرس التطبيقي حول الترميز، سيكون لديك موقع إلكتروني بسيط قابل للاستخدام مع عملية دمج Google Pay. يستردّ هذا المشروع رمزًا مميزًا للدفع يمكن إرساله إلى مقدّم خدمة الدفع لمعالجته.

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

كيفية تحميل Google Pay API وضبط إعداداته
كيفية عرض زر Google Pay والتعامل مع النقرات
كيفية طلب رمز مميّز للدفع من Google Pay

المتطلبات

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

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

2. إنشاء صفحة HTML

إنشاء ملفات المشروع

أنشِئ مجلدًا على جهاز الكمبيوتر باسم gpay-web-101، ثم أنشِئ داخل هذا المجلد ملفَين نصيَّين فارغَين باسم index.html وmain.js.يجب أن يبدو بنية الدليل على النحو التالي:
```
gpay-web-101/
  index.html
  main.js
```

افتح index.html في بيئة التطوير المتكاملة (IDE) التي تختارها وأضِف الرمز التالي:

<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Google Pay API for Web 101</title>
</head>

<body>
  <div id="gpay-container"></div>
  <p>Transaction info and errors will be logged to the console.</p>
  <script type="text/javascript" src="main.js"></script>
  <script
    async src="https://pay.google.com/gp/p/js/pay.js"
    onload="onGooglePayLoaded()">
  </script>
</body>

</html>

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

تتم إضافة DIV فارغ إلى الصفحة مع المعرّف gpay-container. سيكون عنصر DOM هذا هو العنصر الرئيسي الذي تتم فيه إضافة زر Google Pay. يمكنك وضع هذا العنصر في موضع مناسب في تخطيط موقعك الإلكتروني.
يتم وضع علامة النص البرمجي main.js في نموذج العناصر في المستند (DOM) بعد العنصر gpay-container. هذا الإجراء ضروري لضمان توفّر عنصر DIV الحاوي في نموذج كائن المستند (DOM) قبل أن يتم تنفيذ طلبات البحث عن main.js. بالإضافة إلى ذلك، يكون النص البرمجي متزامنًا لضمان تحميله قبل تحميل pay.js، لأنّه يجب أن تكون الطريقة onGooglePayLoaded() متوفّرة قبل اكتمال التحميل. هناك طرق أخرى لتحقيق التأثير نفسه، ولكن لن نتناولها هنا.
أخيرًا، يتم تحميل pay.js بشكل غير متزامن ويتم ضبط onGooglePayLoaded() كمعالج onload. سيتم تحديد هذه الطريقة في main.js.

3- ضبط إعدادات Google Pay

يتطلّب طلب الدفع في Google Pay عنصر طلب. يحتوي العنصر المحدّد هنا باسم baseGooglePayRequest على الحدّ الأدنى من الإعدادات المشتركة لجميع الطلبات. ستتم إضافة إعدادات أخرى حسب الطلب المقدَّم، وسنراجعها في هذا الدرس العملي.

أضِف ثوابت إعدادات Google Pay إلى ملف main.js الفارغ:

//=============================================================================
// Configuration
//=============================================================================

// The DOM element that the Google Pay button will be rendered into
const GPAY_BUTTON_CONTAINER_ID = 'gpay-container';

// Update the `merchantId` and `merchantName` properties with your own values.
// Your real info is required when the environment is `PRODUCTION`.
const merchantInfo = {
  merchantId: '12345678901234567890',
  merchantName: 'Example Merchant'
};

// This is the base configuration for all Google Pay payment data requests.
const baseGooglePayRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: 'CARD',
      parameters: {
        allowedAuthMethods: [
          "PAN_ONLY", "CRYPTOGRAM_3DS"
        ],
        allowedCardNetworks: [
          "AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"
        ]
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: {
          gateway: 'example',
          gatewayMerchantId: 'exampleGatewayMerchantId'
        }
      }
    }
  ],
  merchantInfo
};

// Prevent accidental edits to the base configuration. Mutations will be
// handled by cloning the config using deepCopy() and modifying the copy.
Object.freeze(baseGooglePayRequest);

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

اضبط المتغيّر الثابت GPAY_BUTTON_CONTAINER_ID على رقم تعريف عنصر DOM المستخدَم في صفحة HTML كحاوية رئيسية لزر Google Pay.
أنشئ عنصر الإعداد baseGooglePayRequest مع الإعدادات ذات الصلة لتطبيقك. يمكنك العثور على كل من المواقع والقيم في المستندات المرجعية. قد تتطابق القيم المعروضة في هذا المثال مع احتياجاتك أو لا تتطابق تمامًا، لذا يُرجى مراجعتها بعناية.
عدِّل السمتَين merchantId وmerchantName باستخدام القيم الخاصة بك. تكون هذه الحقول اختيارية عندما تكون البيئة TEST.

الموارد

مشاركة المدوّنة: هل تريد إتمام عملية الدفع بسلاسة أكبر باستخدام Google Pay؟ اضبط خيارات الدفع.
مرجع واجهة برمجة التطبيقات: مستندات عناصر الطلب في Google Pay API
مرجع واجهة برمجة التطبيقات: يُرجى الرجوع إلى PaymentMethod للحصول على مزيد من المعلومات حول طرق التفويض المسموح بها وشبكات البطاقات المسموح بها ومواصفات الترميز، بما في ذلك قيمة البوابة الصحيحة.

4. إضافة عميل الدفعات

يتم استخدام برنامج دفع لإرسال طلبات الدفع وتسجيل عمليات معاودة الاتصال. في هذا الدرس التطبيقي حول الترميز، سنقدّم طلبات دفع فقط. بالإضافة إلى ذلك، يمكنك ضبط PaymentDataCallbacks للتعامل مع الحالات التي تتغيّر فيها بيانات الدفع أو يتغيّر فيها إذن الدفع. ومع ذلك، لا يتم تناول هذه المواضيع المتقدّمة في هذا الدرس العملي.

أضِف رمز العميل هذا إلى أسفل main.js:

//=============================================================================
// Google Payments client singleton
//=============================================================================

let paymentsClient = null;

function getGooglePaymentsClient() {
  if (paymentsClient === null) {
    paymentsClient = new google.payments.api.PaymentsClient({
      environment: 'TEST',
      merchantInfo,
      // todo: paymentDataCallbacks (codelab pay-web-201)
    });
  }

  return paymentsClient;
}

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

سيحتوي المتغيّر paymentsClient على مثيل للعميل بعد إنشائه. لا يتم الوصول إلى المتغيّر مباشرةً من خلال الرمز البرمجي، بل يتم ذلك دائمًا من خلال طريقة getGooglePaymentsClient().
تتحقّق الطريقة getGooglePaymentsClient() مما إذا كان قد تم إنشاء مثيل لبرنامج العميل من قبل وتعرض هذا المثيل. إذا لم يتم إنشاء مثيل من قبل، يتم إنشاء مثيل وحفظه وإرجاعه. تضمن هذه الطريقة إنشاء مثيل واحد فقط واستخدامه طوال مدة تشغيل هذا النص البرمجي.
لإنشاء مثيل لعميل، يتم استدعاء الطريقة PaymentsClient(). في هذا المثال، نخبر العميل بأنّنا في بيئة TEST. البديل هو PRODUCTION. ومع ذلك، فإنّ TEST هو الإعداد التلقائي ويمكن حذفه.

5- إضافة مساعدين

يتم استخدام دوال المساعدة التالية لاحقًا في النص البرمجي، وقد تمت إضافتها لغرض وحيد هو تحسين إمكانية قراءة الرمز البرمجي وصيانته.

أضِف الدوال المساعِدة إلى أسفل main.js:

//=============================================================================
// Helpers
//=============================================================================

const deepCopy = (obj) => JSON.parse(JSON.stringify(obj));

function renderGooglePayButton() {
  const button = getGooglePaymentsClient().createButton({
    onClick: onGooglePaymentButtonClicked
  });

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

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

‫deepCopy() هي أداة مساعدة تستخدم التسلسل والتسلسل العكسي بتنسيق JSON لإنشاء نسخة طبق الأصل من العنصر المقدَّم. إنّها طريقة ملائمة لاستنساخ العناصر بدون القلق بشأن المراجع المشتركة.
‫renderGooglePayButton() هي أداة مساعدة تستدعي طريقة المكتبة createButton() لعرض زر Google Pay. المَعلمة التي تم تمريرها هي مجموعة من الخيارات التي تحدّد طريقة عمل الزر، مثل تسجيل الدالة onGooglePaymentButtonClicked() للتعامل مع النقرات على الزر.

6. إضافة معالِجات الأحداث

في هذا النص البرمجي، نضبط إعدادات معالجَي أحداث. يتم استدعاء الدالة الأولى عند انتهاء تحميل مكتبة pay.js، ويتم استدعاء الدالة الأخرى عند النقر على زر Google Pay.

أضِف معالِجات الأحداث إلى أسفل main.js:

//=============================================================================
// Event Handlers
//=============================================================================

function onGooglePayLoaded() {
  const req = deepCopy(baseGooglePayRequest);

  getGooglePaymentsClient()
    .isReadyToPay(req)
    .then(function(res) {
      if (res.result) {
        renderGooglePayButton();
      } else {
        console.log("Google Pay is not ready for this user.");
      }
    })
    .catch(console.error);
}

function onGooglePaymentButtonClicked() {
  // Create a new request data object for this request
  const req = {
    ...deepCopy(baseGooglePayRequest),
    transactionInfo: {
      countryCode: 'US',
      currencyCode: 'USD',
      totalPriceStatus: 'FINAL',
      totalPrice: (Math.random() * 999 + 1).toFixed(2),
    },
    // todo: callbackIntents (codelab gpay-web-201)
  };

  // Write request object to console for debugging
  console.log(req);

  getGooglePaymentsClient()
    .loadPaymentData(req)
    .then(function (res) {
      // Write response object to console for debugging
      console.log(res);
      // @todo pass payment token to your gateway to process payment
      // @note DO NOT save the payment credentials for future transactions
      paymentToken = res.paymentMethodData.tokenizationData.token;
    })
    .catch(console.error);
}

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

يتم استدعاء onGooglePayLoaded() عند اكتمال تحميل النص البرمجي pay.js على النحو المحدّد في ملف HTML. يتم استدعاء الطريقة isReadyToPay() لتحديد ما إذا كان سيتم عرض زر Google Pay أم لا. إذا كان المستهلك مستعدًا للدفع (أي أنّه أضاف طريقة دفع إلى "محفظة Google")، سيظهر زر Google Pay.
يتم استدعاء onGooglePaymentButtonClicked() عند النقر على زر Google Pay. يستدعي هذا الإجراء طريقة loadPaymentData() في المكتبة، والتي تُستخدَم لاسترداد رمز دفع. بعد الحصول على رمز الدفع المميّز، عليك إرساله إلى بوابة الدفع لمعالجة المعاملة. تصف السمة transactionInfo المعاملة التي يجب معالجتها عند النقر على هذا الزر.

7. الخاتمة

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

تشغيل المشروع

الاختبار باستخدام 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