Trang này được dịch bởi Cloud Translation API.

Thông tin chi tiết kỹ thuật về vé Motics trong Google Wallet

Trang này cung cấp chi tiết kỹ thuật về Nhà điều hành phương tiện công cộng (PTO) và đối tác tích hợp hệ thống của họ cần tích hợp với Google để cung cấp vé Motics trong Google Wallet. Giải pháp này sử dụng API của Google Wallet đồng thời còn dựa vào về PTO triển khai một điểm cuối kích hoạt.

Cấu trúc hệ thống

Phần này cho thấy cấu trúc hệ thống và quy trình lưu của Motics.

Hình 1. Quy trình lưu vé của Motics

Hình 1 thể hiện quy trình tạo, kích hoạt và ghim một phiếu yêu cầu hỗ trợ của Motics Google Wallet trên một số pháp nhân:

Các máy chủ của Google
Máy chủ PTO (Trình tích hợp hệ thống)
Máy chủ SCE của Motics
Cửa hàng trực tuyến

Phần sau đây mô tả chi tiết hơn về quy trình này:

Trong giai đoạn thiết lập ban đầu, máy chủ PTO sẽ tạo transitClass, truyền ownerId và activationUrl bằng transitClass:Insert Điểm cuối API Google Wallet. Đây là hoạt động chỉ cần thực hiện một lần.
Tiếp theo, khi người dùng mua vé từ cửa hàng trên web, máy chủ PTO sẽ gọi transitObject:Insert chứa thông tin bán vé cơ bản và một số các trường đầu tiên cho biết đây là vé Motics.
Sau đó, máy chủ PTO và cửa hàng trực tuyến sẽ phối hợp hoạt động để hiển thị Nút Thêm vào Google Wallet và cuối cùng trả lại JWT của vé về Google, bằng cách sử dụng liên kết lưu.
Bây giờ, giai đoạn ghim phiếu yêu cầu hỗ trợ có thể bắt đầu, khi máy chủ Google gọi hàm Điểm cuối kích hoạt được sử dụng sau activationUrl.
Để phản hồi Bước 4, máy chủ PTO tạo chữ ký (sigSTB) chứa SCE_ID ký bằng SAM.
Trước khi phản hồi lệnh gọi activationUrl, trước tiên, máy chủ PTO phải gọi transitObject:Patch chứa tất cả thông tin Motics cần thiết, bao gồm cả applicationData của Motics.
Chỉ sau khi lệnh gọi transitObject:Patch thành công, PTO máy chủ sẽ trả về phản hồi thành công (HTTP-200) cho activationUrl .

Triển khai dịch vụ Di chuyển và Huỷ liên kết quy trình

Để mang lại trải nghiệm tốt cho người dùng, người dùng nên có khả năng di chuyển Motics vé từ thiết bị này sang thiết bị khác trong những giới hạn nhất định do nhà phát hành quy định. Để làm được điều này, nhà phát hành phải triển khai Quy trình di chuyển và huỷ liên kết.

Điểm cuối kích hoạt

Nhà phát hành/PTO (hoặc đơn vị tích hợp hệ thống của họ) cần triển khai phiếu yêu cầu hỗ trợ điểm cuối kích hoạt mà Google sẽ gọi khi phiếu yêu cầu hỗ trợ được lưu. URL đến điểm cuối này phải được cung cấp trong lệnh gọi đến transitClass:Insert. Điểm cuối kích hoạt sẽ tạo chữ ký (sigSTB) và gọi phương thức transitObject:Patch với các thông số được xác định như sau .

Yêu cầu

Yêu cầu gửi đến điểm cuối kích hoạt có định dạng sau:

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,
}

Phản hồi

Phản hồi thành công HTTP-200 có phần nội dung trống, nên được trả về nếu:

sigSTB chứa SCE_ID đã được tạo và ký bằng SAM
Phương thức TransitObject:Patch đã được gọi thành công

Status: 200 - OK
Body: {}

Mục tiêu độ trễ

Điểm cuối kích hoạt phải tuân thủ các mục tiêu độ trễ sau đây:

Phải phản hồi ít nhất 50% trong tổng số yêu cầu trong vòng 200ms
Phải phản hồi ít nhất 95% trong tổng số yêu cầu trong vòng 2s
Có giới hạn trên cố định là 10s

Các thay đổi đối với API Google Wallet

Sau đây là nội dung thay đổi đối với các điểm cuối của API Google Wallet để hỗ trợ Motics như đã nêu trong kiến trúc hệ thống.

Phương thức: TransitClass:insert

Đây là điểm cuối API Google Wallet để tạo transitClass trên phần phụ trợ. Trình tích hợp hệ thống cần gọi API này bằng cách sau thông số yêu cầu cùng với bất kỳ trường nào khác có thể áp dụng. Tham khảo transitClass và Tài liệu về API transitClass.Insert để biết danh sách đầy đủ thông số (không phải Motics) và thông tin chi tiết khác.

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

Biểu diễn dưới dạng JSON

Quá trình tích hợp Motics đòi hỏi tối thiểu phải có bản trình bày JSON sau đây của transitClass trong nội dung yêu cầu transitClass:insert. Yêu cầu bắt buộc khác Bạn cũng cần đặt các trường siêu dữ liệu transitClass.

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

Khi certEnvironment = PRODUCTION, máy chủ Google sẽ tìm nạp chứng chỉ từ máy chủ sản xuất Motics. Khi certEnvironment = Gắn thẻ cho Google sẽ tìm nạp chứng chỉ từ máy chủ của Sandbox Motics.

Phương thức: TransitObject:insert

Đây là điểm cuối của API Google Wallet để chèn transitObject cho mà người dùng muốn mua và thêm vào Google Wallet. Hệ thống đối tác tích hợp nên truyền transitObject với chủ yếu là thông tin vé tại điểm này. Tham khảo transitObject và API transitObject.Insert tài liệu để biết danh sách đầy đủ các thông số (không phải Motics) và nhiều thông tin chi tiết khác.

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

Biểu diễn dưới dạng JSON

Quá trình tích hợp Motics đòi hỏi tối thiểu phải có bản trình bày JSON sau đây của transitObject trong nội dung yêu cầu transitObject:insert. Đối tượng khác bạn cũng có thể đặt các trường siêu dữ liệu và tất cả các trường bắt buộc khác bao gồm.

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

Lưu ý:

API yêu cầu phải có trường applicationData. Tại thời điểm này trong quy trình kích hoạt Motics, giá trị applicationData chưa xác định, vì vậy, bạn phải đặt thuộc tính này thành một chuỗi trống.
- applicationData sẽ được thiết lập sau trong transitObject:Patch .
Đối tượng DateTime validTimeInterval phải có giá trị chênh lệch múi giờ đã chỉ định, ví dụ: 2024-04-12T19:20:50.52-04:00.

Phương thức: TransitObject:patch

Đây là điểm cuối của API Google Wallet để vá transitObject bằng dữ liệu cần thiết được Google sử dụng để tạo mã vạch Motics và tìm nạp Dịch vụ vé điện tử VDV chứng chỉ. Tham khảo transitObject và API transitObject.Patch tài liệu để biết danh sách đầy đủ các thông số (không phải Motics) và nhiều thông tin chi tiết khác.

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

Biểu diễn dưới dạng JSON

Quy trình tích hợp Motics yêu cầu bản trình bày sau đây của transitObject trong nội dung yêu cầu transitObject:patch. Lưu ý rằng mã ở trạng thái này điểm mà trường applicationData được điền sẵn.

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

Quy cách dữ liệu ứng dụng

Sau đây là đặc tả Motics cho nội dung của applicationData (thẻ:0x5F07). applicationData phải được tạo bởi trình tích hợp hệ thống ở định dạng độ dài thẻ (TLV). Dữ liệu này sẽ xuất hiện sau được gói gọn trong một cấu trúc dữ liệu lớn hơn để cuối cùng được mã hoá dưới dạng một phần của mã QR .

Thẻ	Thời lượng	Giá trị
`0x9E`	81 80	Chữ ký `OctetString`, 128 byte đầu tiên của dữ liệu về quyền đã ký Cụm từ của Google: `sigSTB`
`0x9A`	Thay đổi	Dữ liệu còn lại `OctetString`, dữ liệu quyền còn lại Cụm từ của Google: `sigSTB cont.`
`0x7F21`	81 C8	Chứng chỉ cấp `OctetString`, dữ liệu chứng chỉ Cụm từ của Google: `Cert(puk_SAM)`
`0x42`	08	Tham chiếu tổ chức phát hành chứng chỉ (CAR) `OctetString`, giá trị CAR Cụm từ của Google: `CAR`