Hầu hết thẻ và vé mà bạn có thể cấp cho người dùng cuối để lưu trong Google Wallet đều được xác định bởi 2 thành phần: Lớp thẻ và vé và Đối tượng thẻ và vé. Bất cứ khi nào cấp thẻ và vé cho người dùng, bạn sẽ cần một bản sao của cả Lớp thẻ và vé và Đối tượng thẻ và vé. Đối tượng này cho API Google Wallet biết loại thẻ và vé cần tạo, cũng như các thông tin chi tiết cần hiển thị trên thẻ và vé, chẳng hạn như giá trị của thẻ quà tặng hoặc tên chủ vé.
Google Wallet API cung cấp một nhóm các Đối tượng thẻ và vé được xác định trước mà bạn tạo thực thể, sau đó dùng để tạo thẻ và vé được cấp cho người dùng, chẳng hạn như GiftCardClass và GiftCardObject, GenericClass và GenericObject và các đối tượng khác.
Mỗi thực thể của Lớp thẻ và vé được định nghĩa là một đối tượng JSON. Đối tượng này 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ẻ và vé đó.
Lớp thẻ và vé
Hãy coi Lớp thẻ và vé là một mẫu chung được dùng để tạo một hoặc nhiều thẻ và vé mà bạn sẽ cấp cho người dùng của mình. Lớp thẻ và vé xác định một tập hợp các thuộc tính chung sẽ được đưa vào trong tất cả các lần truyền tham chiếu đến hàm đó.
Ví dụ: ví dụ sau đây của EventTicketClass xác định các trường chung cho tất cả vé đã phát hành cho một sự kiện sắp tới(địa điểm tổ chức, tên sự kiện, nhà 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 thực thể của một Lớp thẻ và vé cần có một thuộc tính id do 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 dùng mã này để tạo Đối tượng thẻ và vé mới
thực thể.
Đối tượng thẻ và vé
Mặc dù thực thể của Lớp thẻ và 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ì Đối tượng thẻ và vé sẽ chỉ định các thông tin chi tiết duy nhất của một thẻ và vé cụ thể được cấp cho một người dùng cụ thể.
Ví dụ: khi tạo một vé xem sự kiện bằng API Google Wallet, EventTicketObject
thực thể bao gồm các cơ sở lưu trú cho chỗ đã được chỉ định cho vé đó vì các giá trị đó sẽ là duy nhất cho mỗi chỗ ngồi
phiếu yêu cầu hỗ trợ đượ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 thực thể của Đối tượng thẻ và vé cần có một thuộc tính id do bạn chỉ định. Mã đối tượng này
đóng vai trò là giá trị nhận dạng riêng biệt mà bạn sẽ tham chiếu khi cấp thẻ/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ã lớp của lớp đó hoặc thêm định nghĩa đầy đủ về Lớp thẻ và vé. Mối quan hệ giữa Lớp thẻ và vé và thực thể Đối tượng thẻ và vé tức là bạn có thể thiết lập và cập nhật các thuộc tính chung cho tất cả thẻ và vé được phát hành thông qua phiên bản Lớp thẻ và vé, và thuộc tính dành riêng cho một lượt truyền hình riêng lẻ trong thực thể Đối tượng thẻ và vé.
Ví dụ: sơ đồ sau đây về một vé xem 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 của một vé cụ thể được xác định trong EventTicketObject kết hợp để tạo thành thẻ và vé đã phát hành chính thức. Lưu ý cách mã nhận dạng của Lớp thẻ và vé được tham chiếu trong thuộc tính classId của Đối tượng thẻ và vé.
Các thay đổi được thực hiện đối với một thực thể Lớp thẻ và vé sẽ được áp dụng ngay lập tức trên mọi thực thể Đối tượng thẻ và vé tham chiếu đến nó. Người dùng sẽ thấy mọi thay đổi mà bạn thực hiện đối với một phiên bản 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é vào Google Wallet của người dùng
Để thêm thẻ và vé vào Google Wallet của người dùng, bạn phải tạo một Mã thông báo web JSON (JWT) chứa các thông báo xác nhận quyền sở hữu bạn (tổ chức phát hành) đang thực hiện liên quan đến phiên bản Đối tượng thẻ và 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 thực thể Đối tượng thẻ và vé mà bạn đang cấp cho người dùng. JWT sau đó sẽ được gửi đến người dùng thông qua nút Thêm vào Google Wallet hoặc 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à vé đã phát hành vào Google Wallet của họ, đường liên kết Truyền thực thể Đối tượng được mã hoá trong JWT đượ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 này, đã có một đường liên kết đến Đối tượng thẻ và vé đó, vì vậy, hệ thống sẽ trùng lặp bản sao sẽ không được thêm vào ví của người dùng.
Nếu người dùng xoá thẻ và vé khỏi ứng dụng Google Wallet, thì thực thể tương ứng của Đối tượng thẻ và vé sẽ là tự động huỷ liên kết khỏ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 vào Nút hoặc đường liên kết Thêm vào Google Wallet một lần nữa để lưu thẻ và vé mà không cần thực thể mới của Đối tượng thẻ và vé (JWT) sẽ được tạo.