1. Giới thiệu
Tổng quan
API Google Wallet giúp bạn tương tác với người dùng thông qua nhiều loại thẻ và vé: thẻ khách hàng thân thiết, ưu đãi, thẻ quà tặng, vé xem sự kiện, vé đi phương tiện công cộng, thẻ lên máy bay và nhiều loại thẻ khác. Mỗi loại thẻ và vé, hay còn gọi là loại thẻ và vé, đi kèm với các trường và tính năng cụ thể cho trường hợp sử dụng để nâng cao trải nghiệm người dùng.
Tuy nhiên, những đề xuất này có thể không phù hợp với mọi trường hợp sử dụng. Để tạo trải nghiệm phù hợp hơn, bạn có thể sử dụng loại thẻ và vé chung. Dưới đây là một số ví dụ về trường hợp sử dụng loại thẻ và vé chung:
- Thẻ đỗ xe
- Thẻ thành viên thư viện
- Phiếu thưởng có giá trị được lưu trữ
- Thẻ thành viên phòng tập thể dục
- Đặt chỗ
Bạn có thể sử dụng thẻ và vé chung cho mọi trường hợp sử dụng có thể được trình bày bằng:
- Tối đa 3 hàng thông tin
- (Không bắt buộc) Đồ họa mã vạch
- (Không bắt buộc) Mục Thông tin chi tiết
Để biết thêm thông tin về API Google Wallet hoặc cách thêm nút Thêm vào Google Wallet vào một trang web, vui lòng xem tài liệu dành cho nhà phát triển Google Wallet.
Truyền các lớp và đối tượng
API Google Wallet cung cấp các phương thức để tạo những nội dung sau:
Loại | Mô tả |
Lớp thẻ và vé | Mẫu cho một đối tượng truyền riêng lẻ. Lớp này chứa thông tin chung cho mọi đối tượng truyền thuộc lớp này. |
Truyền đối tượng | Một thực thể của lớp truyền chỉ dành riêng cho một mã nhận dạng người dùng. |
Thông tin về lớp học lập trình này
Trong lớp học lập trình này, bạn sẽ hoàn thành các nhiệm vụ sau.
- Tạo tài khoản công ty phát hành mới ở chế độ minh hoạ
- Tạo một tài khoản dịch vụ để cấp thẻ và vé
- Tạo một lớp thẻ và vé Chung mới
- Tạo đối tượng truyền mới
- Tạo nút Add to Google Wallet (Thêm vào Google Wallet) để lưu thẻ và vé
- Hiển thị nút này trên trang web
- Xử lý kết quả lưu thẻ và vé
Điều kiện tiên quyết
- Git
- Một Tài khoản Google có quyền truy cập vào bảng điều khiển Google Cloud
- Node.js phiên bản 10 trở lên
Mục tiêu
Sau khi hoàn tất lớp học lập trình này, bạn có thể làm những việc sau:
- Tạo đối tượng thẻ và vé bằng Google Wallet
- Tạo nút Thêm vào Google Wallet
Hỗ trợ
Nếu bạn gặp khó khăn ở bất kỳ thời điểm nào trong lớp học lập trình, thì kho lưu trữ GitHub google-pay/wallet-web-codelab sẽ chứa một giải pháp hoàn chỉnh để bạn tham khảo.
2. Thiết lập
Ở bước này, bạn sẽ tạo Tài khoản phát hành ở chế độ minh hoạ. Nhờ đó, bạn có thể tạo các lớp và đối tượng thẻ và vé để thêm vào ví người dùng. Tiếp theo, bạn sẽ tạo một tài khoản dự án và dịch vụ trên Google Cloud. Các dữ liệu này sẽ được dùng để tạo các lớp và đối tượng theo phương thức lập trình theo cách tương tự như máy chủ phụ trợ. Cuối cùng, bạn sẽ cho phép tài khoản dịch vụ Google Cloud quản lý thẻ và vé trong tài khoản công ty phát hành Google Wallet của bạn.
Đăng ký tài khoản của nhà phát hành Google Wallet
Bạn cần có tài khoản của công ty phát hành để tạo và phân phối thẻ và vé cho Google Wallet. Bạn có thể đăng ký bằng Google Pay và Bảng điều khiển Wallet. Ban đầu, bạn sẽ có quyền truy cập để tạo thẻ và vé ở chế độ minh hoạ. Điều này có nghĩa là chỉ những người dùng thử nghiệm cụ thể mới có thể thêm những thẻ và vé mà bạn tạo. Bạn có thể quản lý người dùng thử nghiệm trong ứng dụng Google Pay và Bảng điều khiển Wallet.
Để biết thêm thông tin về chế độ minh hoạ, hãy xem phần Điều kiện tiên quyết chung để vượt qua lượt xem.
- Mở ứng dụng Google Pay và Bảng điều khiển Wallet
- Làm theo hướng dẫn trên màn hình để tạo Tài khoản công ty phát hành
- Chọn Google Wallet API
- Xác nhận rằng bạn hiểu rõ điều khoản dịch vụ và chính sách quyền riêng tư
- Sao chép giá trị Mã công ty phát hành vào một trình chỉnh sửa văn bản hoặc vị trí khác
- Trong thẻ Quản lý, hãy chọn Thiết lập tài khoản thử nghiệm
- Thêm mọi địa chỉ email mà bạn sẽ sử dụng trong lớp học lập trình này
Bật Google Wallet API
- Đăng nhập vào bảng điều khiển Google Cloud
- Nếu bạn chưa có dự án trên Google Cloud, hãy tạo một dự án ngay bây giờ (xem bài viết Tạo và quản lý dự án để biết thêm thông tin)
- Bật API Google Wallet (còn gọi là API Google Pay cho thẻ và vé) cho dự án của bạn
Tạo tài khoản dịch vụ và khoá
Cần có tài khoản dịch vụ và khoá tài khoản dịch vụ để gọi Google Wallet API. Tài khoản dịch vụ là danh tính để gọi Google Wallet API. Khoá tài khoản dịch vụ chứa khoá riêng tư giúp nhận dạng ứng dụng của bạn là tài khoản dịch vụ. Khoá này nhạy cảm nên hãy bảo mật.
Tạo một tài khoản dịch vụ
- Trong bảng điều khiển Google Cloud, hãy mở mục Tài khoản dịch vụ
- Nhập tên, mã và nội dung mô tả cho tài khoản dịch vụ của bạn
- Chọn TẠO VÀ TIẾP TỤC
- Chọn XONG
Tạo khoá tài khoản dịch vụ
- Chọn tài khoản dịch vụ của bạn
- Chọn trình đơn KEYS
- Chọn THÊM KHOÁ, rồi chọn Tạo khoá mới
- Chọn loại khoá JSON
- Chọn TẠO
Bạn sẽ được nhắc lưu tệp khoá vào máy trạm cục bộ. Hãy nhớ ghi nhớ vị trí của thiết bị.
Đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS
Biến môi trường GOOGLE_APPLICATION_CREDENTIALS
được Google SDK sử dụng để xác thực là tài khoản dịch vụ và truy cập vào các API khác nhau cho một dự án Google Cloud.
- Làm theo hướng dẫn trong tài liệu về khoá tài khoản Dịch vụ Google Cloud để đặt biến môi trường
GOOGLE_APPLICATION_CREDENTIALS
- Xác minh rằng biến môi trường được đặt trong một thiết bị đầu cuối mới (MacOS/Linux) hoặc phiên dòng lệnh (Windows) (bạn có thể phải bắt đầu một phiên mới nếu đã mở một phiên)
echo $GOOGLE_APPLICATION_CREDENTIALS
Uỷ quyền tài khoản dịch vụ
Cuối cùng, bạn sẽ cần uỷ quyền cho tài khoản dịch vụ quản lý thẻ và vé trong Google Wallet.
- Mở ứng dụng Google Pay và Bảng điều khiển Wallet
- Chọn Người dùng
- Chọn Mời người dùng
- Nhập địa chỉ email của tài khoản dịch vụ (ví dụ:
test-svc@myproject.iam.gserviceaccount.com
) - Chọn Nhà phát triển hoặc Quản trị viên từ trình đơn thả xuống Cấp truy cập
- Chọn Mời
3. Khởi động ứng dụng Node.js mẫu
Thời lượng 10:00
Trong bước này, bạn sẽ chạy ứng dụng Node.js mẫu hoạt động như một trang web mua sắm và máy chủ phụ trợ.
Sao chép kho lưu trữ mẫu
Kho lưu trữ google-pay/wallet-web-codelab chứa một dự án mẫu dựa trên Node.js và nhiều tệp tập lệnh mô phỏng một máy chủ phụ trợ dùng để cấp phép các lớp và đối tượng thẻ và vé. Bạn sẽ chỉnh sửa các thành phần này để thêm nút Thêm vào Google Wallet trên màn hình chi tiết sản phẩm.
- Sao chép kho lưu trữ vào máy trạm cục bộ
git clone https://github.com/google-pay/wallet-web-codelab.git
Cài đặt phần phụ thuộc của dự án
- Mở kho lưu trữ đã sao chép trong cửa sổ dòng lệnh hoặc cửa sổ dòng lệnh
- Chuyển đến thư mục
web
(đây là ứng dụng mà bạn sẽ sửa đổi trong phần còn lại của lớp học lập trình này)cd web
- Cài đặt phần phụ thuộc Node.js
npm install .
- Khởi động ứng dụng
node app.js
- Mở ứng dụng chạy trên http://localhost:3000
Nếu bạn nhập địa chỉ email của mình rồi chọn Tạo thẻ và vé thì sẽ không có gì xảy ra. Trong các bước tiếp theo, bạn sẽ định cấu hình ứng dụng để tạo một lớp truyền và đối tượng mới.
4. Tạo lớp thẻ và vé chung
Ở bước này, bạn sẽ tạo lớp cơ sở cho thẻ/vé của mình. Bất cứ khi nào một thẻ/vé mới được tạo cho người dùng, thẻ/vé đó sẽ kế thừa các thuộc tính được xác định trong lớp thẻ/vé.
Lớp thẻ và vé mà bạn sẽ tạo trong lớp học lập trình này sử dụng tính linh hoạt của thẻ và vé Chung để tạo một đối tượng hoạt động như cả huy hiệu nhận dạng và công cụ theo dõi điểm thử thách. Khi một đối tượng truyền được tạo từ lớp này, đối tượng đó sẽ có dạng như hình sau.
Bạn có thể tạo lớp học thẻ và vé ngay trong Google Pay và Wallet Console hoặc bằng cách sử dụng Google Wallet API. Trong lớp học lập trình này, bạn sẽ tạo lớp thẻ và vé Chung bằng API. Việc này tuân theo quy trình mà một máy chủ phụ trợ riêng tư sẽ sử dụng để tạo các lớp truyền.
- Mở tệp
web/app.js
- Thay thế giá trị của
issuerId
bằng Mã công ty phát hành của bạn trong Google Pay và Bảng điều khiển Wallet// TODO: Define Issuer ID const issuerId = 'ISSUER_ID';
- Tìm hàm
createPassClass
- Trong hàm này, hãy tạo một ứng dụng HTTP đã xác thực rồi sử dụng Google Wallet API để tạo một lớp thẻ và vé mới
// TODO: Create a Generic pass class let genericClass = { 'id': `${classId}`, 'classTemplateInfo': { 'cardTemplateOverride': { 'cardRowTemplateInfos': [ { 'twoItems': { 'startItem': { 'firstValue': { 'fields': [ { 'fieldPath': 'object.textModulesData["points"]' } ] } }, 'endItem': { 'firstValue': { 'fields': [ { 'fieldPath': 'object.textModulesData["contacts"]' } ] } } } } ] }, 'detailsTemplateOverride': { 'detailsItemInfos': [ { 'item': { 'firstValue': { 'fields': [ { 'fieldPath': 'class.imageModulesData["event_banner"]' } ] } } }, { 'item': { 'firstValue': { 'fields': [ { 'fieldPath': 'class.textModulesData["game_overview"]' } ] } } }, { 'item': { 'firstValue': { 'fields': [ { 'fieldPath': 'class.linksModuleData.uris["official_site"]' } ] } } } ] } }, 'imageModulesData': [ { 'mainImage': { 'sourceUri': { 'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png' }, 'contentDescription': { 'defaultValue': { 'language': 'en-US', 'value': 'Google I/O 2022 Banner' } } }, 'id': 'event_banner' } ], 'textModulesData': [ { 'header': 'Gather points meeting new people at Google I/O', 'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.', 'id': 'game_overview' } ], 'linksModuleData': { 'uris': [ { 'uri': 'https://io.google/2022/', 'description': 'Official I/O \'22 Site', 'id': 'official_site' } ] } }; let response; try { // Check if the class exists already response = await httpClient.request({ url: `${baseUrl}/genericClass/${classId}`, method: 'GET' }); console.log('Class already exists'); console.log(response); } catch (err) { if (err.response && err.response.status === 404) { // Class does not exist // Create it now response = await httpClient.request({ url: `${baseUrl}/genericClass`, method: 'POST', data: genericClass }); console.log('Class insert response'); console.log(response); } else { // Something else went wrong console.log(err); res.send('Something went wrong...check the console logs!'); } }
Khi mã của bạn chạy, mã này sẽ tạo một lớp truyền (class) mới và xuất mã lớp (class ID). Mã lớp tạo thành mã nhận dạng nhà phát hành, theo sau là một hậu tố do nhà phát triển xác định. Trong trường hợp này, hậu tố được đặt thành codelab_class
(mã lớp sẽ tương tự như 1234123412341234123.codelab_class
). Nhật ký đầu ra cũng sẽ bao gồm phản hồi của Google Wallet API.
5. Tạo một đối tượng truyền chung
Trong bước này, bạn sẽ định cấu hình ứng dụng Node.js để tạo một đối tượng truyền Chung bằng cách sử dụng lớp mà bạn đã tạo trước đó. Có hai quy trình tạo đối tượng thẻ và vé cho người dùng.
Tạo đối tượng truyền trên máy chủ phụ trợ
Trong phương pháp này, đối tượng truyền được tạo trên máy chủ phụ trợ và trả về ứng dụng khách dưới dạng một JWT đã ký. Điều này phù hợp nhất với các trường hợp có tỷ lệ sử dụng cao của người dùng, vì nó đảm bảo đối tượng tồn tại trước khi người dùng cố gắng thêm đối tượng đó vào ví.
Tạo đối tượng thẻ và vé khi người dùng thêm đối tượng đó vào ví
Trong phương pháp này, đối tượng truyền được xác định và mã hoá thành JWT đã ký trên máy chủ phụ trợ. Sau đó, nút Add to Google Wallet (Thêm vào Google Wallet) sẽ xuất hiện trong ứng dụng khách tham chiếu đến JWT. Khi người dùng chọn nút này, JWT sẽ được dùng để tạo đối tượng truyền. Điều này phù hợp nhất với các trường hợp tình trạng chấp nhận của người dùng có thể thay đổi hoặc không xác định, vì nó ngăn việc tạo và không sử dụng các đối tượng truyền. Phương pháp này sẽ được sử dụng trong lớp học lập trình này.
- Mở tệp
web/app.js
- Tìm hàm
createPassObject
- Trong hàm này, hãy xác định một đối tượng truyền mới cho người dùng
// TODO: Create a new Generic pass for the user let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`; let objectId = `${issuerId}.${objectSuffix}`; let genericObject = { 'id': `${objectId}`, 'classId': classId, 'genericType': 'GENERIC_TYPE_UNSPECIFIED', 'hexBackgroundColor': '#4285f4', 'logo': { 'sourceUri': { 'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg' } }, 'cardTitle': { 'defaultValue': { 'language': 'en', 'value': 'Google I/O \'22' } }, 'subheader': { 'defaultValue': { 'language': 'en', 'value': 'Attendee' } }, 'header': { 'defaultValue': { 'language': 'en', 'value': 'Alex McJacobs' } }, 'barcode': { 'type': 'QR_CODE', 'value': `${objectId}` }, 'heroImage': { 'sourceUri': { 'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg' } }, 'textModulesData': [ { 'header': 'POINTS', 'body': '1234', 'id': 'points' }, { 'header': 'CONTACTS', 'body': '20', 'id': 'contacts' } ] }; // TODO: Create the signed JWT and link res.send("Form submitted!");
Nếu tải lại ứng dụng, nhập địa chỉ email của bạn rồi gửi biểu mẫu, bạn sẽ không thấy kết quả nào. Ứng dụng phụ trợ đang xác định đối tượng truyền, nhưng không trả về kết quả nào. Tiếp theo, bạn sẽ chuyển thẻ/vé thành đường liên kết Thêm vào Google Wallet.
6. Tạo một Nút Thêm vào Google Wallet
Đối với bước cuối cùng, bạn sẽ tạo JWT đã ký và trả về một đường liên kết có thể dùng được qua nút Add to Google Wallet (Thêm vào Google Wallet). Khi người dùng chọn nút này, họ sẽ thấy lời nhắc lưu thẻ và vé vào ví.
- Tạo thông báo xác nhận quyền sở hữu JWT, mã hoá các thông báo này bằng khoá riêng tư của tài khoản dịch vụ rồi trả về nút Add to Google Wallet (Thêm vào Google Wallet) bằng đường liên kết được nhúng
// TODO: Create the signed JWT and link const claims = { iss: credentials.client_email, aud: 'google', origins: [], typ: 'savetowallet', payload: { genericObjects: [ genericObject ] } }; const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' }); const saveUrl = `https://pay.google.com/gp/v/save/${token}`; res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`);
- Tải lại ứng dụng đang chạy trên trình duyệt
- Nhập địa chỉ email của bạn vào biểu mẫu rồi chọn Tạo thẻ và vé
- Khi nút này xuất hiện, hãy chọn nút Thêm vào Google Wallet
7. Xin chúc mừng
Xin chúc mừng, bạn đã tích hợp thành công API Google Wallet trên web!
Tìm hiểu thêm
Hãy xem phần tích hợp hoàn chỉnh trong kho lưu trữ google-pay/wallet-web-codelab trên GitHub.
Tạo thẻ và vé và yêu cầu quyền phát hành công khai
Khi bạn đã sẵn sàng phát hành thẻ và vé của riêng mình trong phiên bản phát hành công khai, hãy truy cập vào Google Pay và Bảng điều khiển Wallet để yêu cầu quyền truy cập vào kênh phát hành công khai.
Hãy xem Điều kiện tiên quyết về API Web để tìm hiểu thêm.