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

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

מידע על Codelab זה

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

1.‏ מבוא

סקירה כללית

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

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

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

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

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

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

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

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

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

סוג

תיאור

סוג הכרטיס

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

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

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

מידע על Codelab זה

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

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

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

מטרות

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

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

תמיכה

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

2.‏ הגדרה

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

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

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

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

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

הפעלת 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.‏ יצירת כיתה של כרטיס גנרי

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

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

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

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

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

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

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

  1. פתיחת Android Studio
  2. בוחרים באפשרות קובץ ואז באפשרות פתיחה.
  3. בוחרים את הספרייה android במאגר
  4. בוחרים באפשרות פתיחה.

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

  1. פותחים את קובץ ה-build של Gradle ברמת המודול (android/app/build.gradle)
  2. מוסיפים את 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"
  3. שומרים את הקובץ.
  4. בוחרים באפשרות File (קובץ) ואז באפשרות Sync Project with Gradle Files (סנכרון הפרויקט עם קובצי Gradle).

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

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

הלחצן 'הוספה ל-Google Wallet'

  1. יוצרים קובץ פריסה חדש: app/src/main/res/layout/add_to_google_wallet_button.xml
  2. מוסיפים את התוכן הבא לקובץ הפריסה החדש
    <?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>
  3. כוללים את הפריסה 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 זמין במכשיר. אם כן, הלחצן יוצג בפעילות. אחרת, הכפתור יהיה מוסתר.

  1. פותחים את הקובץ CheckoutActivity.kt ב-app/src/main/java/com/google/android/gms/samples/wallet/activity/
  2. יצירת מאפיין כיתה למכונה PayClient
    // TODO: Create a client to interact with the Google Wallet API
    private lateinit var walletClient: PayClient
  3. יצירת מופע של המאפיין PayClient בשיטה onCreate
    // TODO: Instantiate the client
    walletClient = Pay.getClient(this)
  4. יצירת שיטה שבודקת אם ה-SDK וה-API של Google Wallet זמינים במכשיר ומטפלת בתוצאה
    // 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
        }
    }
  5. קוראים ל-method‏ fetchCanUseGoogleWalletApi ב-method‏ onCreate כדי לבדוק אם Google Wallet API זמין
    // TODO: Check if the Google Wallet API is available
    fetchCanUseGoogleWalletApi()

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

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

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

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

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

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

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

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

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

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

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

8.‏ מוסיפים את הכרטיס ל-Google Wallet

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

  1. פותחים את הקובץ app/src/main/CheckoutActivity.kt
  2. מחליפים את הערך של token ב-JWT שיצרתם קודם
    // TODO: Save the JWT from the backend "response"
    private val token = "TOKEN"
  3. יוצרים מאפיין בכיתה כדי לאחסן את קוד הבקשה
    // TODO: Add a request code for the save operation
    private val addToGoogleWalletRequestCode = 1000
  4. הגדרת מאזין ללחצן הוספה ל-Google Wallet
    // TODO: Set an on-click listener on the "Add to Google Wallet" button
    addToGoogleWalletButton = layout.addToGoogleWalletButton.

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

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

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

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

  1. פותחים את הקובץ app/src/main/CheckoutActivity.kt
  2. משנים את השיטה 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.