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

1. 簡介

總覽

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

不過，這些方法不一定適用於所有用途。如要享有更個人化的體驗，可以使用一般票證類型。以下列舉一般票證類型的幾種用途：

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

泛型票證可用於任何能展示的產品用途：

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

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

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

傳遞類別和物件

Google Wallet API 提供建立以下項目的方法：

類型

說明

票證類別

個別票證物件的範本。含有屬於這個類別的所有票證物件通用的資訊。

傳遞物件

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

程式碼研究室簡介

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

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

必要條件

目標

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

  • 在 Android 應用程式中加入 Google 錢包 SDK
  • 檢查 Android 裝置是否提供 Google Wallet API
  • 建立「新增至 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 控制台中，開啟「服務帳戶」。
  2. 輸入服務帳戶的名稱、ID 和說明
  3. 選取「建立並繼續」
  4. 選取「完成」

建立服務帳戶金鑰

  1. 選取服務帳戶
  2. 選取「KEYS」KEYS選單
  3. 依序選取「新增金鑰」和「建立新的金鑰」
  4. 選取「JSON」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 (類別 ID 類似於 1234123412341234123.codelab_class)。輸出記錄中也會包含 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. 在「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"
    加入 Google 錢包 SDK
  3. 儲存檔案
  4. 依序選取「File」和「Sync Project with Gradle Files」。

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

在這個步驟中，您將建立「新增至 Google 錢包」按鈕，並新增至現有活動中。按鈕素材資源先前已納入專案。如要加入按鈕，請建立獨立的版面配置檔案。新增完成後，按鈕會如下所示。

「新增至 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 Wallet API 的裝置上開啟應用程式，可能會在使用者嘗試新增票證時造成負面影響。如果使用者的裝置不支援 Google Wallet API，只要隱藏「新增至 Google 錢包」按鈕，即可避免造成混淆。導致 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 方法
    // TODO: Instantiate the client
walletClient = Pay.getClient(this)
    中的 PayClient 屬性執行個體化
  4. 建立方法，檢查裝置是否支援 Google Wallet 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 中應該會顯示「新增至 Google 錢包」按鈕。

現在應用程式活動會顯示「新增至 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 Wallet API，並已建立已簽署的 JWT，現在可以提示使用者將票證新增至錢包。在這個步驟中，您將在「新增至 Google 錢包」按鈕中新增事件監聽器，透過 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. 處理 keepPassesJwt 結果

在本程式碼研究室的最後一個步驟中，您要設定應用程式來處理 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 必要條件。