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

Google Wallet API 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é đi phương tiện công cộng, thẻ lên máy bay và nhiều loại thẻ/vé khác. Mỗi loại thẻ hoặc 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 trường hợp 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ẻ chung. Sau đây là một số trường hợp sử dụng mẫu cho loại thẻ chung:

Thẻ đỗ xe
Thẻ thành viên thư viện
Phiếu quà tặ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ể 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 Thông tin chi tiết

Một thiết bị chạy Android minh hoạ quy trình cung cấp tính năng 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 một ứng dụng Android, vui lòng xem tài liệu dành cho nhà phát triển của Google Wallet.

Truyền các lớp và đối tượng

Google Wallet API cung cấp các phương thức để tạo những mục sau:

Loại	Mô tả
Lớp thẻ và vé	Một mẫu cho từng đối tượng thẻ và vé. Nó chứa thông tin chung cho tất cả các đối tượng thẻ và vé thuộc lớp này.
Đối tượng thẻ và vé	Một phiên bản của lớp thẻ và vé, 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 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é tổng quát 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 này 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
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 sẽ có thể làm những việc sau:

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

2. Thiết lập

Trong bước này, bạn sẽ tạo một tài khoản Đơn vị phát hành ở chế độ minh hoạ. Điều này sẽ cho phép bạn tạo các lớp và đối tượng thẻ có thể 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 đối tượng này sẽ được dùng để tạo các lớp và đối tượng thẻ/vé 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ẽ cấp quyền cho tài khoản dịch vụ Google Cloud quản lý thẻ và vé trong tài khoản tổ chức phát hành Google Wallet.

Bạn cần có tài khoản Nhà 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 Google Pay và Wallet. 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 kiểm thử 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 Google Pay & Wallet Console.

Để 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 đối với 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 một tài khoản Tổ chức 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ã nhận dạng đơn vị 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 kiểm thử
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 nào trên Google Cloud, hãy tạo một dự án ngay bây giờ (xem phần 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 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 một khoá riêng tư giúp xác định ứng dụng của bạn là tài khoản dịch vụ. Khoá này là khoá 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ụ 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ụ
Chọn trình đơn KEYS (KHOÁ)
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ớ vị trí của nó.

Đặ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 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ụ của 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 thiết bị đầu cuối (MacOS/Linux) mới (bạn có thể cần 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 sẽ cần cấp 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 một lớp Thẻ và vé chung

Trong bước này, bạn sẽ tạo lớp cơ sở cho thẻ và vé. Bất cứ khi nào 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ẻ/vé mà bạn sẽ tạo trong lớp học lập trình này tận dụng tính linh hoạt của thẻ/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 thẻ/vé được tạo từ lớp này, đối tượng đó sẽ có dạng như hình minh hoạ sau.

Bạn có thể tạo các lớp thẻ và vé ngay trong Google Pay & 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. Thao tác này tuân theo quy trình mà một máy chủ riêng tư ở phần phụ trợ sẽ dùng để tạo các lớp thẻ và vé.

Sao chép kho lưu trữ google-pay/wallet-android-codelab trên GitHub 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ữ đã sao chép trong thiết bị đầu cuối hoặc dấu 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 thao tác 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ã tổ chức phát hành của bạn trong Bảng điều khiển Google Pay và Wallet
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
Trong dấu 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 mã của bạn chạy, mã đó sẽ tạo một lớp thẻ và xuất mã lớp. Mã nhận dạng lớp bao gồm mã nhận dạng của tổ chức 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ã nhận dạng lớp sẽ có dạng 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 có chứa một dự án Android với một hoạt động trống. Ở bước này, bạn sẽ chỉnh sửa trong 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 Tệp, rồi chọn Mở
Chọn thư mục android trong kho lưu trữ
Chọn Mở

Thêm Google Wallet SDK vào ứng dụng của bạn

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

Thêm Google Wallet SDK vào mục 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 các tệp Gradle)

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

Ở bước này, bạn sẽ tạo nút Thêm vào Google Wallet rồi thêm nút đó vào một hoạt động hiện có. Các thành phần cho nút đã đượ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ợ Google Wallet API, thì điều này có thể gây ra trải nghiệm tiêu cực khi họ cố gắng thêm thẻ và vé. Nếu thiết bị của người dùng không hỗ trợ Google Wallet API, thì việc ẩn nút Thêm vào Google Wallet sẽ tránh được tình trạng nhầm lẫn có thể xảy ra. Có nhiều lý do khiến API có thể không hoạt động, chẳng hạn như phiên bản Android hoặc Google Play Services đã 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ó hoạt động trên thiết bị hay không. Nếu có, nút này sẽ được kết xuất 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 thực thể cho 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, sau khi xác minh rằng Google Wallet API có sẵn, bạn có thể tạo một thẻ/vé và nhắc người dùng thêm thẻ/vé đó vào ví của họ. Có hai quy trình để 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ợ

Theo phương pháp này, đối tượng thẻ và vé được tạo trên một máy chủ phụ trợ và được trả về cho ứng dụng khách dưới dạng JWT đã ký. Cách này phù hợp nhất cho những trường hợp có tỷ lệ chấp nhận của người dùng cao, vì cách 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ẻ khi người dùng thêm thẻ vào ví

Theo phương pháp này, đối tượng thẻ và vé được xác định và mã hoá thành một JWT đã ký trên máy chủ phụ trợ. Sau đó, nút 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 thẻ và vé. Đây là lựa chọn phù hợp nhất cho những trường hợp mà mức độ chấp nhận của người dùng là biến số hoặc không xác định, vì lựa chọn này ngăn việc tạo và không sử dụng các đối tượng thẻ và vé. Phương pháp này sẽ được 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ã tổ chức phát hành của bạn trong Bảng điều khiển Google Pay và Wallet
```
// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
```
Trong cửa sổ dòng lệnh hoặc dấu nhắ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 mã của bạn chạy, mã đó sẽ xác định một đối tượng thẻ và nhúng đối tượng đó vào một 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 đối với Google Wallet API để thông tin đăng nhập không cần được lưu trữ trong ứng dụng khách.

aside Trong môi trường phát hành công khai, hệ thống phụ trợ của bạn sẽ chịu trách nhiệm tạo JWT và trả về cho các ứng dụng. Trong lớp học lập trình này, tập lệnh generic_pass.js sẽ 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, sau khi xác minh rằng Google Wallet API có sẵn và bạn đã tạo một JWT đã ký, bạn có thể nhắc người dùng thêm thẻ/vé vào ví của họ. Trong bước này, bạn sẽ thêm một trình nghe vào nút Thêm vào Google Wallet. Trình nghe này sẽ dùng Google Wallet API để 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 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 mộ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.root

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

Trong 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 thao tác 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 Thẻ chung.

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

Tìm hiểu thêm

Hãy xem quy trình tích hợp hoàn chỉnh trong kho lưu trữ google-pay/wallet-android-codelab trên GitHub.

Tạo thẻ và vé, đồng thời 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 môi trường phát hành công khai, hãy truy cập vào Google Pay & Wallet Console để yêu cầu quyền truy cập vào môi trường 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 đối với SDK Android để tìm hiểu thêm.