Tổng quan

API Thẻ và vé của Google Wallet cho phép các đối tác chỉ định một điểm cuối cho 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ị dành cho người dùng mà khi nhấn vào 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ệ (mã vạch hoặc kiểm tra 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 về việc đổi thưởng. Xin lưu ý rằng trước khi kích hoạt, mọi hoạt động sử dụng ưu đãi hiện có sẽ không được 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 phương tiện. Đối tác chịu trách nhiệm duy trì một điểm cuối kích hoạt hoạt động bằng độ trễ hợp lý.

  activationOptions: {
    activationUrl: string
  }
Trường Mô tả
activationUrl

string

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

Trạng thái kích hoạt được lưu trữ trên đối tượng bằng cách sử dụng trường activationStatus. Các trạng thái hợp lệ bao gồm NOT_ACTIVATED và ACTIVATED. Kích hoạt phải cập nhật đối tượng với trạng thái ACTIVATED cũng như đảm bảo đối tượng có thông tin đổi thưởng hợp lệ như mã vạch hoặc thông số kiểm tra bằng hình ảnh. Chiến lược phát hành đĩa đơn Trường deviceContext có thể dùng để ghim thiết bị.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Trường Mô tả
activationStatus

enum (ActivationStatus)

Trạng thái kích hoạt cho đối tượng chuyển tuyến 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 thao tác; ví dụ: nút Kích hoạt sẽ xuất hiện trên thông tin chi tiết về phiếu yêu cầu hỗ trợ nếu giá trị này được đặt thành 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ó liên kết với một thiết bị nào hay không.
DeviceContext
Trường Mô tả
deviceToken

string

Nếu bạn đặt chính sách này, thông tin đổi thưởng sẽ chỉ được trả về thiết bị đã cho khi kích hoạt của đối tượng. Bạn không thể 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. Nó có thể thay đổi giữa nhiều thẻ và vé cho cùng một thiết bị hoặc thậm chí trên các thiết bị khác nhau cho cùng một thiết bị. Khi bạn đặt chế độ cài đặt này, người gọi cũng phải đặt hasLinkedDevice trên đối tượng đang được kích hoạt.

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

Ghim thiết bị

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

Trước khi kích hoạt, người dùng có thể xem vé và nút kích hoạt trên bất kỳ thiết bị nào mà họ của bạn. Sau khi được kích hoạt và ghim vào một thiết bị, thiết bị được ghim sẽ hiển thị thông tin về việc đổi thưởng và 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 vé khác thiết bị. Nếu bạn không muốn thao tác di chuyển vé nhưng bạn có thể kích hoạt vé trên một thiết bị bất kỳ, thì có thể cập nhật phiếu yêu cầu hỗ trợ trong quá trình kích hoạt thành ONE_USER_ONE_DEVICE thay vì so với việc 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 nhận được cùng với 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. Sau đó, nếu muốn, vé có thể bị huỷ liên kết 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ự ghim thiết bị

Tham số kích hoạt

Yêu cầu tới điểm cuối kích hoạt sẽ chứa các tham 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”
  }

Số nhận dạng 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 bất kỳ tệp phân phối trùng lặp nào.
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 cập nhật để liên kết một đối tượng với thiết bị.

Mã này có thể không cố định cho các yêu cầu trong tương lai từ một thiết bị cụ thể.