סקירה כללית

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

API להפעלה

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

  activationOptions: {
    activationUrl: string
  }
שדה תיאור
activationUrl

string

כתובת ה-URL של נקודת הקצה של השותף שתיקרא לבקשות הפעלה. כתובת ה-URL צריכה להתארח ב-HTTPS ו-robots.txt צריך לאפשר גישה לנתיב כתובת ה-URL UserAgent:Google-Valuables.

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

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
שדה תיאור
activationStatus

enum (ActivationStatus)

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

הערכים הקבילים הם:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

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

boolean

אם האובייקט הזה מקושר כרגע למכשיר אחד.
DeviceContext
שדה תיאור
deviceToken

string

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

חשוב לשים לב שהשדה deviceToken מתקבל מהשדה פרמטרים של הפעלה deviceContext

הצמדת מכשיר

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

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

כדי להטמיע את התכונה 'הצמדת מכשיר', צריך לעדכן את האובייקט באמצעות השדה deviceToken שמתקבל עם הפרמטרים של ההפעלה, וגם באמצעות הגדרת הערך של hasLinkedDevice כ-true באותה קריאה ל-API. אם רוצים, אפשר לבטל את הקישור של הכרטיס למכשיר על ידי הגדרת הערך hasLinkedDevice כ-False בקריאה עתידית ל-API.

תרשים רצף להצמדת מכשיר

פרמטרים של הפעלה

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

דוגמה לקובץ JSON: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

מזהה תיאור
classId

מזהה כיתה מוגדר במלואו. נעשה שימוש בפורמט הבא:

<issuer_id.class_id>
objectIds

מערך מוגדר במלואו של מזהי אובייקטים המשתמשים בפורמט הבא:

<issuer_id.object_id>
expTimeMillis זמן התפוגה באלפיות השנייה מאז EPOCH. אחרי תאריך התפוגה, ההודעה צריכה להיחשב לא חוקית.
eventType תמיד "activate".
nonce אין אפשרות לעקוב אחר משלוחים כפולים.
deviceContext

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

המזהה הזה לא יכול להיות קבוע לבקשות עתידיות ממכשיר נתון.