סקירה כללית

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

ממשק API להפעלה

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

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

string

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

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

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