Hầu hết các thẻ và vé mà bạn có thể phát hành để người dùng cuối lưu vào Google Wallet đều được xác định bằng hai thành phần: Lớp thẻ và vé và Đối tượng thẻ và vé. Bất cứ khi nào phát hành thẻ/vé cho người dùng, bạn sẽ cần một phiên bản của cả Danh mục thẻ/vé và Đối tượng thẻ/vé. Phiên bản này sẽ cho Google Wallet API biết loại thẻ/vé cần tạo, cũng như thông tin chi tiết cần hiển thị trên thẻ/vé, chẳng hạn như giá trị của thẻ quà tặng hoặc tên của người giữ vé.
Google Wallet API cung cấp một bộ Lớp thẻ và vé cũng như Đối tượng thẻ và vé được xác định trước mà bạn tạo các thực thể, sau đó dùng để tạo thẻ và vé được phát hành cho người dùng, chẳng hạn như GiftCardClass và GiftCardObject, GenericClass và GenericObject, cùng nhiều loại khác.
Mỗi thực thể Lớp thẻ và Đối tượng thẻ được xác định là một đối tượng JSON, có một tập hợp các thuộc tính bắt buộc và không bắt buộc tương ứng với trường hợp sử dụng cụ thể dành cho loại thẻ đó.
Danh mục thẻ và vé
Hãy coi Lớp thẻ và vé là một mẫu dùng chung để tạo một hoặc nhiều thẻ và vé mà bạn sẽ phát hành cho người dùng. Lớp Thẻ và vé xác định một nhóm thuộc tính chung sẽ được đưa vào tất cả thẻ và vé tham chiếu đến lớp đó.
Ví dụ: phiên bản EventTicketClass sau đây xác định các trường thường gặp trong tất cả vé đã phát hành cho một sự kiện sắp diễn ra(địa điểm, tên sự kiện, đơn vị phát hành, ngày/giờ).
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"eventName": {
"defaultValue": {
"language": "en-US",
"value": "Google Live"
}
},
"venue": {
"name": {
"defaultValue": {
"language": "en-US",
"value": "Shoreline Amphitheater"
}
},
"address": {
"defaultValue": {
"language": "en-US",
"value": "ADDRESS_OF_THE_VENUE"
}
}
},
"dateTime": {
"start": "2023-04-12T11:30"
},
"reviewStatus": "UNDER_REVIEW"
}
Mỗi phiên bản của Lớp thẻ và vé đều yêu cầu một thuộc tính id mà bạn chỉ định. Mã lớp này đóng vai trò là giá trị nhận dạng duy nhất mà bạn sẽ tham chiếu bất cứ khi nào bạn sử dụng mã này để tạo một phiên bản Đối tượng thẻ và vé mới.
Đối tượng thẻ và vé
Mặc dù một thực thể của Lớp thẻ/vé chỉ định một tập hợp các thuộc tính dùng chung sẽ được sử dụng trong một hoặc nhiều thẻ/vé, nhưng Đối tượng thẻ/vé chỉ định thông tin chi tiết riêng của một thẻ/vé cụ thể được phát hành cho một người dùng cụ thể.
Ví dụ: khi bạn tạo Thẻ vé sự kiện bằng Google Wallet API, một phiên bản EventTicketObject sẽ bao gồm các thuộc tính cho ghế được chỉ định cho vé đó vì những giá trị này sẽ là duy nhất đối với mỗi vé được phát hành.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Mỗi phiên bản của Đối tượng thẻ và vé đều yêu cầu một thuộc tính id mà bạn chỉ định. Object ID này đóng vai trò là giá trị nhận dạng riêng biệt mà bạn sẽ tham chiếu khi phát hành thẻ và vé cho người dùng.
Cách lớp thẻ và vé hoạt động với đối tượng thẻ và vé
Đối tượng Thẻ và vé phải mở rộng một thực thể của Lớp thẻ và vé bằng cách tham chiếu đến Mã nhận dạng lớp hoặc bao gồm định nghĩa đầy đủ về Lớp thẻ và vé. Mối quan hệ này giữa một thực thể Lớp thẻ và thực thể Đối tượng thẻ có nghĩa là bạn có thể đặt và cập nhật các thuộc tính chung cho tất cả thẻ đã phát hành thông qua thực thể Lớp thẻ, cũng như các thuộc tính riêng cho từng thẻ trong thực thể Đối tượng thẻ.
Ví dụ: sơ đồ sau đây về một thẻ Vé sự kiện đơn giản cho thấy cách các trường được xác định trong EventTicketClass dùng chung và các trường cho một vé cụ thể được xác định trong EventTicketObject kết hợp để tạo thành thẻ cuối cùng được phát hành. Lưu ý cách mã nhận dạng của Lớp thẻ/vé được tham chiếu trong thuộc tính classId của Đối tượng thẻ/vé.
Các thay đổi đối với một thực thể Passes Class sẽ được truyền ngay lập tức trên tất cả các thực thể Passes Object tham chiếu đến thực thể đó. Người dùng sẽ thấy mọi thay đổi mà bạn thực hiện đối với một thực thể Lớp thẻ và vé được phản ánh trên thẻ và vé trong ứng dụng Google Wallet vào lần đồng bộ hoá tiếp theo.
Thêm thẻ/vé vào Google Wallet của người dùng
Để thêm thẻ/vé vào Google Wallet của người dùng, bạn tạo một Mã thông báo Web JSON (JWT) chứa các xác nhận quyền sở hữu mà bạn (tổ chức phát hành) đang thực hiện về phiên bản Đối tượng thẻ/vé sẽ được lưu trong Google Wallet của người dùng – quan trọng nhất là Mã đối tượng của phiên bản Đối tượng thẻ/vé mà bạn đang phát hành cho người dùng. Sau đó, JWT sẽ được gửi đến người dùng thông qua nút Thêm vào Google Wallet hoặc đường liên kết Thêm vào Google Wallet.
Sau khi người dùng nhấp vào nút hoặc đường liên kết để thêm thẻ/vé đã phát hành vào Google Wallet, một đường liên kết đến thực thể Passes Object được mã hoá trong JWT sẽ được liên kết với Tài khoản Google của người dùng đó. Điều này có nghĩa là khi người dùng nhấp lại vào nút, một đường liên kết đã tồn tại đến Đối tượng thẻ/vé đó, vì vậy, các bản sao trùng lặp sẽ không được thêm vào ví của người dùng.
Nếu người dùng xoá một thẻ/vé khỏi ứng dụng Google Wallet, thì phiên bản Passes Object tương ứng sẽ tự động bị huỷ liên kết với người dùng, nhưng không bị xoá. Điều này có nghĩa là người dùng có thể nhấp lại vào nút hoặc đường liên kết Thêm vào Google Wallet để lưu thẻ và vé mà không cần tạo một phiên bản Passes Object hoặc JWT mới.