Tổng quan

API Thẻ và vé của Google Wallet cho phép đối tác chỉ định một điểm cuối để kích hoạt vé đi phương tiện công cộng. Khi cần kích hoạt, nút "Kích hoạt" sẽ hiển thị cho người dùng. Khi người dùng nhấn vào, nút này sẽ gọi điểm cuối được chỉ định bằng các tham số được mô tả bên dưới. Điểm cuối phải đảm bảo rằng thẻ/vé có thông tin đổi thưởng hợp lệ (kiểm tra bằng mã vạch hoặc bằng hình ảnh) trước khi trả lại. Khi đó, thẻ/vé trong Wallet của người dùng sẽ được cập nhật để hiển thị thông tin đổi thưởng. Xin lưu ý rằng trước khi kích hoạt, mọi thông tin đổi thưởng hiện có sẽ không hiển thị.

API Kích hoạt

Điểm cuối kích hoạt được chỉ định trong API bằng cách sử dụng activationOptions trên lớp chuyển tiếp. Đối tác chịu trách nhiệm duy trì một điểm cuối kích hoạt đang hoạt động với độ trễ hợp lý.

  activationOptions: {
    activationUrl: string
  }
Trường Nội dung mô tả
activationUrl

string

URL dành cho điểm cuối của đối tác sẽ được gọi để yêu cầu kích hoạt. URL phải được lưu trữ trên HTTPS và tệp robots.txt phải cho phép UserAgent:Google-Valuables truy cập được vào đường dẫn URL.

Trạng thái kích hoạt được lưu trữ trên đối tượng bằng trường activationStatus. Trạng thái hợp lệ bao gồm NOT_ACTIVATED và ACTIVATED. Điểm cuối kích hoạt phải cập nhật trạng thái ACTIVATED cho đối tượng, đồng thời đảm bảo đối tượng có thông tin sử dụng hợp lệ, chẳng hạn như mã vạch hoặc thông số kiểm tra bằng hình ảnh. Bạn có thể dùng trường deviceContext để ghim thiết bị.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Trường Nội dung mô tả
activationStatus

enum (ActivationStatus)

Trạng thái kích hoạt cho đối tượng phương tiện công cộng này. Trạng thái này sẽ thay đổi cách thể hiện của phiếu yêu cầu hỗ trợ và cho phép người dùng thực hiện hành động. Ví dụ: nút Kích hoạt sẽ hiển thị trên thông tin về phiếu yêu cầu hỗ trợ nếu bạn đặt giá trị này là NOT_ACTIVATED.

Các giá trị được chấp nhận là:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Ngữ cảnh thiết bị để liên kết với đối tượng. Nếu được đặt, thông tin đổi thưởng sẽ chỉ được trả về thiết bị đã cho.
hasLinkedDevice

boolean

Liệu đối tượng này hiện có được liên kết với một thiết bị duy nhất hay không.
DeviceContext
Trường Nội dung mô tả
deviceToken

string

Nếu được đặt, thông tin đổi thưởng sẽ chỉ được trả về thiết bị đã cho khi kích hoạt đối tượng. Không thể sử dụng giá trị này làm giá trị nhận dạng ổn định để theo dõi thiết bị của người dùng. Thuộc tính này có thể thay đổi giữa nhiều thẻ và vé trên cùng một thiết bị hoặc thậm chí là theo nhiều lần kích hoạt trên cùng một thiết bị. Khi đặt giá trị này, phương thức gọi cũng phải đặt hasLinkedDevice trên đối tượng đang được kích hoạt.

Lưu ý rằng deviceToken nhận được từ trường deviceContext tham số kích hoạt

Ghim thiết bị

Ghim thiết bị là tính năng cho phép người dùng kích hoạt vé trên một thiết bị và chỉ hiển thị thông tin về việc sử dụng vé trên thiết bị đó. Thuộc tính này tách biệt với multipleDevicesAndHoldersAllowedStatus của ONE_USER_ONE_DEVICE, vì phương thức này chỉ cho phép hiển thị vé trên một thiết bị duy nhất. Bạn nên sử dụng trạng thái ONE_USER_ALL_DEVICES với tính năng ghim thiết bị.

Trước khi kích hoạt, người dùng có thể xem phiếu yêu cầu hỗ trợ và nút kích hoạt trên mọi thiết bị của họ. Sau khi được kích hoạt và ghim vào một thiết bị, thiết bị đã ghim sẽ hiển thị thông tin đổi thưởng, còn các thiết bị khác sẽ hiển thị nút kích hoạt để cho phép người dùng chuyển vé sang một thiết bị khác. Nếu bạn không muốn dùng chức năng di chuyển phiếu yêu cầu hỗ trợ nhưng được kích hoạt trên bất kỳ thiết bị nào, thì trong quá trình kích hoạt, bạn có thể cập nhật phiếu yêu cầu hỗ trợ đó thành ONE_USER_ONE_DEVICE thay vì sử dụng tính năng ghim thiết bị.

Để triển khai tính năng ghim thiết bị, bạn phải cập nhật đối tượng bằng trường deviceToken mà hệ thống nhận được bằng thông số kích hoạt cũng như đặt hasLinkedDevice thành true trong cùng một lệnh gọi API. Nếu muốn, bạn có thể huỷ liên kết vé đó khỏi một thiết bị bằng cách đặt hasLinkedDevice thành false trong một lệnh gọi API trong tương lai.

sơ đồ trình tự cho thao tác ghim thiết bị

Thông số kích hoạt

Yêu cầu gửi đến điểm cuối kích hoạt sẽ chứa các thông số sau.

Ví dụ về JSON: 

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

Giá trị nhận dạng Nội dung mô tả
classId

Mã lớp đủ điều kiện. Sử dụng định dạng sau:

<issuer_id.class_id>
objectIds

Mảng mã đối tượng đủ điều kiện sử dụng định dạng sau:

<issuer_id.object_id>
expTimeMillis Thời gian hết hạn tính bằng mili giây kể từ EPOCH. Sau thời gian hết hạn, thông báo cần được coi là không hợp lệ.
eventType Luôn là "activate".
nonce Số chỉ dùng một lần để theo dõi mọi gói phân phối trùng lặp.
deviceContext

Mã nhận dạng duy nhất do Google tạo, đại diện cho thiết bị mà người dùng đang thực hiện hành động. Bạn nên sử dụng mã nhận dạng này khi thực hiện các bản cập nhật liên kết một đối tượng với một thiết bị.

Mã nhận dạng này có thể không cố định đối với các yêu cầu sau này từ một thiết bị cụ thể.