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