דף זה תורגם על ידי Cloud Translation API.

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

1. מבוא

סקירה כללית

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

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

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

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

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

דוגמה לכרטיס ל-Google Wallet לאירוע של כנס

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

העברת מחלקות ואובייקטים

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

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

מידע על ה-Codelab הזה

ב-codelab הזה תבצעו את המשימות הבאות:

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

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

Git
חשבון Google עם גישה למסוף Google Cloud
‫Node.js בגרסה 10 ואילך

מטרות

אחרי שתשלימו את ה-codelab הזה, תוכלו:

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

תמיכה

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

2. הגדרה

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

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

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

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

הפעלת Google Wallet API

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

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

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

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

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

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

בחירת חשבון השירות
בוחרים בתפריט KEYS (מקשים).
לוחצים על ADD KEY (הוספת מפתח) ואז על Create new key (יצירת מפתח חדש).
בוחרים את סוג המפתח JSON.
לוחצים על יצירה.

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

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

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

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

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

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

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

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

משך הצפייה 10:00

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

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

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

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

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

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

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

4. יצירת כרטיס גנרי

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

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

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

פותחים את הקובץ web/app.js
מחליפים את הערך של issuerId במזהה המנפיק מתוך מסוף Google Pay ו-Wallet.
```
// TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
```
איתור הפונקציה createPassClass

בפונקציה, יוצרים לקוח 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 כדי ליצור את אובייקט הכרטיס. האפשרות הזו מתאימה במיוחד למקרים שבהם אימוץ המשתמשים משתנה או לא ידוע, כי היא מונעת יצירה של כרטיסים שלא נעשה בהם שימוש. הגישה הזו תשמש ב-codelab.

פותחים את הקובץ web/app.js
איתור הפונקציה createPassObject

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

// 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!");

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

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

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

יוצרים את טענות ה-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>`);

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

7. מזל טוב

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

השלמת בהצלחה את השילוב של Google Wallet API באתר!

מידע נוסף

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

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

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

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