Halaman ini diterjemahkan oleh Cloud Translation API.

Detail teknis untuk tiket Motics di Google Wallet

Halaman ini memberikan detail teknis Operator Transportasi Umum (PTO) dan integrator sistem mereka harus berintegrasi dengan Google untuk menyediakan tiket Motics di Google Wallet. Solusi ini memanfaatkan Google Wallet API dan juga mengandalkan di PTO yang menerapkan endpoint aktivasi.

Arsitektur Sistem

Bagian ini menampilkan arsitektur sistem dan alur penyimpanan Motics.

Gambar 1. Alur Penyimpanan Tiket Motics

Gambar 1 menunjukkan alur untuk membuat, mengaktifkan, dan menyematkan tiket Motics di Google Wallet, di beberapa entitas:

Server Google
Server PTO (Integrator Sistem)
Server SCE Motics
Toko web

Berikut ini menjelaskan alur tersebut secara lebih detail:

Pada fase penyiapan awal, server PTO membuat transitClass, meneruskan ownerId dan activationUrl menggunakan transitClass:Insert Endpoint Google Wallet API. Kegiatan ini hanya dilakukan satu kali.
Selanjutnya, ketika pengguna membeli tiket dari toko web, server PTO memanggil transitObject:Insert yang berisi informasi dasar tiket dan beberapa isian awal yang menunjukkan bahwa ini adalah tiket Motics.
Kemudian server PTO dan toko web bekerja sama untuk merender Tombol Tambahkan ke Google Wallet dan pada akhirnya kembalikan JWT tiket ke Google, menggunakan link simpan.
Sekarang fase penyematan tiket dapat dimulai, saat server Google memanggil Endpoint Aktivasi di belakang activationUrl.
Sebagai respons terhadap Langkah 4, server PTO menghasilkan tanda tangan (sigSTB) berisi SCE_ID yang ditandatangani dengan SAM.
Sebelum merespons panggilan activationUrl, server PTO harus terlebih dahulu panggil transitObject:Patch yang berisi semua informasi Motics yang diperlukan, termasuk applicationData Motics.
Hanya setelah panggilan transitObject:Patch berhasil, PTO server harus mengembalikan respons sukses (HTTP-200) ke activationUrl panggilan telepon.

Implementasikan Pindahkan & Alur Batalkan Penautan

Untuk memberikan pengalaman pengguna yang baik, pengguna harus dapat memindahkan Motic mereka tiket dari satu perangkat ke perangkat lain, dalam batas tertentu yang ditentukan oleh penerbit. Untuk hal ini, penerbit harus menerapkan Alur Pemindahan dan Membatalkan Tautan.

Endpoint Aktivasi

Penerbit/PTO (atau integrator sistemnya) perlu mengimplementasikan tiket endpoint aktivasi yang akan dipanggil Google saat tiket disimpan. URL ke endpoint ini harus diberikan dalam pemanggilan transitClass:Insert. Endpoint aktivasi akan menghasilkan tanda tangan (sigSTB) dan memanggil metode transitObject:Patch dengan parameter yang ditentukan dalam tabel berikut bagian.

Permintaan

Permintaan ke endpoint aktivasi memiliki format berikut:

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

Respons

Respons sukses HTTP-200 dengan isi kosong harus ditampilkan jika:

sigSTB yang berisi SCE_ID telah dibuat dan ditandatangani dengan SAM
Metode transitObject:Patch berhasil dipanggil

Status: 200 - OK
Body: {}

Target Latensi

Endpoint aktivasi harus mematuhi target latensi berikut:

Minimal 50% dari semua permintaan harus direspons dalam 200ms
Minimal 95% dari semua permintaan harus direspons dalam 2s
Ada batas atas tetap sebesar 10s

Perubahan Google Wallet API

Berikut penjelasan tentang perubahan pada endpoint Google Wallet API untuk mendukung Motics seperti yang diuraikan dalam arsitektur sistem.

Metode: transitClass:insert

Ini adalah endpoint Google Wallet API untuk membuat transitClass di backend. Integrator sistem perlu memanggil API ini dengan perintah parameter permintaan bersama dengan kolom lain yang berlaku. Rujuk ke transitClass & Dokumentasi API transitClass.Insert untuk daftar lengkap (non-Motics) dan detail selengkapnya.

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

Representasi JSON

Integrasi Motics memerlukan setidaknya representasi JSON berikut dari transitClass dalam isi permintaan transitClass:insert. Wajib lainnya transitClass kolom metadata juga harus ditetapkan.

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

Jika certEnvironment = PRODUCTION, server Google akan mengambil sertifikat dari server Motics produksi. Kapan certEnvironment = STAGING Google server akan mengambil sertifikat dari server sandbox Motics.

Metode: transitObject:insert

Ini adalah endpoint Google Wallet API untuk menyisipkan transitObject dalam tiket yang ingin dibeli dan ditambahkan pengguna ke Google Wallet. Sistem integrator harus meneruskan transitObject terutama yang berisi informasi tiket di di titik ini. Lihat transitObject & API transitObject.Insert untuk daftar lengkap parameter (non-Motics) dan detail selengkapnya.

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

Representasi JSON

Integrasi Motics memerlukan setidaknya representasi JSON berikut dari transitObject dalam isi permintaan transitObject:insert. Objek lainnya isian {i>metadata<i} dapat diatur juga dan semua isian wajib lainnya juga harus disertakan.

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

Catatan:

API mengharuskan kolom applicationData disertakan. Pada tahap ini dalam alur aktivasi Motics, nilai applicationData belum diketahui, jadi harus diatur ke string kosong.
- applicationData akan ditetapkan nanti di transitObject:Patch panggilan telepon.
Objek DateTime validTimeInterval harus memiliki offset zona waktu tentukan, misalnya: 2024-04-12T19:20:50.52-04:00.

Metode: transitObject:patch

Ini adalah endpoint Google Wallet API untuk mem-patch transitObject dengan data menjadi digunakan oleh Google untuk pembuatan kode batang Motics dan pengambilan Layanan VDV eTicket CA {i>root<i}. Lihat transitObject & API transitObject.Patch untuk daftar lengkap parameter (non-Motics) dan detail selengkapnya.

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

Representasi JSON

Integrasi Motics memerlukan representasi representasi transitObject dalam isi permintaan transitObject:patch. Perhatikan bahwa pada titik bahwa kolom applicationData telah diisi.

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

Spesifikasi Data Aplikasi

Berikut adalah spesifikasi Motics untuk konten applicationData (tag:0x5F07). applicationData harus dibuat oleh integrator sistem dalam format {i>tag-length-value<i} (TLV). Data ini nantinya dienkapsulasi dalam struktur data yang lebih besar untuk akhirnya dikodekan sebagai bagian dari pada kode sumber.

Tag	Durasi	Nilai
`0x9E`	81 80	Tanda tangan `OctetString`, 128 byte pertama data hak yang ditandatangani Persyaratan Google: `sigSTB`
`0x9A`	Bervariasi	Data residu `OctetString`, data hak residu Persyaratan Google: `sigSTB cont.`
`0x7F21`	81 C8	Sertifikat penerbitan `OctetString`, data sertifikat Persyaratan Google: `Cert(puk_SAM)`
`0x42`	08	Referensi Certificate Authority (CAR) `OctetString`, nilai CAR Persyaratan Google: `CAR`