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

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

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

כל מופע של מחלקת כרטיסים ושל אובייקט כרטיס מוגדר כאובייקט 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 Object) מציין את הפרטים הייחודיים של כרטיס ספציפי שהונפק למשתמש ספציפי, בעוד שמופע של מחלקה של כרטיסים (Passes Class) מציין קבוצה של מאפיינים משותפים לשימוש בכרטיס אחד או יותר.

לדוגמה, כשיוצרים כרטיס לאירוע באמצעות 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": ""
  }
}
  

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

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

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

לדוגמה, בתרשים הבא של כרטיס פשוט לאירוע אפשר לראות איך השדות שמוגדרים ב-EventTicketClass המשותף והשדות של כרטיס ספציפי שמוגדרים ב-EventTicketObject משולבים כדי ליצור את הכרטיס הסופי שהונפק. שימו לב איך מזהה הכרטיס מסוג Passes Class מופיע במאפיין classId של האובייקט Passes Object.

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

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

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

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

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