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

1. מבוא

מה תפַתחו

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

מה תלמדו

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

הדרישות

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

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. הוספת לקוח תשלומים

לקוח תשלומים משמש לשליחת בקשות תשלום ולרישום של קריאות חוזרות (callback). ב-codelab הזה נבצע רק בקשות תשלום. בנוסף, אפשר להגדיר את PaymentDataCallbacks כך שיטפל במקרים שבהם פרטי התשלום או ההרשאה השתנו. עם זאת, הנושאים המתקדמים האלה לא נכללים ב-codelab הזה.

מוסיפים את קוד הלקוח הזה לתחתית של 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 יכיל את המופע של הלקוח אחרי שהוא ייווצר. הקוד שלנו לא ניגש למשתנה ישירות, אלא תמיד באמצעות ה-method‏ 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() שמשמשת לאחזור של טוקן תשלום. אחרי שיוצרים את אסימון התשלום, שולחים אותו לשער התשלומים כדי לעבד את העסקה. ‫transactionInfo מתאר את העסקה שאמורה לעבור עיבוד בלחיצה על הלחצן הזה.

7. סיכום

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

הרצת הפרויקט

בדיקה באמצעות 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.

לאן כדאי ללכת מכאן

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