รายละเอียดทางเทคนิคสำหรับตั๋วของ Motics ใน Google Wallet

หน้านี้ให้รายละเอียดทางเทคนิคของผู้ให้บริการขนส่งมวลชน (PTO) และ ผู้ผสานรวมระบบจะต้องผสานรวมกับ Google เพื่อออกตั๋วของ Motics ใน Google Wallet โซลูชันนี้ใช้ Google Wallet API และยังต้องใช้ เกี่ยวกับ PTO ในการใช้อุปกรณ์ปลายทางการเปิดใช้งาน

สถาปัตยกรรมของระบบ

ส่วนนี้จะแสดงสถาปัตยกรรมของระบบและขั้นตอนการบันทึก Motics

รูปที่ 1 ขั้นตอนการบันทึกตั๋ว Motics

รูปที่ 1 แสดงขั้นตอนการสร้าง เปิดใช้งาน และปักหมุดตั๋ว Motics ใน Google Wallet ในหลายหน่วยงาน ได้แก่

• เซิร์ฟเวอร์ของ Google
• เซิร์ฟเวอร์ PTO (System Integrator)
• เซิร์ฟเวอร์ SCE ของ Motics
• ร้านค้าบนเว็บ

ต่อไปนี้เป็นคำอธิบายขั้นตอนอย่างละเอียด

1. ในระยะการตั้งค่าเริ่มต้น เซิร์ฟเวอร์ PTO จะสร้าง transitClass การส่ง ownerId และ activationUrl โดยใช้ transitClass:Insert อุปกรณ์ปลายทาง API ของ Google Wallet นี่เป็นกิจกรรมแบบครั้งเดียว
2. ถัดไป เมื่อผู้ใช้ซื้อตั๋วจากเว็บไซต์ร้านค้า เซิร์ฟเวอร์ PTO จะเรียก transitObject:Insert ที่มีข้อมูลการจำหน่ายตั๋วพื้นฐานและบางส่วน ฟิลด์เริ่มต้นที่ระบุว่านี่คือตั๋ว Motics
3. จากนั้นเซิร์ฟเวอร์ PTO และเว็บสโตร์จะทำงานร่วมกันเพื่อแสดงผล เพิ่มลงใน Google Wallet แล้วส่ง JWT ของตั๋วคืนไปยัง Google โดยใช้ลิงก์บันทึก
4. ตอนนี้ขั้นตอนการปักหมุดตั๋วจะเริ่มขึ้นแล้ว เมื่อเซิร์ฟเวอร์ของ Google เรียก ปลายทางการเปิดใช้งานที่อยู่หลัง activationUrl
5. เพื่อตอบสนองต่อขั้นตอนที่ 4 เซิร์ฟเวอร์ PTO จะสร้างลายเซ็น (sigSTB) ที่มี SCE_ID ที่ลงนามกับ SAM
6. ก่อนตอบกลับการเรียก activationUrl เซิร์ฟเวอร์ PTO ควร เรียก transitObject:Patch ที่มีข้อมูล Motics ที่จำเป็นทั้งหมด ซึ่งรวมถึง applicationData ของ Motics
7. PTO หลังการเรียก transitObject:Patch สำเร็จแล้วเท่านั้น เซิร์ฟเวอร์ควรแสดงผลการตอบกลับที่สำเร็จ (HTTP-200) ไปยัง activationUrl การโทร

ใช้การย้ายและ ขั้นตอนการยกเลิกการลิงก์

หากต้องการมอบประสบการณ์ที่ดีแก่ผู้ใช้ ผู้ใช้ควรย้าย Motics ได้ คำขอแจ้งปัญหาจากอุปกรณ์หนึ่งไปยังอีกเครื่องหนึ่ง ภายใต้ขีดจำกัดที่ผู้ออกบัตรกำหนด ในกรณีนี้ ผู้ออกบัตรจะต้องใช้ขั้นตอนการย้ายและยกเลิกการลิงก์

ปลายทางการเปิดใช้งาน

ผู้ออกบัตร/PTO (หรือผู้รวมระบบของผู้ให้บริการ) ต้องออกตั๋ว ปลายทางการเปิดใช้งานที่ Google จะเรียกใช้เมื่อบันทึกตั๋วแล้ว URL ควรระบุในการเรียกใช้ transitClass:Insert ที่ปลายทางนี้ ปลายทางการเปิดใช้งานจะสร้างลายเซ็น (sigSTB) และเรียก transitObject:Patch ที่มีพารามิเตอร์ที่กำหนดไว้ในเมธอดต่อไปนี้

สำคัญ: เซิร์ฟเวอร์ PTO (ผู้ผสานระบบ) ต้องเรียกใช้ 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 แล้ว
• เมธอด transitObject:Patch ถูกเรียกสำเร็จแล้ว

Status: 200 - OK
Body: {}

เป้าหมายเวลาในการตอบสนอง

ปลายทางการเปิดใช้งานควรเป็นไปตามเป้าหมายเวลาในการตอบสนองต่อไปนี้

• ควรมีการตอบกลับคำขออย่างน้อย 50% รายการภายใน 200ms
• ควรมีการตอบกลับคำขออย่างน้อย 95% รายการภายใน 2s
• มีการจำกัดขีดจำกัดสูงสุดไว้ที่ 10s

การเปลี่ยนแปลงใน Google Wallet API

ข้อมูลต่อไปนี้สรุปการเปลี่ยนแปลงในอุปกรณ์ปลายทาง Google Wallet API เพื่อ รองรับ Motics ตามที่ระบุไว้ในสถาปัตยกรรมระบบ

สำคัญ: ข้อมูลต่อไปนี้คือว่าคุณได้ศึกษาด้านมาตรฐานเสร็จสมบูรณ์แล้ว การผสานรวมกับ Google Wallet API เฉพาะการอัปเดตและการเปลี่ยนแปลงปลายทางสำหรับ Motics ของการสนับสนุนจะแสดงที่นี่

เมธอด: transitClass:insert

นี่คือปลายทาง Google Wallet API สำหรับสร้าง transitClass ในบัญชี แบ็กเอนด์ ผู้ผสานรวมระบบต้องเรียกใช้ API นี้ด้วยข้อมูลต่อไปนี้ พารามิเตอร์คำขอ พร้อมด้วยฟิลด์อื่นๆ ที่เกี่ยวข้อง โปรดดู transitClass และ เอกสารประกอบของ transitClass.Insert สำหรับรายการทั้งหมดของ (ไม่ใช่ Motics) และรายละเอียดเพิ่มเติม

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 = จัดแท็ก Google จะเรียกใบรับรองจากเซิร์ฟเวอร์แซนด์บ็อกซ์ Motics

เมธอด: transitObject:insert

นี่คือปลายทาง Google Wallet API สำหรับแทรก transitObject สำหรับ ตั๋วที่ผู้ใช้ต้องการซื้อและเพิ่มลงใน Google Wallet ระบบ ผู้รวมระบบควรส่ง transitObject ที่มีข้อมูลตั๋วเป็นหลักที่ ถึงจุดนี้ โปรดดู transitObject และ transitObject.Insert API สําหรับรายการพารามิเตอร์ (ไม่ใช่ Motics) ทั้งหมดและรายละเอียดเพิ่มเติม

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 การโทร
• ออบเจ็กต์ DateTime validTimeInterval ต้องมีออฟเซ็ตเขตเวลา ที่ระบุไว้ เช่น 2024-04-12T19:20:50.52-04:00

เมธอด: transitObject:patch

นี่คือปลายทาง API ของ Google Wallet ที่จะแพตช์ transitObject ด้วยข้อมูลที่จะ ใช้โดย Google for Motics การสร้างบาร์โค้ดและการดึงข้อมูล VDV eTicket Service ใบรับรอง โปรดดู transitObject และ API transitObject.Patch สําหรับรายการพารามิเตอร์ (ไม่ใช่ Motics) ทั้งหมดและรายละเอียดเพิ่มเติม

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

การแสดง JSON

การผสานรวม Motics ต้องการการนำเสนอต่อไปนี้ transitObject ในเนื้อหาคำขอ transitObject:patch โปรดทราบว่า ที่มีการป้อนข้อมูลในช่อง applicationData

หมายเหตุ: ปลายทางtransitObject:patch สนับสนุนความหมายของแพตช์ ดังนั้นจึงเป็น เพียงพอที่จะรวมข้อมูลที่เฉพาะเจาะจงของ Motics ต่อไปนี้เมื่อ กำลังเรียกใช้แพตช์

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

ข้อกำหนดในการจัดทำข้อมูลแอปพลิเคชัน

ต่อไปนี้เป็นข้อกำหนดของ Motics สำหรับเนื้อหาของ applicationData (แท็ก:0x5F07) applicationData ควรสร้างโดย ผู้ผสานรวมระบบในรูปแบบค่าความยาวแท็ก (TLV) ข้อมูลนี้จะมาในภายหลัง ห่อหุ้มอยู่ในโครงสร้างข้อมูลขนาดใหญ่เพื่อเข้ารหัสในที่สุดโดยเป็นส่วนหนึ่งของคิวอาร์โค้ด โค้ด

แท็ก	ความยาว	ค่า
0x9E	81 80	ลายเซ็น OctetString, 128 ไบต์แรกของข้อมูลการให้สิทธิ์ที่ลงนามแล้ว ข้อกำหนดของ Google: sigSTB
0x9A	แตกต่างกันไป	ข้อมูลที่เหลืออยู่ OctetString, ข้อมูลการให้สิทธิ์ที่เหลืออยู่ ข้อกำหนดของ Google: sigSTB cont.
0x7F21	81 C8	ใบรับรองที่ออก OctetString, ข้อมูลใบรับรอง ข้อกำหนดของ Google: Cert(puk_SAM)
0x42	08	ข้อมูลอ้างอิงผู้ออกใบรับรอง (CAR) OctetString, ค่า CAR ข้อกำหนดของ Google: CAR