Ringkasan

Google Wallet Passes API memungkinkan partner menentukan endpoint untuk aktivasi tiket transportasi umum. Saat aktivasi diperlukan, tombol “Aktifkan” akan ditampilkan untuk pengguna, yang ketika diketuk akan memanggil endpoint yang ditentukan dengan parameter yang dijelaskan di bawah. Endpoint harus memastikan bahwa kartu memiliki informasi penukaran yang valid (kode batang atau pemeriksaan visual) sebelum kembali. Pada saat itu, kartu di Wallet pengguna akan diperbarui untuk menampilkan informasi penukaran. Perlu diperhatikan bahwa sebelum aktivasi, informasi penukaran yang ada tidak akan ditampilkan.

Aktivasi API

Endpoint aktivasi ditentukan dalam API menggunakan activationOptions di class transportasi umum. Partner bertanggung jawab untuk mempertahankan endpoint aktivasi yang berfungsi dengan latensi yang wajar.

  activationOptions: {
    activationUrl: string
  }
Kolom Deskripsi
activationUrl

string

URL untuk endpoint partner yang akan dipanggil untuk permintaan aktivasi. URL harus dihosting di HTTPS dan robots.txt harus mengizinkan jalur URL dapat diakses oleh UserAgent:Google-Valuables.

Status aktivasi disimpan pada objek menggunakan kolom activationStatus. Status yang valid termasuk NOT_ACTIVATED dan ACTIVATED. Endpoint aktivasi harus memperbarui objek dengan status ACTIVATED serta memastikan objek memiliki informasi penukaran yang valid seperti kode batang atau parameter inspeksi visual. Kolom deviceContext dapat digunakan untuk penyematan perangkat.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Kolom Deskripsi
activationStatus

enum (ActivationStatus)

Status aktivasi untuk objek transportasi umum ini. Status ini akan mengubah representasi tiket dan memungkinkan pengguna mengambil tindakan; misalnya, tombol Aktifkan akan dirender pada detail tiket jika ditetapkan sebagai NOT_ACTIVATED.

Nilai yang dapat diterima adalah:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Konteks perangkat yang akan digunakan untuk mengaitkan objek. Jika ditetapkan, informasi penukaran hanya akan dikembalikan ke perangkat yang ditentukan.
hasLinkedDevice

boolean

Apakah objek ini saat ini ditautkan ke satu perangkat.
DeviceContext
Kolom Deskripsi
deviceToken

string

Jika ditetapkan, informasi penukaran hanya akan dikembalikan ke perangkat yang diberikan setelah objek diaktifkan. ID ini tidak dapat digunakan sebagai ID yang stabil untuk melacak perangkat pengguna. Nilai ini dapat berubah di berbagai kartu yang berbeda untuk perangkat yang sama, atau bahkan di berbagai aktivasi untuk perangkat yang sama. Saat menyetelnya, pemanggil juga harus menetapkan hasLinkedDevice pada objek yang diaktifkan.

Perhatikan bahwa deviceToken diterima dari kolom deviceContext parameter aktivasi

Penyematan perangkat

Penyematan perangkat adalah fitur yang memungkinkan pengguna mengaktifkan tiket di satu perangkat dan menampilkan informasi penukaran tiket hanya di perangkat tersebut. Ini terpisah dengan multipleDevicesAndHoldersAllowedStatus dari ONE_USER_ONE_DEVICE, yang hanya memungkinkan tiket ditampilkan di satu perangkat. Sebaiknya gunakan status ONE_USER_ALL_DEVICES dengan pemasangan pin pada perangkat.

Sebelum aktivasi, pengguna dapat melihat tiket dan tombol pengaktifan di perangkat apa pun yang mereka miliki. Setelah diaktifkan dan disematkan ke perangkat, perangkat yang disematkan akan menampilkan informasi penukaran dan perangkat lain akan menampilkan tombol aktifkan untuk memungkinkan pengguna memindahkan tiket ke perangkat lain. Jika memindahkan tiket bukan fungsi yang diinginkan, tetapi mengaktifkannya di perangkat apa pun, Anda dapat memperbarui tiket selama aktivasi ke ONE_USER_ONE_DEVICE daripada menggunakan pemasangan pin di perangkat.

Untuk menerapkan penyematan perangkat, objek harus diperbarui dengan kolom deviceToken yang diterima dengan parameter aktivasi serta menyetel hasLinkedDevice ke benar dalam panggilan API yang sama. Jika diinginkan, tiket tersebut kemudian dapat dibatalkan tautannya dari perangkat dengan menetapkan hasLinkedDevice ke salah dalam panggilan API mendatang.

diagram urutan untuk penyematan perangkat

Parameter aktivasi

Permintaan ke endpoint aktivasi akan berisi parameter berikut.

Contoh JSON: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

ID Deskripsi
classId

ID class yang sepenuhnya memenuhi syarat. Menggunakan format berikut:

<issuer_id.class_id>
objectIds

Array ID objek yang sepenuhnya memenuhi syarat yang menggunakan format berikut:

<issuer_id.object_id>
expTimeMillis Waktu habis masa berlaku dalam milidetik sejak EPOCH. Setelah masa berlaku habis, pesan harus dianggap tidak valid.
eventType Selalu "activate".
nonce Nonce untuk melacak setiap pengiriman duplikat.
deviceContext

ID unik yang dibuat oleh Google, mewakili perangkat yang digunakan pengguna untuk melakukan tindakan. ID ini harus digunakan saat melakukan pembaruan yang mengaitkan objek ke perangkat.

ID ini mungkin tidak konstan untuk permintaan mendatang dari perangkat tertentu.