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

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

1. מבוא

סקירה כללית

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

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

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

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

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

מכשיר מבוסס-Android שמציג את תהליך ההקצאה של 'הוספה ל-Google Wallet'

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

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

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

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

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

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

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

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

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

מטרות

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

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

תמיכה

אם נתקעתם בשלב כלשהו ב-Codelab, במאגר GitHub‏ google-pay/wallet-android-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. יצירת כרטיס גנרי

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

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

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

משכפלים את מאגר GitHub‏ google-pay/wallet-android-codelab לתחנת העבודה המקומית
```
git clone https://github.com/google-pay/wallet-android-codelab.git
```
פותחים את המאגר המשוכפל במסוף או בשורת הפקודה
מנווטים לספרייה backend (הסקריפטים האלה מחקים פעולות של שרת backend)
```
cd backend
```
התקנה של יחסי התלות ב-Node.js
```
npm install .
```
במאגר backend, פותחים את generic_class.js
מחליפים את הערך של issuerId במזהה המנפיק מתוך מסוף Google Pay ו-Wallet.
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
בטרמינל או בשורת הפקודה, מריצים את הסקריפט generic_class.js.
```
node generic_class.js
```

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

4. פתיחת הפרויקט ב-Android Studio

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

פתיחת Android Studio
בוחרים באפשרות קובץ ואז באפשרות פתיחה.
בוחרים את הספרייה android במאגר
לוחצים על פתיחה.

הוספת Google Wallet SDK לאפליקציה

פותחים את קובץ ה-Gradle build ברמת המודול (android/app/build.gradle).

הוספת Google Wallet SDK לקטע dependencies

// TODO: Add the "com.google.android.gms:play-services-pay" dependency to
//       use the Google Wallet API
implementation "com.google.android.gms:play-services-pay:16.0.3"

שמירת הקובץ
בוחרים באפשרות File (קובץ) ואז באפשרות Sync Project with Gradle Files (סנכרון הפרויקט עם קובצי Gradle).

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

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

יוצרים קובץ פריסה חדש: app/src/main/res/layout/add_to_google_wallet_button.xml

מוסיפים את התוכן הבא לקובץ הפריסה החדש

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:clickable="true"
    android:contentDescription="@string/add_to_google_wallet_button_content_description"
    android:focusable="true">
  <ImageView
      android:layout_width="227dp"
      android:layout_height="26dp"
      android:layout_gravity="center"
      android:duplicateParentState="true"
      android:src="@drawable/add_to_google_wallet_button_foreground" />
</FrameLayout>

כוללים את הפריסה add_to_google_wallet_button.xml בקובץ הפריסה של פעילות התשלום (app/src/main/res/layout/activity_checkout.xml)

<!--
    TODO: Create the button under `add_to_google_wallet_button.xml`
          and include it in your UI
-->
<include
    android:id="@+id/addToGoogleWalletButton"
    layout="@layout/add_to_google_wallet_button"
    android:layout_width="match_parent"
    android:layout_height="48dp"
    android:layout_marginTop="10dp" />

6. בדיקה אם Google Wallet API זמין

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

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

פותחים את הקובץ CheckoutActivity.kt ב-app/src/main/java/com/google/android/gms/samples/wallet/activity/

יצירת מאפיין של מחלקה למופע PayClient

// TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient

מציבים את המאפיין PayClient בשיטה onCreate

// TODO: Instantiate the client
walletClient = Pay.getClient(this)

יוצרים שיטה שבודקת אם Google Wallet SDK ו-API זמינים במכשיר ומטפלת בתוצאה

// TODO: Create a method to check for the Google Wallet SDK and API
private fun fetchCanUseGoogleWalletApi() {
  walletClient
    .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
    .addOnSuccessListener { status ->
      if (status == PayApiAvailabilityStatus.AVAILABLE)
        layout.passContainer.visibility = View.VISIBLE
    }
    .addOnFailureListener {
      // Hide the button and optionally show an error message
    }
}

קוראים לשיטה fetchCanUseGoogleWalletApi בשיטה onCreate כדי לבדוק אם Google Wallet API זמין
```
// TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()
```

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

7. יצירת אובייקט כרטיס כללי

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

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

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

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

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

פותחים את הקובץ backend/generic_pass.js
מחליפים את הערך של issuerId במזהה המנפיק מתוך מסוף Google Pay ו-Wallet.
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
בטרמינל או בשורת הפקודה, מריצים את הקובץ generic_pass.js
```
node generic_pass.js
```
מעתיקים את טוקן הפלט ללוח או לעורך טקסט

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

aside בסביבת ייצור, המערכת העורפית אחראית ליצירת JWT ולהחזרתם ללקוחות. ב-codelab הזה, הסקריפט generic_pass.js מחקה את ההתנהגות הזו ו "מחזיר" טוקן לשימוש באפליקציית הלקוח.

8. הוספת הכרטיס ל-Google Wallet

אחרי שווידאתם שממשק Google Wallet API זמין ויצרתם JWT חתום, אתם יכולים להציג למשתמש בקשה להוסיף את הכרטיס לארנק. בשלב הזה, מוסיפים listener ללחצן Add to Google Wallet (הוספה ל-Google Wallet) שמשתמש ב-Google Wallet API כדי לשמור את הכרטיס ב-Wallet של המשתמש.

פותחים את הקובץ app/src/main/CheckoutActivity.kt

מחליפים את הערך של token ב-JWT שיצרתם קודם.

// TODO: Save the JWT from the backend "response"
private val token = "TOKEN"

יצירת מאפיין של מחלקה לאחסון קוד הבקשה

// TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000

הגדרת מאזין ללחצן הוספה ל-Google Wallet

// TODO: Set an on-click listener on the "Add to Google Wallet" button
addToGoogleWalletButton = layout.addToGoogleWalletButton.root

addToGoogleWalletButton.setOnClickListener {
  walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
}

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

9. טיפול בתוצאה של savePassesJwt

בשלב האחרון של ה-codelab הזה, תגדירו את האפליקציה כך שתטפל בתוצאה של פעולת walletClient.savePassesJwt.

פותחים את הקובץ app/src/main/CheckoutActivity.kt

מחליפים את השיטה onActivityResult בקוד הבא

// TODO: Handle the result
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (requestCode == addToGoogleWalletRequestCode) {
    when (resultCode) {
      RESULT_OK -> {
        // Pass saved successfully. Consider informing the user.
      }

      RESULT_CANCELED -> {
        // Save canceled
      }

      PayClient.SavePassesResult.SAVE_ERROR ->
        data?.let { intentData ->
          val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
          // Handle error. Consider informing the user.
          Log.e("SavePassesResult", errorMessage.toString())
        }

      else -> {
        // Handle unexpected (non-API) exception
      }
    }
  }
}

עכשיו האפליקציה יכולה לטפל בתרחישים הבאים:

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

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

10. מזל טוב

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

השלמת בהצלחה את השילוב של Google Wallet API ב-Android.

מידע נוסף

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

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

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

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