דף זה תורגם על ידי Cloud Translation API.

פרטים טכניים לגבי כרטיסים של Motics ב-Google Wallet

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

ארכיטקטורת המערכת

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

איור 1. תהליך השמירה של כרטיס Motics

איור 1 מציג את תהליך היצירה, ההפעלה וההצמדה של כרטיס Motics Google Wallet, במספר ישויות:

השרתים של Google
שרת PTO (System Integrator)
שרת Motics SCE
חנות באינטרנט

הנה תיאור מפורט יותר של התהליך:

בשלב ההגדרה הראשונית, שרת ה-PTO יוצר את transitClass, מעבירים את הערכים ownerId ו-activationUrl באמצעות transitClass:Insert נקודת קצה ל-Google Wallet API. זו פעילות חד-פעמית.
לאחר מכן, כשמשתמש רוכש כרטיס בחנות האינטרנט, שרת ה-PTO קורא transitObject:Insert שמכיל מידע בסיסי על מכירת כרטיסים וחלק בשדות הראשוניים שמציינים שמדובר בכרטיס של Motics.
לאחר מכן שרת ה-PTO וחנות האינטרנט פועלים יחד כדי לעבד את הוסף ללחצן Google Wallet, ובסופו של דבר תחזיר את ה-JWT של הכרטיס אל Google, באמצעות הקישור לשמירה.
עכשיו שלב הצמדת הכרטיס יכול להתחיל, כששרת Google קורא נקודת קצה (endpoint) של הפעלה מאחורי activationUrl.
בתגובה לשלב 4, שרת ה-PTO יוצר את החתימה (sigSTB) שמכיל את ה-SCE_ID שנחתם באמצעות ה-SAM.
לפני התגובה לקריאה של activationUrl, שרת ה-PTO צריך קודם קריאה transitObject:Patch שמכיל את כל המידע הנדרש של Motics, כולל applicationData של Motics.
רק אחרי שהקריאה transitObject:Patch הושלמה בהצלחה, ה-PTO השרת צריך להחזיר תגובה מוצלחת (HTTP-200) ל-activationUrl שיחה.

יישום ההעברה ביטול הקישור בתהליך

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

נקודת קצה להפעלה

המנפיק/ה-PTO (או משלב המערכת שלו) צריכים להטמיע כרטיס נקודת הקצה להפעלה ש-Google תפעיל כשהכרטיס יישמר. כתובת ה-URL לנקודת הקצה הזו, יש לציין בהפעלה של transitClass:Insert. נקודת הקצה של ההפעלה תיצור את החתימה (sigSTB) ותקרא שיטת transitObject:Patch עם הפרמטרים המוגדרים בהמשך .

בקשה

שליחת הבקשה לנקודת הקצה להפעלה היא בפורמט הבא:

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

תשובה

צריך להחזיר תגובת HTTP-200 מוצלחת עם גוף ריק אם:

ה-sigSTB שמכיל SCE_ID נוצר ונחתם באמצעות SAM
ה-method transitObject:Patch הופעלה בהצלחה

Status: 200 - OK
Body: {}

יעדי זמן אחזור

נקודת הקצה להפעלה צריכה להיות תואמת ליעדי זמן האחזור הבאים:

יש להשיב לפחות על 50% מכל הבקשות בתוך 200ms
יש להשיב לפחות על 95% מכל הבקשות בתוך 2s
יש גבול קשיח עליון של 10s

שינויים ב-Google Wallet API

בהמשך מתוארים השינויים בנקודות הקצה של Google Wallet API כדי תומכים ב-Motics כפי שמתואר בארכיטקטורת המערכת.

שיטה: transitClass:insert

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

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

ייצוג JSON

בשילוב של Motics נדרש לפחות ייצוג JSON הבא של transitClass בגוף הבקשה transitClass:insert. חובה אחרת יש להגדיר גם transitClass שדות מטא-נתונים.

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

כאשר certEnvironment = PRODUCTION = שרת Google יאחזר את האישור מהשרת של Motics בשלב הייצור. כאשר certEnvironment = STAGING את Google השרת יאחזר את האישור משרת Motics של ארגז החול.

שיטה: transitObject:insert

זוהי נקודת הקצה של Google Wallet API להוספת transitObject עבור כרטיס שהמשתמש רוצה לרכוש ולהוסיף ל-Google Wallet. המערכת משלב השילוב צריך להעביר transitObject עם בעיקר פרטי הכרטיס ב לנקודה הזו. עיינו בהסבר transitObject & ממשק API של transitObject.Insert לרשימה מלאה של פרמטרים (שאינם תנועה) ופרטים נוספים.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitObject

ייצוג JSON

בשילוב של Motics נדרש לפחות ייצוג JSON הבא של transitObject בגוף הבקשה transitObject:insert. אובייקט אחר ניתן להגדיר גם את שדות המטא-נתונים, ואת כל שדות החובה האחרים צריכים להיות כלול.

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

הערות:

לפי דרישת ה-API, צריך לכלול את השדה applicationData. בשלב הזה בתהליך ההפעלה של Motics, הערך של applicationData עדיין לא ידוע, ולכן הוא צריך להיות מוגדר למחרוזת ריקה.
- השדה applicationData יוגדר בהמשך בtransitObject:Patch שיחה.
חובה להגדיר את הקיזוז של אזור הזמן על האובייקטים validTimeInterval מסוג DateTime שצוין, לדוגמה: 2024-04-12T19:20:50.52-04:00.

שיטה: transitObject:patch

זוהי נקודת הקצה של Google Wallet API לתיקון transitObject בנתונים משמש את Google ליצירת ברקודים ב-Motics ולאחזור שירות eTicket של VDV eTicket אישורים. עיינו בהסבר transitObject & API של transitObject.Patch לרשימה מלאה של פרמטרים (שאינם תנועה) ופרטים נוספים.

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

ייצוג JSON

השילוב של Motics מחייב את הייצוג הבא של transitObject בגוף הבקשה transitObject:patch. לתשומת ליבכם: שהשדה applicationData יאוכלס.

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

מפרטים של נתוני האפליקציות

בהמשך מפורט המפרט של Motics לגבי התוכן של applicationData (תג:0x5F07). צריך ליצור את applicationData על ידי משלב המערכת בפורמט tag-length-value (TLV). הנתונים האלה מופיעים בהמשך עובר במבנה נתונים גדול יותר כדי לקודד אותו סוף סוף כחלק מקוד ה-QR

תג	אורך	ערך
`0x9E`	81 80	חתימה `OctetString`, 128 הבייטים הראשונים של נתוני הרשאה חתומים מונח ב-Google: `sigSTB`
`0x9A`	משתנה	שאריות נתונים `OctetString`, שאר נתוני ההרשאה מונח ב-Google: `sigSTB cont.`
`0x7F21`	81 C8	האישור המנפיק `OctetString`, נתוני אישורים מונח ב-Google: `Cert(puk_SAM)`
`0x42`	08	סימוכין לרשות האישורים (מכונית) `OctetString`, שווי הרכב מונח ב-Google: `CAR`