יצירת כרטיסים באינטרנט באמצעות Google Wallet API

יצירת כרטיסים באינטרנט באמצעות Google Wallet API

מידע על Codelab זה

subjectהעדכון האחרון: ינו׳ 19, 2023
account_circleנכתב על ידי Nick Alteen

1.‏ מבוא

באמצעות Google Wallet API תוכלו ליצור אינטראקציה עם המשתמשים באמצעות סוגי כרטיסים שונים: כרטיסי מועדון לקוחות, מבצעים, כרטיסי מתנה, כרטיסים לאירועים, כרטיסים לתחבורה ציבורית, כרטיסי עלייה למטוס ועוד. כל סוג כרטיס או סוג כרטיס מגיע עם שדות ותכונות ספציפיים לתרחישי שימוש, כדי לשפר את חוויית המשתמש.

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

  • כרטיסי חניה
  • כרטיסי חברות בספרייה
  • שוברים עם ערך שמור
  • כרטיסי מינוי למכון כושר
  • הזמנות

אפשר להשתמש בכרטיסים כלליים בכל תרחיש לדוגמה שאפשר להציג באמצעות:

  • עד שלוש שורות של מידע
  • (אופציונלי) גרפיקה של ברקוד
  • (אופציונלי) קטע פרטים

דוגמה לכרטיס ב-Google Wallet לכנס

מידע נוסף על Google Wallet API או על הוספת הלחצן הוספה ל-Google Wallet לדף אינטרנט זמין במסמכי התיעוד למפתחים של Google Wallet.

העברה של כיתות ואובייקטים

Google Wallet API חושף שיטות ליצירה של הפריטים הבאים:

סוג

תיאור

סוג הכרטיס

תבנית לאובייקט כרטיס ספציפי. הוא מכיל מידע שמשותף לכל אובייקטי הכרטיס ששייכים לכיתה הזו.

העברת אובייקט

מופע של סוג כרטיס ייחודי למזהה משתמש.

מידע על Codelab זה

ב-codelab הזה תלמדו לבצע את המשימות הבאות.

  1. יצירת חשבון מנפיק חדש במצב הדגמה
  2. יצירת חשבון שירות להנפקת כרטיסים
  3. יצירת כיתה חדשה של כרטיס גנרי
  4. יצירת אובייקט כרטיס חדש
  5. יצירת לחצן הוספה ל-Google Wallet לשמירת כרטיס
  6. הצגת הלחצן בדף האינטרנט
  7. טיפול בתוצאה של שמירת הכרטיס

דרישות מוקדמות

מטרות

בסיום הקודלאב הזה, תוכלו:

  • יצירת אובייקטים של כרטיסים באמצעות Google Wallet
  • יצירת לחצן הוספה ל-Google Wallet

תמיכה

אם אתם נתקעים בשלב כלשהו בקודלאב, תוכלו להיעזר בפתרון המלא במאגר GitHub‏ google-pay/wallet-web-codelab.

2.‏ הגדרה

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

הרשמה לחשבון מנפיק ב-Google Wallet

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

מידע נוסף על מצב הדגמה זמין בקטע דרישות מוקדמות כלליות לקבלת אישור.

  1. פותחים את מסוף Google Pay ו-Wallet.
  2. פועלים לפי ההוראות במסך כדי ליצור חשבון מנפיק.
  3. בוחרים באפשרות Google Wallet API.
  4. מאשרים שהבנתם את התנאים וההגבלות ואת מדיניות הפרטיות
  5. מעתיקים את הערך של Issuer ID (מזהה המנפיק) לעורך טקסט או למיקום אחר
  6. בכרטיסייה ניהול, בוחרים באפשרות הגדרת חשבונות בדיקה.
  7. מוסיפים את כתובות האימייל שבהן תשתמשו ב-codelab הזה

הפעלת Google Wallet API

  1. נכנסים למסוף Google Cloud.
  2. אם עדיין אין לכם פרויקט ב-Google Cloud, אתם יכולים ליצור פרויקט עכשיו (מידע נוסף זמין במאמר יצירה וניהול של פרויקטים).
  3. מפעילים את Google Wallet API (נקרא גם Google Pay for Passes API) בפרויקט

יצירת חשבון שירות ומפתח

כדי לקרוא ל-Google Wallet API, צריך חשבון שירות ומפתח של חשבון שירות. חשבון השירות הוא הזהות שמפעילה את Google Wallet API. המפתח של חשבון השירות מכיל מפתח פרטי שמזהה את האפליקציה כחשבון השירות. המפתח הזה רגיש, לכן חשוב לשמור על סודיות.

יצירה של חשבון שירות

  1. במסוף Google Cloud, פותחים את Service Accounts.
  2. נותנים שם, מזהה ותיאור לחשבון השירות
  3. בוחרים באפשרות יצירה והמשך.
  4. לוחצים על סיום.

יצירת מפתח של חשבון שירות

  1. בחירת חשבון השירות
  2. בוחרים בתפריט KEYS.
  3. בוחרים באפשרות ADD KEY ואז באפשרות Create new key.
  4. בוחרים את סוג המפתח JSON.
  5. בוחרים באפשרות יצירה.

תופיע בקשה לשמור את קובץ המפתח בתחנת העבודה המקומית. חשוב לזכור את המיקום שלו.

הגדרת משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS

ערכות ה-SDK של Google משתמשות במשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS כדי לבצע אימות כחשבון שירות ולגשת לממשקי API שונים של פרויקט ב-Google Cloud.

  1. פועלים לפי ההוראות שמפורטות במסמכי העזרה בנושא מפתחות של חשבונות שירות ב-Google Cloud כדי להגדיר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS.
  2. מוודאים שמשתנה הסביבה מוגדר בסשן חדש של מסוף (MacOS/‏Linux) או של שורת הפקודה (Windows) (יכול להיות שתצטרכו להתחיל סשן חדש אם כבר יש לכם סשן פתוח)
    echo $GOOGLE_APPLICATION_CREDENTIALS

מתן הרשאה לחשבון השירות

לבסוף, תצטרכו להעניק לחשבון השירות הרשאה לנהל כרטיסים ב-Google Wallet.

  1. פותחים את מסוף Google Pay ו-Wallet.
  2. בוחרים באפשרות משתמשים.
  3. בוחרים באפשרות הזמנת משתמש.
  4. מזינים את כתובת האימייל של חשבון השירות (למשל test-svc@myproject.iam.gserviceaccount.com)
  5. בתפריט הנפתח רמת גישה, בוחרים באפשרות מפתח או אדמין.
  6. בוחרים באפשרות הזמנה.

3.‏ הפעלת אפליקציית Node.js לדוגמה

משך 10:00

בשלב הזה תפעילו אפליקציית Node.js לדוגמה שתופעל בתור אתר שופינג ושרת לקצה העורפי.

שכפול המאגר לדוגמה

המאגר google-pay/wallet-web-codelab מכיל פרויקט לדוגמה שמבוסס על Node.js וקובצי סקריפט שונים שמחקים שרת לקצה העורפי המשמש לניהול הקצאות של כיתות וכלי תשלום. תצטרכו לערוך את הדפים האלה כך שיכללו את הלחצן הוספה ל-Google Wallet במסך פרטי המוצר.

  1. שכפול המאגר לתחנת העבודה המקומית
    git clone https://github.com/google-pay/wallet-web-codelab.git

התקנת יחסי התלות של הפרויקט

  1. פותחים את המאגר המשובט במסוף או בשורת הפקודה
  2. עוברים לספרייה web (זוהי האפליקציה שתשנו בשאר הקודלאב הזה)
    cd web
  3. התקנה של יחסי התלות של Node.js
    npm install .
  4. הפעלת האפליקציה
    node app.js
  5. פותחים את האפליקציה שפועלת בכתובת http://localhost:3000

דוגמה לאפליקציית אינטרנט עם שדה להזנת כתובת אימייל וכפתור 'יצירת כרטיס'

אם מזינים את כתובת האימייל ובוחרים באפשרות Create pass (יצירת כרטיס), לא קורה כלום. בשלבים הבאים תגדירו את האפליקציה כך שתוכל ליצור אובייקט וסוג כרטיס חדשים.

4.‏ יצירת כיתה של כרטיס גנרי

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

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

אפשר ליצור סוגים של כרטיסים ישירות במסוף Google Pay ו-Wallet או באמצעות Google Wallet API. בסדנת הקוד הזו תלמדו ליצור את הכיתה Generic pass באמצעות ה-API. התהליך הזה תואם לתהליך שבו שרת פרטי לקצה העורפי משתמש כדי ליצור סוגים של כרטיסים.

  1. פתיחת הקובץ web/app.js
  2. מחליפים את הערך של issuerId במזהה המנפיק מהמסוף של Google Pay ו-Wallet.
    // TODO: Define Issuer ID
    const issuerId = 'ISSUER_ID';
  3. מאתרים את הפונקציה createPassClass
  4. בפונקציה, יוצרים לקוח HTTP מאומת ומשתמשים ב-Google Wallet API כדי ליצור סוג כרטיס חדש
    // TODO: Create a Generic pass class
    let genericClass = {
      'id': `${classId}`,
      'classTemplateInfo': {
        'cardTemplateOverride': {
          'cardRowTemplateInfos': [
            {
              'twoItems': {
                'startItem': {
                  'firstValue': {
                    'fields': [
                      {
                        'fieldPath': 'object.textModulesData["points"]'
                      }
                    ]
                  }
                },
                'endItem': {
                  'firstValue': {
                    'fields': [
                      {
                        'fieldPath': 'object.textModulesData["contacts"]'
                      }
                    ]
                  }
                }
              }
            }
          ]
        },
        'detailsTemplateOverride': {
          'detailsItemInfos': [
            {
              'item': {
                'firstValue': {
                  'fields': [
                    {
                      'fieldPath': 'class.imageModulesData["event_banner"]'
                    }
                  ]
                }
              }
            },
            {
              'item': {
                'firstValue': {
                  'fields': [
                    {
                      'fieldPath': 'class.textModulesData["game_overview"]'
                    }
                  ]
                }
              }
            },
            {
              'item': {
                'firstValue': {
                  'fields': [
                    {
                      'fieldPath': 'class.linksModuleData.uris["official_site"]'
                    }
                  ]
                }
              }
            }
          ]
        }
      },
      'imageModulesData': [
        {
          'mainImage': {
            'sourceUri': {
              'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
            },
            'contentDescription': {
              'defaultValue': {
                'language': 'en-US',
                'value': 'Google I/O 2022 Banner'
              }
            }
          },
          'id': 'event_banner'
        }
      ],
      'textModulesData': [
        {
          'header': 'Gather points meeting new people at Google I/O',
          'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
          'id': 'game_overview'
        }
      ],
      'linksModuleData': {
        'uris': [
          {
            'uri': 'https://io.google/2022/',
            'description': 'Official I/O \'22 Site',
            'id': 'official_site'
          }
        ]
      }
    };

    let response;
    try {
      // Check if the class exists already
      response = await httpClient.request({
        url: `${baseUrl}/genericClass/${classId}`,
        method: 'GET'
      });

      console.log('Class already exists');
      console.log(response);
    } catch (err) {
      if (err.response && err.response.status === 404) {
        // Class does not exist
        // Create it now
        response = await httpClient.request({
          url: `${baseUrl}/genericClass`,
          method: 'POST',
          data: genericClass
        });

        console.log('Class insert response');
        console.log(response);
      } else {
        // Something else went wrong
        console.log(err);
        res.send('Something went wrong...check the console logs!');
      }
    }

כשהקוד ירוץ, הוא ייצור סוג כרטיס חדש ויפיק את מזהה הכיתה. מזהה הכיתה מורכב ממזהה המנפיק ואחריו סיומת שהוגדרה על ידי המפתח. במקרה כזה, הסיומת מוגדרת כ-codelab_class (מזהה הכיתה ייראה דומה ל-1234123412341234123.codelab_class). יומני הפלט יכללו גם את התגובה מ-Google Wallet API.

5.‏ יצירת אובייקט של כרטיס גנרי

בשלב הזה, תגדירו את אפליקציית Node.js כך שתוכל ליצור אובייקט של כרטיס משולב באמצעות הכיתה שיצרתם קודם. יש שני תהליכים ליצירת אובייקטים של כרטיסים למשתמשים.

יצירת אובייקט הכרטיס בשרת הקצה העורפי

בשיטה הזו, אובייקט הכרטיס נוצר בשרת לקצה העורפי ומוחזר לאפליקציית הלקוח כ-JWT חתום. האפשרות הזו מתאימה במיוחד למקרים שבהם שיעור ההטמעה בקרב המשתמשים גבוה, כי היא מבטיחה שהאובייקט קיים לפני שהמשתמש מנסה להוסיף אותו לארנק.

יצירת אובייקט הכרטיס כשהמשתמש מוסיף אותו לארנק

בשיטה הזו, אובייקט הכרטיס מוגדר ומקודד לאסימון JWT חתום בשרת הקצה העורפי. לאחר מכן, מוצג באפליקציית הלקוח כפתור הוספה ל-Google Wallet שמפנה ל-JWT. כשהמשתמש לוחץ על הלחצן, ה-JWT משמש ליצירת אובייקט הכרטיס. האפשרות הזו מתאימה במיוחד למקרים שבהם השימוש של המשתמשים משתנה או לא ידוע, כי היא מונעת יצירה של אובייקטים של כרטיסים ללא שימוש בהם. הגישה הזו תוצג בקודלאב.

  1. פתיחת הקובץ web/app.js
  2. מאתרים את הפונקציה createPassObject
  3. מגדירים בפונקציה אובייקט כרטיס חדש למשתמש
    // TODO: Create a new Generic pass for the user
    let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
    let objectId = `${issuerId}.${objectSuffix}`;

    let genericObject = {
      'id': `${objectId}`,
      'classId': classId,
      'genericType': 'GENERIC_TYPE_UNSPECIFIED',
      'hexBackgroundColor': '#4285f4',
      'logo': {
        'sourceUri': {
          'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg'
        }
      },
      'cardTitle': {
        'defaultValue': {
          'language': 'en',
          'value': 'Google I/O \'22'
        }
      },
      'subheader': {
        'defaultValue': {
          'language': 'en',
          'value': 'Attendee'
        }
      },
      'header': {
        'defaultValue': {
          'language': 'en',
          'value': 'Alex McJacobs'
        }
      },
      'barcode': {
        'type': 'QR_CODE',
        'value': `${objectId}`
      },
      'heroImage': {
        'sourceUri': {
          'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
        }
      },
      'textModulesData': [
        {
          'header': 'POINTS',
          'body': '1234',
          'id': 'points'
        },
        {
          'header': 'CONTACTS',
          'body': '20',
          'id': 'contacts'
        }
      ]
    };

    // TODO: Create the signed JWT and link
    res.send("Form submitted!");

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

6.‏ יצירת לחצן 'הוספה ל-Google Wallet'

בשלב האחרון, תיצרו JWT חתום ותחזירו קישור שאפשר להשתמש בו בלחצן הוספה ל-Google Wallet. כשהמשתמש ילחץ על הלחצן, יוצג לו חלון עם בקשה לשמור את הכרטיס ב-Wallet.

  1. יוצרים את הצהרות ה-JWT, מקודדים אותן באמצעות המפתח הפרטי של חשבון השירות ומחזירים לחצן הוספה ל-Google Wallet עם הקישור המוטמע
    // TODO: Create the signed JWT and link
    const claims = {
      iss: credentials.client_email,
      aud: 'google',
      origins: [],
      typ: 'savetowallet',
      payload: {
        genericObjects: [
          genericObject
        ]
      }
    };

    const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
    const saveUrl = `https://pay.google.com/gp/v/save/${token}`;

    res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`);
  2. טעינת מחדש של האפליקציה שפועלת בדפדפן
  3. מזינים את כתובת האימייל בטופס ובוחרים באפשרות יצירת כרטיס.
  4. כשהלחצן מופיע, בוחרים באפשרות הוספה ל-Google Wallet.

הכפתור &#39;הוספה ל-Google Wallet&#39; מוצג בהצלחה בחזית האפליקציה

7.‏ מזל טוב

דוגמה לאובייקט של אישור כללי

מזל טוב, השלמתם את השילוב של Google Wallet API באינטרנט!

מידע נוסף

אפשר לעיין בשילוב המלא במאגר GitHub‏ google-pay/wallet-web-codelab.

יצירת כרטיסים ובקשת גישה לייצור

כשתהיו מוכנים להנפיק כרטיסים משלכם בסביבת הייצור, תוכלו להיכנס למסוף של Wallet ו-Google Pay כדי לבקש גישה לסביבת הייצור.

מידע נוסף זמין במאמר דרישות מוקדמות ל-Web API.