Quy trình phát triển thẻ và vé trong Google Wallet
Google Wallet API cung cấp một tập hợp các loại thẻ và vé được xác định trước được tối ưu hoá cho các trường hợp sử dụng cụ thể, chẳng hạn như thẻ quà tặng, thẻ lên máy bay, vé xem sự kiện, v.v. Ngoài ra, còn có một loại thẻ và vé chung dành cho các trường hợp sử dụng không có loại thẻ và vé cụ thể.
Bài viết này nhằm giúp bạn làm quen với các bước cơ bản cần thiết để tạo và cấp thẻ và vé bằng Google Wallet API. Có nhiều cách để thực hiện một số bước được nêu chi tiết bên dưới, nhưng ở cấp độ cao, tất cả loại thẻ và vé đều được tạo bằng cách tuân theo cùng một quy trình phát triển cơ bản.
Để biết hướng dẫn chi tiết về cách tạo thẻ và vé, hãy xem hướng dẫn về web, email và SMS hoặc ứng dụng Android.
![](https://developers.google.cn/static/wallet/images/ticket-class.png?authuser=0000&%3Bhl=vi&hl=vi)
1. Tạo một lớp Thẻ và vé
Ý nghĩa
Lớp thẻ và vé xác định một tập hợp các thuộc tính phổ biến trong nhiều thẻ và vé, tương tự như một mẫu. Ví dụ: nếu bạn phát hành vé cho một sự kiện, Lớp thẻ và vé sẽ xác định các trường giống nhau cho tất cả các vé, chẳng hạn như tên, ngày và giờ của sự kiện.
Mỗi thẻ và vé bạn cấp phải tham chiếu đến một Lớp thẻ và vé. Bạn cũng phải chỉ định một mã nhận dạng duy nhất cho mỗi Lớp thẻ và vé mà bạn tạo và được dùng để tham chiếu đến mã này khi tạo thẻ và vé.
Cách thực hiện
Lớp thẻ và vé được định nghĩa ở định dạng JSON và có thể được tạo bằng API REST của Google Wallet, SDK Android hoặc trong Google Wallet Business Console.
Ví dụ về loại thẻ và vé
{ "id": "ISSUER_ID.EVENT_CLASS_ID", "issuerName": "[TEST ONLY] Heraldic Event", "localizedIssuerName": { "defaultValue": { "language": "en-US", "value": "[TEST ONLY] Heraldic Event" } }, "logo": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "LOGO_IMAGE_DESCRIPTION" } } }, "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", "hexBackgroundColor": "#264750", "heroImage": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "HERO_IMAGE_DESCRIPTION" } } } }
![](https://developers.google.cn/static/wallet/images/ticket-object.png?authuser=0000&%3Bhl=vi&hl=vi)
2. Tạo một đối tượng thẻ và vé
Ý nghĩa
Đối tượng thẻ và vé xác định các thuộc tính của một thẻ và vé duy nhất sẽ được cấp cho một người dùng cụ thể. Ví dụ: Đối tượng Thẻ và vé của một vé xem sự kiện sẽ xác định các trường dành riêng cho một vé cụ thể, chẳng hạn như số chỗ ngồi hoặc mã QR của vé đó.
Khi một Đối tượng thẻ và vé được tạo, Google Wallet API sẽ lưu trữ một thẻ và vé mới và liên kết thẻ và vé đó với tài khoản của công ty phát hành. Thẻ và vé được lưu trữ này là sự kết hợp giữa các thuộc tính duy nhất của Đối tượng thẻ và vé và các thuộc tính mẫu của Lớp thẻ và vé được liên kết.
Bạn cũng phải chỉ định cho mỗi Đối tượng thẻ và vé một mã nhận dạng duy nhất, dùng để tham chiếu đến mã này khi cấp thẻ và vé.
Cách thực hiện
Đối tượng thẻ và vé là định dạng JSON được xác định và bạn có thể tạo bằng API REST của Google Wallet hoặc SDK Android.
Hiện ví dụ về đối tượng thẻ và vé
{ "id": "ISSUER_ID.OBJECT_ID", "classId": "ISSUER_ID.EVENT_CLASS_ID", "state": "ACTIVE", "seatInfo": { "seat": { "defaultValue": { "language": "en-us", "value": "5" } }, "row": { "defaultValue": { "language": "en-us", "value": "G" } }, "section": { "defaultValue": { "language": "en-us", "value": "40" } }, "gate": { "defaultValue": { "language": "en-us", "value": "3A" } } }, "barcode": { "type": "QR_CODE", "value": "BARCODE_VALUE", "alternateText": "" } }
![](https://developers.google.cn/static/wallet/images/ticket-jwt.png?authuser=0000&%3Bhl=vi&hl=vi)
3. Mã hoá thẻ và vé dưới dạng Mã thông báo web JSON (JWT)
Ý nghĩa
Để cấp thẻ và vé cho người dùng, Lớp thẻ và vé phải được mã hoá bằng Mã thông báo web JSON (JWT). Định dạng JWT là một tiêu chuẩn mở và phổ biến để thể hiện tuyên bố giữa hai bên. Trong trường hợp phát hành thẻ và vé bằng API Google Wallet, JWT được dùng để gửi yêu cầu xác nhận rằng người dùng có quyền truy cập vào một thẻ và vé cụ thể được liên kết với tài khoản của công ty phát hành thẻ.
Khi JWT được gửi đến API Google Wallet, dữ liệu đã mã hoá sẽ được dùng để xác định một thẻ và vé cụ thể và cấp cho người dùng. Nếu thẻ/vé đã được phát hành, dữ liệu này cũng giúp API Google Wallet xác định rằng thẻ/vé đó bị trùng lặp để không bị thêm vào Google Wallet của người dùng nhiều lần.
Cách thực hiện
JWT được xác định ở định dạng JSON dựa trên thông số kỹ thuật JWT. Để xác định JWT dùng để cấp thẻ và vé bằng API Google Wallet, bạn cần cung cấp thông tin về thẻ và vé mà bạn muốn cấp trong thuộc tính payload
của JWT.
Hiện ví dụ về JWT
{ "iss": "issuer@example.com", "aud": "google", "typ": "savetowallet", "iat": 1696877738, "origins": [ "www.example.com" ], "payload": { "eventTicketObjects": [ { "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX" } ] } }
![](https://developers.google.cn/static/wallet/images/ticket-jwt-signed.png?authuser=0000&%3Bhl=vi&hl=vi)
4. Ký vào JWT bằng thông tin xác thực của bạn
Ý nghĩa
Tất cả JWT được gửi đến API Google Wallet để cấp thẻ và vé đều phải được ký bằng thông tin đăng nhập mà bạn đã cung cấp trước đó trong Google Wallet Business Console. Tính năng ký sử dụng thông tin đăng nhập của bạn để mã hoá JWT sao cho thẻ và vé của bạn vẫn được bảo mật, đồng thời cho phép Google Wallet API xác thực rằng thông tin thẻ và vé được mã hoá trong đó là hợp lệ và được liên kết với tài khoản của công ty phát hành thẻ.
Cách thực hiện
Thư viện ứng dụng Google Wallet và SDK Android cung cấp các phương thức thuận tiện để ký JWT của bạn. Ngoài ra, còn có nhiều thư viện nguồn mở giúp bạn lựa chọn trong số các thư viện nguồn mở giúp xử lý tính phức tạp của việc ký mã.
Nếu bạn sử dụng API REST của Google Wallet để tạo thẻ và vé, JWT sẽ được ký bằng một khoá tài khoản dịch vụ Google Cloud. Đối với những người sử dụng SDK Android của Google Wallet, SDK sẽ tự động xử lý việc ký JWT bằng vân tay số SHA-1 của chứng chỉ ký ứng dụng.
Để bảo vệ thông tin đăng nhập, bạn chỉ nên ký JWT trên máy chủ hoặc sử dụng SDK Android của Google Wallet trong ứng dụng.
Hiện tính năng ký mã ví dụ
Java
// Create the JWT as a HashMap object HashMapclaims = new HashMap (); claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail()); claims.put("aud", "google"); claims.put("origins", Arrays.asList("www.example.com")); claims.put("typ", "savetowallet"); // Create the Google Wallet payload and add to the JWT HashMap payload = new HashMap (); payload.put("eventTicketObjects", Arrays.asList(newObject)); claims.put("payload", payload); // Google Cloud service account credentials are used to sign the JWT Algorithm algorithm = Algorithm.RSA256( null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey()); String token = JWT.create().withPayload(claims).sign(algorithm);
Node.JS
// Create the JWT claims let claims = { iss: this.credentials.client_email, aud: 'google', origins: ['www.example.com'], typ: 'savetowallet', payload: { eventTicketObjects: [newObject] }, }; // The service account credentials are used to sign the JWT let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
Python
# Create the JWT claims claims = { 'iss': self.credentials.service_account_email, 'aud': 'google', 'origins': ['www.example.com'], 'typ': 'savetowallet', 'payload': { # The listed classes and objects will be created 'eventTicketObjects': [new_object] } } # The service account credentials are used to sign the JWT signer = crypt.RSASigner.from_service_account_file(self.key_file_path) token = jwt.encode(signer, claims).decode('utf-8')
![](https://developers.google.cn/static/wallet/images/ticket-add-to-wallet.png?authuser=0000&%3Bhl=vi&hl=vi)
5. Phát hành thẻ/vé bằng nút hoặc đường liên kết "Thêm vào Google Wallet"
Ý nghĩa
Sau khi tạo JWT đã ký, bạn có thể cấp thẻ và vé cho người dùng Google Wallet! Điều này được thực hiện bằng cách hiển thị cho người dùng nút "Thêm vào Google Wallet" hoặc liên kết. Khi người dùng nhấp vào nút hoặc siêu liên kết này, JWT đã ký sẽ được gửi đến Google Wallet API. Sau đó, API này sẽ giải mã thông tin này bằng thông tin đăng nhập đã lưu của bạn. Sau khi chữ ký JWT được xác thực, thẻ/vé sẽ được cấp cho người dùng để lưu vào Google Wallet.
Cách thực hiện
Để tạo một "Thêm vào Google Wallet" dành cho ứng dụng Android, hãy sử dụng SDK Android của Google Wallet. SDK này cung cấp các phương thức để tạo nút. Đối với tất cả các nền tảng khác, bao gồm cả web, email và tin nhắn văn bản, hãy tạo một siêu liên kết theo định dạng https://pay.google.com/gp/v/save/<signed_jwt>
. Nếu có thể, tốt nhất là cung cấp liên kết này cho người dùng dưới dạng 'Thêm vào Google Wallet' .
Để biết thêm thông tin về cách sử dụng nút "Thêm vào Google Wallet" nút, hãy xem Nguyên tắc về thương hiệu của API Google Wallet
Hiện mã ví dụ
Siêu liên kết
https://pay.google.com/gp/v/save/<signed_jwt>
SDK Android
private lateinit var walletClient: PayClient private val addToGoogleWalletRequestCode = 1000 private lateinit var addToGoogleWalletButton: View override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) walletClient = Pay.getClient(this) addToGoogleWalletButton.setOnClickListener { walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode) } }
![](https://developers.google.cn/static/wallet/images/ticket-enduser-view.png?authuser=0000&%3Bhl=vi&hl=vi)
6. Xem trong Google Wallet
Sau khi người dùng lưu thẻ và vé đã phát hành, nó sẽ xuất hiện trong ứng dụng Google Wallet cùng với mọi thẻ và vé khác mà họ đã lưu.
Tạo các đối tượng truyền và lớp truyền trong JWT
Bạn có thể tạo trước lớp thẻ và vé bằng cách sử dụng API REST của Google Wallet hoặc SDK Android. Sau khi được tạo, các thẻ và vé này sẽ được dùng để cấp thẻ và vé bằng cách tham chiếu đến giấy tờ tuỳ thân của chúng.
Ngoài ra, bạn cũng có thể tạo Lớp thẻ và vé và Đối tượng thẻ và vé "đúng lúc" bằng cách nhúng trực tiếp JSON vào JWT dùng để cấp thẻ và vé cho người dùng. Trong phương thức này, các lớp thẻ và vé sẽ được API Google Wallet tạo ra khi JWT đã ký được gửi bằng lệnh "Thêm vào Google Wallet" hoặc liên kết.
Ví dụ: sau đây là một JWT có Lớp thẻ và vé mới cũng như Đối tượng thẻ và vé được xác định bằng các thuộc tính payload.eventTicketClasses
và payload.eventTicketObjects
. Lưu ý rằng những thuộc tính này là các mảng nên có thể chấp nhận một hoặc nhiều Lớp thẻ và vé hoặc Đối tượng thẻ và vé. Bạn cũng có thể chỉ định một Đối tượng thẻ và vé mới trong JWT tham chiếu đến một Lớp thẻ và vé hiện có theo mã nhận dạng.
Hiện ví dụ về JWT
{ "iss": "issuer@example.com", "aud": "google", "typ": "savetowallet", "iat": 1696877738, "origins": [ "www.example.com" ], "payload": { "eventTicketClasses": [{ "id": "ISSUER_ID.EVENT_CLASS_ID", "issuerName": "[TEST ONLY] Heraldic Event", "localizedIssuerName": { "defaultValue": { "language": "en-US", "value": "[TEST ONLY] Heraldic Event" } }, "logo": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "LOGO_IMAGE_DESCRIPTION" } } }, "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", "hexBackgroundColor": "#264750", "heroImage": { "sourceUri": { "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336" }, "contentDescription": { "defaultValue": { "language": "en-US", "value": "HERO_IMAGE_DESCRIPTION" } } } }], "eventTicketObjects": [{ "id": "ISSUER_ID.OBJECT_ID", "classId": "ISSUER_ID.EVENT_CLASS_ID", "state": "ACTIVE", "seatInfo": { "seat": { "defaultValue": { "language": "en-us", "value": "5" } }, "row": { "defaultValue": { "language": "en-us", "value": "G" } }, "section": { "defaultValue": { "language": "en-us", "value": "40" } }, "gate": { "defaultValue": { "language": "en-us", "value": "3A" } } }, "barcode": { "type": "QR_CODE", "value": "BARCODE_VALUE", "alternateText": "" } }] } }