使用 Google Wallet API 在 Android 上建立票證

1. 簡介

總覽

您可以透過 Google Wallet API 提供各種票證，與使用者互動，例如會員卡、優惠、禮物卡、活動票券、大眾運輸車票、登機證等。每個票證類型 (或票證類別) 都會提供特定用途的欄位和功能，以提升使用者體驗。

不過，這些可能不適用於所有用途。如要打造更貼近需求的體驗，您可以使用通用票證類型。以下是一般票證類型的幾個範例用途：

  • 停車證
  • 圖書館會員卡
  • 儲值券
  • 健身房會員卡
  • 保留項目

您可以使用通用票證，用於以下任何用途：

  • 最多三列資訊
  • (選用) 條碼圖片
  • (選用) 詳細資料專區

展示「新增至 Google 錢包」佈建流程的 Android 裝置

如要進一步瞭解 Google Wallet API，或在 Android 應用程式中新增「新增至 Google 錢包」按鈕，請參閱 Google Wallet 開發人員說明文件。

傳遞類別和物件

Google Wallet API 會公開方法，用於建立下列項目：

類型

說明

票證類別

個別票證物件的範本。其中包含屬於此類別的所有通行證物件共用的資訊。

傳遞物件

使用者 ID 專屬的通行證類別例項。

程式碼研究室簡介

在本程式碼研究室中，您將完成下列工作。

  1. 在示範模式中建立新的核發機構帳戶
  2. 建立服務帳戶以核發票證
  3. 建立新的一般票證類別
  4. 建立新的票證物件
  5. 建立「新增至 Google 錢包」按鈕，以便儲存票證
  6. 在 Android 應用程式中顯示按鈕
  7. 處理票證儲存結果

必要條件

目標

完成本程式碼研究室後，您將能夠執行下列操作：

  • 在 Android 應用程式中加入 Google 錢包 SDK
  • 檢查 Google Wallet API 是否可在 Android 裝置上使用
  • 建立「新增至 Google 錢包」按鈕

支援

如果在程式碼研究室的任何階段遇到問題，請參考 google-pay/wallet-android-codelab GitHub 存放區中的完整解決方案。

2. 設定

在這個步驟中，您將在示範模式下建立核發機構帳戶。這樣一來，您就能建立可新增至使用者錢包的票證類別和物件。接下來，您將建立 Google Cloud 專案和服務帳戶。這些類別和物件會以與後端伺服器相同的方式，透過程式輔助方式建立。最後，您將授權 Google Cloud 服務帳戶管理 Google 錢包發卡機構帳戶中的票證。

申請 Google Wallet API 核發機構帳戶

您必須擁有發布者帳戶，才能建立及發布 Google 錢包票證。您可以使用 Google Pay 和錢包主控台註冊。您一開始只能在展示模式中建立票證。也就是說，只有特定測試使用者才能新增您建立的票證。您可以在 Google Pay 和錢包主控台管理測試使用者。

如要進一步瞭解展示模式，請參閱通用通行證先決條件。

  1. 開啟 Google Pay 和錢包主控台
  2. 按照畫面上的指示建立發布者帳戶
  3. 選取「Google Wallet API」
  4. 確認您瞭解服務條款和隱私權政策
  5. 將「發出者 ID」值複製到文字編輯器或其他位置
  6. 在「管理」分頁中，選取「設定測試帳戶」。
  7. 新增您將在本程式碼研究室中使用的電子郵件地址

啟用 Google Wallet API

  1. 登入 Google Cloud 控制台
  2. 如果您尚未建立 Google Cloud 專案，請立即建立 (詳情請參閱「建立及管理專案」)
  3. 為專案啟用 Google Wallet API (也稱為 Google Pay for Passes API)

建立服務帳戶和金鑰

您必須具備服務帳戶和服務帳戶金鑰，才能呼叫 Google Wallet API。服務帳戶是呼叫 Google Wallet API 的身分。服務帳戶金鑰包含私密金鑰，可將您的應用程式識別為服務帳戶。這組金鑰屬於機密資料，請妥善保密。

建立服務帳戶

  1. 在 Google Cloud 控制台中，開啟「Service Accounts」
  2. 輸入服務帳戶的名稱、ID 和說明
  3. 選取「建立並繼續」
  4. 選取「完成」

建立服務帳戶金鑰

  1. 選取服務帳戶
  2. 選取「KEYS」KEYS選單
  3. 依序選取「新增金鑰」和「建立新的金鑰」。
  4. 選取「JSON」金鑰類型
  5. 選取「建立」

系統會提示您將金鑰檔案儲存至本機工作站。請務必記住該檔案的位置。

設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數

Google SDK 會使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數，以服務帳戶身分進行驗證，並存取 Google Cloud 專案的不同 API。

  1. 按照 Google Cloud 服務帳戶金鑰說明文件中的指示設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數
  2. 確認環境變數已在新的終端機 (macOS/Linux) 或指令列 (Windows) 工作階段中設定 (如果您已開啟工作階段，可能需要啟動新的工作階段)
    echo $GOOGLE_APPLICATION_CREDENTIALS

授權給服務帳戶

最後，您需要授權服務帳戶管理 Google 錢包票證。

  1. 開啟 Google Pay 和錢包主控台
  2. 選取「使用者」
  3. 選取「邀請使用者」
  4. 輸入服務帳戶的電子郵件地址 (例如 test-svc@myproject.iam.gserviceaccount.com)
  5. 在「存取層級」下拉式選單中選取「開發人員」或「管理員」
  6. 選取「邀請」

3. 建立通用通行證類別

在這個步驟中，您將為票證建立基礎類別。每次為使用者建立新票證時，系統都會繼承票證類別中定義的屬性。

您在本程式碼研究室中建立的票證類別會利用通用票證的彈性，建立可同時做為身分徽章和挑戰點追蹤器的物件。從這個類別建立的票證物件會如下圖所示。

您可以直接在 Google Pay 和錢包主控台中建立票證類別，也可以使用 Google Wallet API 建立。在本程式碼研究室中，您將使用 API 建立通用通行證類別。這項作業會遵循私人後端伺服器建立通行類別的程序。

  1. 將 google-pay/wallet-android-codelab GitHub 存放區複製到本機工作站
    git clone https://github.com/google-pay/wallet-android-codelab.git
  2. 在終端機或指令列提示中開啟複製的存放區
  3. 前往 backend 目錄 (這些指令碼會模擬後端伺服器動作)
    cd backend
  4. 安裝 Node.js 依附元件
    npm install .
  5. 在 backend 目錄中開啟 generic_class.js
  6. 將 issuerId 的值改為 Google Pay 和錢包主控台中的核發機構 ID
    // TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
  7. 在終端機或指令列提示中執行 generic_class.js 指令碼
    node generic_class.js

程式碼執行時，會建立新的通行證類別並輸出類別 ID。類別 ID 由發卡機構 ID 和開發人員定義的後置字串組成。在這種情況下，後置字串會設為 codelab_class (類似 1234123412341234123.codelab_class 的類別 ID)。輸出記錄也會包含 Google Wallet API 的回應。

4. 在 Android Studio 中開啟專案

您複製的 GitHub 存放區包含一個含有空白活動的 Android 專案。在這個步驟中，您將編輯這個活動，在產品頁面中加入「新增至 Google 錢包」按鈕。

  1. 開啟 Android Studio
  2. 依序選取「檔案」和「開啟」
  3. 選取存放區中的 android 目錄
  4. 選取「開啟」

在應用程式中加入 Google Wallet SDK

  1. 開啟模組層級 Gradle 建構檔案 (android/app/build.gradle)
  2. 將 Google Wallet SDK 新增至 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"
  3. 儲存檔案
  4. 依序選取「File」和「Sync Project with Gradle Files」

5. 建立「新增至 Google 錢包」按鈕

在這個步驟中，您將建立「Add to Google Wallet」按鈕，並新增至現有活動。按鈕的素材資源已納入專案。如要加入按鈕，您必須建立個別的版面配置檔案。新增後，按鈕會如下所示。

「新增至 Google 錢包」按鈕

  1. 建立新的版面配置檔案：app/src/main/res/layout/add_to_google_wallet_button.xml
  2. 將下列內容新增至新版面配置檔案
    <?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>
  3. 在結帳活動版面配置檔案 (app/src/main/res/layout/activity_checkout.xml) 中加入 add_to_google_wallet_button.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. 檢查 Google Wallet API 是否可用

如果使用者在不支援 Google 錢包 API 的裝置上開啟應用程式，在嘗試新增票證時可能會遇到負面體驗。如果使用者的裝置不支援 Google 錢包 API，請隱藏「Add to Google Wallet」按鈕，避免使用者產生疑惑。無法使用 API 的原因有很多，例如 Android 或 Google Play 服務版本過舊，或是 Google 錢包在使用者所在國家/地區無法使用。

在這個步驟中，您將在應用程式中新增邏輯，檢查裝置是否支援 Google Wallet API。如果是，按鈕就會在活動中顯示。否則按鈕就會隱藏。

  1. 在 app/src/main/java/com/google/android/gms/samples/wallet/activity/ 中開啟 CheckoutActivity.kt 檔案
  2. 為 PayClient 例項建立類別屬性
    // TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient
  3. 在 onCreate 方法中將 PayClient 屬性例項化
    // TODO: Instantiate the client
walletClient = Pay.getClient(this)
  4. 建立方法，檢查裝置上是否可使用 Google 錢包 SDK 和 API，並處理結果
    // 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
    }
}
  5. 在 onCreate 方法中呼叫 fetchCanUseGoogleWalletApi 方法，以便檢查 Google Wallet API 是否可用
    // TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()

執行應用程式時，您現在應該會在 UI 中看到「Add to Google Wallet」按鈕。

應用程式活動中現在會顯示「新增至 Google 錢包」按鈕

7. 建立通用通行證物件

確認 Google Wallet API 可供使用後，您就可以建立票證，並提示使用者將票證新增至錢包。為使用者建立票證物件有兩種流程。

在後端伺服器上建立通行證物件

在這種做法中，系統會在後端伺服器上建立通行證物件，並以已簽署的 JWT 格式傳回給用戶端應用程式。這類做法最適合使用者採用率高的情況，因為這可確保使用者在嘗試將物件新增至錢包前，物件已存在。

在使用者將票證新增至錢包時建立票證物件

在這種方法中，系統會定義憑證物件，並將其編碼為後端伺服器上的已簽署 JWT。接著，系統會在參照 JWT 的用戶端應用程式中顯示「Add to Google Wallet」按鈕。使用者選取按鈕時，系統會使用 JWT 建立票證物件。這類情況最適合使用者採用情況不固定或不明的情況，因為這可避免建立並未使用的票證物件。本程式碼研究室會使用這種方法。

  1. 開啟 backend/generic_pass.js 檔案。
  2. 將 issuerId 的值替換為 Google Pay 和錢包主控台的發卡機構 ID
    // TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
  3. 在終端機或指令列提示中執行 generic_pass.js 檔案
    node generic_pass.js
  4. 將輸出符記複製到剪貼簿或文字編輯器

程式碼執行時，會定義新的通行證物件，並將其嵌入 JWT。接著，先前建立的服務帳戶金鑰會簽署 JWT。這可驗證對 Google Wallet API 的要求，因此不需要將憑證儲存在用戶端應用程式中。

在實際工作環境中，您的後端系統會負責建立 JWT 並傳回給用戶端。在本程式碼研究室中，generic_pass.js 指令碼會模擬這項行為，並「傳回」您要在用戶端應用程式中使用的權杖。

8. 將票證新增至 Google 錢包

您已驗證 Google 錢包 API 是否可用，並建立了已簽署的 JWT，因此可以提示使用者將票證新增至錢包。在這個步驟中，您將在「Add to Google Wallet」按鈕中新增事件監聽器，使用 Google Wallet API 將票證儲存至使用者的錢包。

  1. 開啟 app/src/main/CheckoutActivity.kt 檔案。
  2. 將 token 的值替換為先前建立的 JWT
    // TODO: Save the JWT from the backend "response"
private val token = "TOKEN"
  3. 建立類別屬性以儲存要求代碼
    // TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000
  4. 為「新增至 Google 錢包」按鈕設定事件監聽器
    // TODO: Set an on-click listener on the "Add to Google Wallet" button
addToGoogleWalletButton = layout.addToGoogleWalletButton.

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

使用者選取「新增至 Google 錢包」按鈕時，系統會呼叫 walletClient.savePassesJwt 方法。這個方法會提示使用者將新的票證物件新增至 Google 錢包。

9. 處理 savePassesJwt 結果

在本程式碼研究室的最後一個步驟中，您將設定應用程式，以便處理 walletClient.savePassesJwt 作業的結果。

  1. 開啟 app/src/main/CheckoutActivity.kt 檔案。
  2. 覆寫 onActivityResult 方法，以便包含下列程式碼
    // 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
      }
    }
  }
}

您的應用程式現在可以處理下列情境：

  • 已成功新增票證
  • 使用者取消訂單
  • 發生非預期的錯誤

執行應用程式，確認您可以新增票證並處理結果。

10. 恭喜

通用通行證物件的範例。

恭喜！您已成功在 Android 上整合 Google Wallet API！

瞭解詳情

請參閱 google-pay/wallet-android-codelab GitHub 存放區中的完整整合程序。

建立票證並要求取得正式版存取權

準備好在正式版中發行自己的票證時，請前往 Google Pay 和錢包主控台，要求取得正式版存取權並授權 Android 應用程式。

如需瞭解詳情，請參閱 Android SDK 先決條件。