Trang này được dịch bởi Cloud Translation API.

Tạo thẻ và vé trên Android bằng Google Wallet API

1. Giới thiệu

Tổng quan

API Google Wallet cho phé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é phương tiện công cộng, thẻ lên máy bay, v.v. Mỗi loại thẻ và lớp thẻ đều có các trường và tính năng dành riêng cho trường hợp sử dụng để nâng cao trải nghiệm người dùng.

Tuy nhiên, những cách 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 tuỳ chỉnh hơn, bạn có thể sử dụng loại thẻ và vé chung. Dưới đây là một số trường hợp sử dụng mẫu cho 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ình ảnh mã vạch
(Không bắt buộc) Mục Chi tiết

Một thiết bị chạy Android minh hoạ quy trình cấp phép Thêm vào Google Wallet

Để biết thêm thông tin về API Ví Google hoặc cách thêm nút Thêm vào Google Wallet vào ứng dụng Android, 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 Ví Google hiển thị các phương thức để tạo:

Loại	Mô tả
Lớp truyền	Mẫu cho một đối tượng thẻ và vé riêng lẻ. Tệp này chứa thông tin chung cho tất cả đối tượng thẻ và vé thuộc lớp này.
Truyền đối tượng	Một thực thể của lớp thẻ và vé 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 phát hành mới ở chế độ minh hoạ
Tạo tài khoản dịch vụ để phát hành thẻ và vé
Tạo một lớp thẻ và vé chung mới
Tạo đối tượng thẻ và vé mới
Tạo nút Thêm vào Google Wallet để lưu thẻ/vé
Hiển thị nút trong ứng dụng Android
Xử lý kết quả lưu thẻ và vé

Điều kiện tiên quyết

Android Studio
Git
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 sẽ có thể làm những việc sau:

Thêm SDK Google Wallet vào ứng dụng Android
Kiểm tra xem API Google Wallet có trên thiết bị chạy Android hay không
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 này, kho lưu trữ GitHub google-pay/wallet-android-codelab có chứa một giải pháp hoàn chỉnh để tham khảo.

2. Thiết lập

Ở bước này, bạn sẽ tạo một Tài khoản phát hành ở chế độ minh hoạ. Điều này cho phép bạn tạo các lớp và đối tượng thẻ và vé có thể được thêm vào ví của người dùng. Tiếp theo, bạn sẽ tạo một dự án và tài khoản dịch vụ trên Google Cloud. Các lớp này sẽ được dùng để tạo các lớp và đối tượng thẻ và vé theo phương thức lập trình giống 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ủa tổ chức phát hành thẻ và vé trên Google Wallet.

Bạn cần có Tài khoản 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 Bảng điều khiển của Google Pay và Ví. Ban đầu, bạn sẽ có quyền 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 thẻ và vé mà bạn tạo. Bạn có thể quản lý người dùng thử nghiệm trong Bảng điều khiển của Google Pay và Ví.

Để biết thêm thông tin về chế độ minh hoạ, hãy xem phần Các điều kiện tiên quyết chung về thẻ và vé.

Mở Bảng điều khiển của Google Pay và Wallet
Làm theo hướng dẫn trên màn hình để tạo Tài khoản phát hành
Chọn Google Wallet API
Xác nhận rằng bạn hiểu điều khoản dịch vụ và chính sách quyền riêng tư
Sao chép giá trị Mã nhận dạng của tổ chức phát hành vào trình soạn thảo 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 bạn sẽ sử dụng trong lớp học lập trình này

Bật API Ví Google

Đă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 ngay một dự án (xem bài viết Tạo và quản lý dự án để biết thêm thông tin)
Bật API Ví Google (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á

Bạn cần có tài khoản dịch vụ và khoá tài khoản dịch vụ để gọi API Google Wallet. Tài khoản dịch vụ là danh tính gọi API Google Wallet. Khoá tài khoản dịch vụ chứa một khoá riêng tư xác định ứng dụng của bạn là tài khoản dịch vụ. Khoá này rất nhạy cảm, vì vậy, hãy giữ bí mật.

Tạo một tài khoản dịch vụ

Trong Google Cloud Console, hãy mở Tài khoản dịch vụ
Nhập tên, mã nhận dạng và nội dung mô tả cho tài khoản dịch vụ
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ụ
Chọn trình đơn KEYS (PHÍM)
Chọn THÊM KHÓA, 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ớ vị trí của tệp đó.

Đặt biến môi trường `GOOGLE_APPLICATION_CREDENTIALS`

Biến môi trường GOOGLE_APPLICATION_CREDENTIALS được các SDK của Google sử dụng để xác thực dưới dạng tài khoản dịch vụ và truy cập vào nhiều API 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 phiên dòng lệnh (Windows) hoặc phiên giao diện dòng lệnh mới (MacOS/Linux) (bạn có thể cần 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 cho tài khoản dịch vụ

Cuối cùng, bạn cần uỷ quyền cho tài khoản dịch vụ quản lý thẻ và vé trong Google Wallet.

Mở Bảng điều khiển của Google Pay và 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 trong trình đơn thả xuống Cấp truy cập
Chọn Mời

3. Tạo lớp thẻ và vé chung

Ở bước này, bạn sẽ tạo lớp cơ sở cho thẻ và vé. Mỗi khi một thẻ và vé mới được tạo cho người dùng, thẻ và vé đó sẽ kế thừa các thuộc tính được xác định trong lớp thẻ và vé.

Lớp thẻ 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ẻ chung để tạo một đối tượng vừa là huy hiệu nhận dạng vừa là trình theo dõi điểm thử thách. Khi một đối tượng thẻ và vé được tạo từ lớp này, đối tượng đó sẽ có dạng như hình ảnh sau.

Bạn có thể tạo lớp thẻ và vé trực tiếp trong Bảng điều khiển của Google Pay và Ví hoặc bằng cách sử dụng API Ví Google. 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. Quá trình này tuân theo quy trình mà máy chủ phụ trợ riêng tư sẽ sử dụng để tạo các lớp thẻ và vé.

Sao chép kho lưu trữ GitHub google-pay/wallet-android-codelab vào máy trạm cục bộ
```
git clone https://github.com/google-pay/wallet-android-codelab.git
```
Mở kho lưu trữ được sao chép trong dòng lệnh hoặc lời nhắc dòng lệnh
Chuyển đến thư mục backend (các tập lệnh này mô phỏng các hành động của máy chủ phụ trợ)
```
cd backend
```
Cài đặt các phần phụ thuộc Node.js
```
npm install .
```
Trong thư mục backend, hãy mở generic_class.js
Thay thế giá trị của issuerId bằng mã nhận dạng của tổ chức phát hành trong Bảng điều khiển của Google Pay và Wallet
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
Trong lời nhắc dòng lệnh hoặc thiết bị đầu cuối, hãy chạy tập lệnh generic_class.js
```
node generic_class.js
```

Khi chạy, mã sẽ tạo một lớp thẻ và xuất mã nhận dạng lớp. Mã lớp được tạo thành từ mã nhận dạng của tổ chức phát hành, theo sau là 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 từ API Google Wallet.

4. Mở dự án trong Android Studio

Kho lưu trữ GitHub mà bạn đã sao chép chứa một dự án Android có hoạt động trống. Ở bước này, bạn sẽ chỉnh sửa hoạt động này để thêm nút Thêm vào Google Wallet trên trang sản phẩm.

Mở Android Studio
Chọn File (Tệp), rồi chọn Open (Mở)
Chọn thư mục android trong kho lưu trữ
Chọn Mở

Thêm SDK Google Wallet vào ứng dụng

Mở tệp bản dựng Gradle cấp mô-đun (android/app/build.gradle)

Thêm SDK Google Wallet vào phần dependencies

// TODO: Add the "com.google.android.gms:play-services-pay" dependency to
//       use the Google Wallet API
implementation "com.google.android.gms:play-services-pay:16.0.3"

Lưu tệp
Chọn File (Tệp), sau đó chọn Sync Project with Gradle Files (Đồng bộ hoá dự án với tệp Gradle)

5. Tạo nút Thêm vào Google Wallet

Ở bước này, bạn sẽ tạo một nút Thêm vào Google Wallet và thêm nút đó vào một hoạt động hiện có. Các thành phần của nút này đã được đưa vào dự án. Để thêm nút này, bạn sẽ tạo một tệp bố cục riêng. Sau khi thêm, nút sẽ có dạng như sau.

Tạo tệp bố cục mới: app/src/main/res/layout/add_to_google_wallet_button.xml

Thêm nội dung sau vào tệp bố cục mới

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:clickable="true"
    android:contentDescription="@string/add_to_google_wallet_button_content_description"
    android:focusable="true">
  <ImageView
      android:layout_width="227dp"
      android:layout_height="26dp"
      android:layout_gravity="center"
      android:duplicateParentState="true"
      android:src="@drawable/add_to_google_wallet_button_foreground" />
</FrameLayout>

Đưa bố cục add_to_google_wallet_button.xml vào tệp bố cục hoạt động thanh toán (app/src/main/res/layout/activity_checkout.xml)

<!--
    TODO: Create the button under `add_to_google_wallet_button.xml`
          and include it in your UI
-->
<include
    android:id="@+id/addToGoogleWalletButton"
    layout="@layout/add_to_google_wallet_button"
    android:layout_width="match_parent"
    android:layout_height="48dp"
    android:layout_marginTop="10dp" />

6. Kiểm tra xem API Ví Google có hoạt động hay không

Nếu người dùng mở ứng dụng của bạn trên một thiết bị không hỗ trợ API Google Wallet, thì họ có thể gặp phải trải nghiệm không tốt khi cố gắng thêm thẻ và vé. Nếu thiết bị của người dùng không hỗ trợ API Google Wallet, hãy ẩn nút Thêm vào Google Wallet để tránh gây nhầm lẫn. Có nhiều lý do khiến API có thể không hoạt động, chẳng hạn như các phiên bản Android hoặc Dịch vụ Google Play đã lỗi thời hoặc Google Wallet không hoạt động ở quốc gia của người dùng.

Trong bước này, bạn sẽ thêm logic vào ứng dụng để kiểm tra xem API Google Wallet có trên thiết bị hay không. Nếu có, nút này sẽ được hiển thị trong hoạt động. Nếu không, nút này sẽ bị ẩn.

Mở tệp CheckoutActivity.kt trong app/src/main/java/com/google/android/gms/samples/wallet/activity/

Tạo một thuộc tính lớp cho thực thể PayClient

// TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient

Tạo bản sao của thuộc tính PayClient trong phương thức onCreate
```
// TODO: Instantiate the client
walletClient = Pay.getClient(this)
```

Tạo một phương thức kiểm tra xem SDK và API Google Wallet có trên thiết bị hay không và xử lý kết quả

// TODO: Create a method to check for the Google Wallet SDK and API
private fun fetchCanUseGoogleWalletApi() {
  walletClient
    .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
    .addOnSuccessListener { status ->
      if (status == PayApiAvailabilityStatus.AVAILABLE)
        layout.passContainer.visibility = View.VISIBLE
    }
    .addOnFailureListener {
      // Hide the button and optionally show an error message
    }
}

Gọi phương thức fetchCanUseGoogleWalletApi trong phương thức onCreate để kiểm tra xem API Ví Google có hoạt động hay không
```
// TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()
```

Khi chạy ứng dụng, bạn sẽ thấy nút Thêm vào Google Wallet trong giao diện người dùng.

7. Tạo đối tượng thẻ và vé chung

Giờ đây, khi đã xác minh rằng Google Wallet API có sẵn, bạn có thể tạo thẻ và nhắc người dùng thêm thẻ đó vào ví của họ. Có hai luồng để tạo đối tượng thẻ và vé cho người dùng.

Tạo đối tượng thẻ và vé trên máy chủ phụ trợ

Trong phương pháp này, đối tượng thẻ và vé được tạo trên máy chủ phụ trợ và được trả về ứng dụng khách dưới dạng JWT đã ký. Phương thức này phù hợp nhất với những trường hợp người dùng sử dụng nhiều, vì phương thức này đả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í của họ.

Tạo đối tượng thẻ và vé khi người dùng thêm thẻ và vé đó vào ví

Trong phương pháp này, đối tượng thẻ và vé được xác định và mã hoá thành JWT đã ký trên máy chủ phụ trợ. Sau đó, nút Thêm vào Google Wallet sẽ hiển thị 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 thẻ và vé. Cách này phù hợp nhất với các trường hợp người dùng sử dụng biến hoặc không xác định, vì cách này 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.

Mở tệp backend/generic_pass.js
Thay thế giá trị của issuerId bằng mã nhận dạng của tổ chức phát hành trong Bảng điều khiển của Google Pay và Wallet
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
Trong dấu nhắc dòng lệnh hoặc dòng lệnh, hãy chạy tệp generic_pass.js
```
node generic_pass.js
```
Sao chép mã thông báo đầu ra vào bảng nhớ tạm hoặc trình chỉnh sửa văn bản

Khi chạy, mã sẽ xác định một đối tượng thẻ và nhúng đối tượng đó vào JWT. Sau đó, JWT được ký bằng khoá tài khoản dịch vụ mà bạn đã tạo trước đó. Thao tác này xác thực yêu cầu gửi đến API Google Wallet để không cần lưu trữ thông tin xác thực trong ứng dụng khách.

Ngoài ra, trong môi trường sản xuất, hệ thống phụ trợ của bạn sẽ chịu trách nhiệm tạo JWT và trả về cho ứng dụng. Trong lớp học lập trình này, tập lệnh generic_pass.js mô phỏng hành vi này và "trả về" một mã thông báo để bạn sử dụng trong ứng dụng khách.

8. Thêm thẻ và vé vào Google Wallet

Giờ đây, khi đã xác minh rằng Google Wallet API có sẵn và đã tạo JWT đã ký, bạn có thể nhắc người dùng thêm thẻ và vé vào ví của họ. Ở bước này, bạn sẽ thêm trình nghe vào nút Thêm vào Google Wallet. Nút này sử dụng API Google Wallet để lưu thẻ và vé vào ví của người dùng.

Mở tệp app/src/main/CheckoutActivity.kt

Thay thế giá trị của token bằng JWT mà bạn đã tạo trước đó

// TODO: Save the JWT from the backend "response"
private val token = "TOKEN"

Tạo một thuộc tính lớp để lưu trữ mã yêu cầu

// TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000

Đặt trình nghe cho nút Thêm vào Google Wallet

// TODO: Set an on-click listener on the "Add to Google Wallet" button
addToGoogleWalletButton = layout.addToGoogleWalletButton.

addToGoogleWalletButton.setOnClickListener {
  walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
}

Khi người dùng chọn nút Thêm vào Google Wallet, phương thức walletClient.savePassesJwt sẽ được gọi. Phương thức này nhắc người dùng thêm đối tượng thẻ và vé mới vào Google Wallet.

9. Xử lý kết quả savePassesJwt

Ở bước cuối cùng của lớp học lập trình này, bạn sẽ định cấu hình ứng dụng để xử lý kết quả của toán tử walletClient.savePassesJwt.

Mở tệp app/src/main/CheckoutActivity.kt

Ghi đè phương thức onActivityResult để chứa mã sau

// TODO: Handle the result
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (requestCode == addToGoogleWalletRequestCode) {
    when (resultCode) {
      RESULT_OK -> {
        // Pass saved successfully. Consider informing the user.
      }

      RESULT_CANCELED -> {
        // Save canceled
      }

      PayClient.SavePassesResult.SAVE_ERROR ->
        data?.let { intentData ->
          val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
          // Handle error. Consider informing the user.
          Log.e("SavePassesResult", errorMessage.toString())
        }

      else -> {
        // Handle unexpected (non-API) exception
      }
    }
  }
}

Giờ đây, ứng dụng của bạn có thể xử lý các trường hợp sau:

Đã thêm thẻ và vé thành công
Người dùng huỷ
Lỗi không mong muốn

Chạy ứng dụng để xác nhận rằng bạn có thể thêm thẻ và xử lý kết quả như mong đợi.

10. Xin chúc mừng

Ví dụ về đối tượng truyền chung.

Xin chúc mừng! Bạn đã tích hợp thành công API Ví Google trên Android!

Tìm hiểu thêm

Hãy xem cách tích hợp đầy đủ trong kho lưu trữ GitHub google-pay/wallet-android-codelab.

Tạo thẻ và vé và yêu cầu quyền truy cập chính thức

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 chính thức, hãy truy cập vào Bảng điều khiển Google Pay và Ví để yêu cầu quyền truy cập vào kênh phát hành công khai và uỷ quyền cho ứng dụng Android của bạn.

Hãy xem phần Điều kiện tiên quyết về SDK Android để tìm hiểu thêm.