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

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

Google Wallet API מספק קבוצה מוגדרת מראש של אובייקטים מסוג מחלקות וכרטיסים של כרטיסים שאפשר ליצור עבורם מופעים, ולהשתמש בהם כדי ליצור כרטיס שמונפק למשתמש כמו GiftCardClass וגם GiftCardObject, GenericClass ו-GenericObject ועוד.

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

סיווגי כרטיסים

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

לדוגמה, במופע הבא של EventTicketClass מוגדרים השדות המשותפים לכל הכרטיסים שמונפקים לאירוע קרוב(מקום, שם האירוע, המנפיק, תאריך/שעה).

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW"
}
  

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

מעביר אובייקטים

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

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

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "9"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "L"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "45"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "7C"
      }
    }
  },
  "barcode": {
    "type": "BARCODE_TYPE_UNSPECIFIED",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
  

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

איך כיתות מסוג 'כרטיסים' פועלות עם אובייקטים של 'כרטיסים'

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

לדוגמה, בתרשים הבא של כרטיס פשוט לאירוע אפשר לראות איך השדות שמוגדרים בEventTicketClass המשותף, והשדות של כרטיס ספציפי שמוגדר בEventTicketObject, יוצרים יחד את הכרטיס הסופי שיונפק. הערה: בנכס classId של האובייקט 'כרטיסים' יש הפניה למזהה של מחלקת הכרטיסים.

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

הוספת כרטיס ל-Google Wallet של המשתמש

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

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

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