‫Google Pay API בדפדפן – 101: יסודות

1. מבוא

מה תפַתחו

בסיום הקודלאב הזה, יהיה לכם אתר מינימלי שפועל עם שילוב של Google Pay. הפרויקט הזה מאחזר אסימון תשלום שעשוי להישלח לספק שירותי תשלומים לצורך עיבוד.

מה תלמדו

  • איך טוענים ומגדירים את Google Pay API
  • איך מציגים את הלחצן של Google Pay ומטפלים בקליקים
  • איך מבקשים אסימון תשלום מ-Google Pay

מה נדרש

  • עורך טקסט לבחירתכם לעריכת קובצי HTML ו-JavaScript.
  • דפדפן האינטרנט Google Chrome או דרך אחרת לבדוק אתר מקומי.
  • בסביבת הייצור, תצטרכו merchantId של Google Pay. ההרשמה במסוף של Google Pay ו-Wallet נמשכת רק דקה, אז כדאי לעשות את זה עכשיו.

איך עוקבים אחרי האירוע באמצעות Project IDX

פתיחת ה-codelab הזה ב-IDX

2. יצירת דף ה-HTML

יצירת קבצים בפרויקט

  1. יוצרים במחשב תיקייה בשם gpay-web-101 ובתוך התיקייה הזו יוצרים שני קובצי טקסט ריקים בשם index.html ו-main.js.מבנה הספרייה אמור להיראות כך:
    gpay-web-101/
  index.html
  main.js
  2. פותחים את 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>

הסבר על הקוד

  1. נוסף לדף DIV ריק עם המזהה gpay-container. רכיב ה-DOM הזה יהיה רכיב ההורה שאליו מתווסף הלחצן של Google Pay. אפשר למקם את הרכיב הזה בפריסת האתר במקום המתאים.
  2. תג הסקריפט main.js ממוקם ב-DOM אחרי הרכיב gpay-container. הפעולה הזו נחוצה כדי לוודא שה-DIV של הקונטיינר נמצא ב-DOM לפני שה-main.js מבצע שאילתות לגביו. בנוסף, הסקריפט הוא סינכרוני כדי לוודא שהוא נטען לפני טעינה של pay.js, כי שיטת onGooglePayLoaded() חייבת להתקיים לפני השלמת הטעינה. יש דרכים אחרות להשיג את אותו אפקט, אבל לא נדון בהן כאן.
  3. לבסוף, pay.js נטען באופן אסינכרוני ומגדיר את onGooglePayLoaded() כמתבצע של onload. השיטה הזו תוגדר ב-main.js.

3. הגדרת Google Pay

כדי לשלוח בקשת תשלום ב-Google Pay, צריך אובייקט בקשה. האובייקט שמוגדר כאן בתור baseGooglePayRequest מכיל את ההגדרות המשותפות המינימליות לכל הבקשות. בהתאם לבקשה, יתווספו הגדרות נוספות. נבדוק את ההגדרות האלה ב-codelab הזה.

מוסיפים את קבועי התצורה של 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);

הסבר על הקוד

  1. מגדירים את המשתנה הקבוע GPAY_BUTTON_CONTAINER_ID למזהה של אלמנט ה-DOM שמשמש בדף ה-HTML כמאגר האב של לחצן Google Pay.
  2. יוצרים את אובייקט התצורה baseGooglePayRequest עם ההגדרות הרלוונטיות לאפליקציה. כל המאפיינים והערכים מפורטים במסמכי העזר. הערכים שמוצגים בדוגמה הזו עשויים להתאים לצרכים שלכם או לא, לכן חשוב לבדוק אותם היטב.
  3. מעדכנים את המאפיינים merchantId ו-merchantName בערכים משלכם. השדות האלה הם אופציונליים כשהסביבה היא TEST.

משאבים

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

הסבר על הקוד

  1. המשתנה paymentsClient יחזיק את המופע של הלקוח אחרי שהוא נוצר. הקוד שלנו לא ניגש למשתנה ישירות, אלא תמיד באמצעות השיטה getGooglePaymentsClient().
  2. השיטה getGooglePaymentsClient() בודקת אם כבר נוצר מופע של לקוח ומחזירה את המופע הזה. אם לא נוצרה מופע קודם, הוא נוצר, נשמר ומוחזר. השיטה הזו מבטיחה שייווצר רק מופע אחד, שבו נעשה שימוש במהלך כל חיי הסקריפט.
  3. כדי ליצור מופע של לקוח, מפעילים את השיטה 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);
}

הסבר על הקוד

  1. deepCopy() היא תוכנית שירות שמשתמשת בסריאליזציה ובדה-סריאליזציה של JSON כדי ליצור עותק מעמיק של האובייקט שסופק. זוהי דרך נוחה לשכפל אובייקטים בלי לדאוג לגבי הפניות משותפות.
  2. 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);
}

הסבר על הקוד

  1. הפונקציה onGooglePayLoaded() מופעלת כשהסקריפט pay.js מסיים את הטעינה, כפי שהוגדר בקובץ ה-HTML. השיטה isReadyToPay() מופעלת כדי לקבוע אם להציג את הלחצן של Google Pay או לא. אם הצרכן מוכן לשלם (כלומר הוסיף אמצעי תשלום ל-Google Wallet), המערכת תיצור את הלחצן של Google Pay.
  2. הפונקציה onGooglePaymentButtonClicked() מופעלת כשלוחצים על לחצן Google Pay. השיטה הזו מפעילה את שיטת הספרייה loadPaymentData(), שמשמשת לאחזור אסימון תשלום. לאחר קבלת אסימון התשלום, שולחים אותו ל-Payment Gateway לצורך עיבוד העסקה. השדה transactionInfo מתאר את העסקה שצריך לעבד בלחיצה על הלחצן הזה.

7. סיכום

כל הכבוד על השלמת ה-Codelab הזה! למדתם איך לשלב את Google Pay API באתר.

הרצת הפרויקט

בדיקה באמצעות Google Chrome

פותחים את index.html בדפדפן האינטרנט Google Chrome באמצעות קובץ > פתיחת קובץ… בתפריט הראשי של 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.

מה עושים עכשיו

מקורות מידע נוספים