程式碼研究室簡介
1. 簡介
總覽
您可以透過 Google Wallet API 提供各種票證,與使用者互動,例如會員卡、優惠、禮物卡、活動票券、大眾運輸車票、登機證等。每個票證類型 (或票證類別) 都會提供特定用途的欄位和功能,以提升使用者體驗。
不過,這些可能不適用於所有用途。如要打造更貼近需求的體驗,您可以使用通用票證類型。以下是一般票證類型的幾個範例用途:
- 停車證
- 圖書館會員卡
- 儲值券
- 健身房會員卡
- 保留項目
您可以使用通用票證,用於以下任何用途:
- 最多三列資訊
- (選用) 條碼圖片
- (選用) 詳細資料專區
如要進一步瞭解 Google Wallet API,或在 Android 應用程式中新增「新增至 Google 錢包」按鈕,請參閱 Google Wallet 開發人員說明文件。
傳遞類別和物件
Google Wallet API 會公開方法,用於建立下列項目:
類型 | 說明 |
票證類別 | 個別票證物件的範本。其中包含屬於此類別的所有通行證物件共用的資訊。 |
傳遞物件 | 使用者 ID 專屬的通行證類別例項。 |
程式碼研究室簡介
在本程式碼研究室中,您將完成下列工作。
- 在示範模式中建立新的核發機構帳戶
- 建立服務帳戶以核發票證
- 建立新的一般票證類別
- 建立新的票證物件
- 建立「新增至 Google 錢包」按鈕,以便儲存票證
- 在 Android 應用程式中顯示按鈕
- 處理票證儲存結果
必要條件
- Android Studio
- Git
- 可存取 Google Cloud 控制台的 Google 帳戶
- Node.js 10 以上版本
目標
完成本程式碼研究室後,您將能夠執行下列操作:
- 在 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 和錢包主控台管理測試使用者。
如要進一步瞭解展示模式,請參閱通用通行證先決條件。
- 開啟 Google Pay 和錢包主控台
- 按照畫面上的指示建立發布者帳戶
- 選取「Google Wallet API」
- 確認您瞭解服務條款和隱私權政策
- 將「發出者 ID」值複製到文字編輯器或其他位置
- 在「管理」分頁中,選取「設定測試帳戶」。
- 新增您將在本程式碼研究室中使用的電子郵件地址
啟用 Google Wallet API
- 登入 Google Cloud 控制台
- 如果您尚未建立 Google Cloud 專案,請立即建立 (詳情請參閱「建立及管理專案」)
- 為專案啟用 Google Wallet API (也稱為 Google Pay for Passes API)
建立服務帳戶和金鑰
您必須具備服務帳戶和服務帳戶金鑰,才能呼叫 Google Wallet API。服務帳戶是呼叫 Google Wallet API 的身分。服務帳戶金鑰包含私密金鑰,可將您的應用程式識別為服務帳戶。這組金鑰屬於機密資料,請妥善保密。
建立服務帳戶
建立服務帳戶金鑰
- 選取服務帳戶
- 選取「KEYS」KEYS選單
- 依序選取「新增金鑰」和「建立新的金鑰」。
- 選取「JSON」金鑰類型
- 選取「建立」
系統會提示您將金鑰檔案儲存至本機工作站。請務必記住該檔案的位置。
設定 GOOGLE_APPLICATION_CREDENTIALS
環境變數
Google SDK 會使用 GOOGLE_APPLICATION_CREDENTIALS
環境變數,以服務帳戶身分進行驗證,並存取 Google Cloud 專案的不同 API。
- 按照 Google Cloud 服務帳戶金鑰說明文件中的指示設定
GOOGLE_APPLICATION_CREDENTIALS
環境變數 - 確認環境變數已在新的終端機 (macOS/Linux) 或指令列 (Windows) 工作階段中設定 (如果您已開啟工作階段,可能需要啟動新的工作階段)
echo $GOOGLE_APPLICATION_CREDENTIALS
授權給服務帳戶
最後,您需要授權服務帳戶管理 Google 錢包票證。
- 開啟 Google Pay 和錢包主控台
- 選取「使用者」
- 選取「邀請使用者」
- 輸入服務帳戶的電子郵件地址 (例如
test-svc@myproject.iam.gserviceaccount.com
) - 在「存取層級」下拉式選單中選取「開發人員」或「管理員」
- 選取「邀請」
3. 建立通用通行證類別
在這個步驟中,您將為票證建立基礎類別。每次為使用者建立新票證時,系統都會繼承票證類別中定義的屬性。
您在本程式碼研究室中建立的票證類別會利用通用票證的彈性,建立可同時做為身分徽章和挑戰點追蹤器的物件。從這個類別建立的票證物件會如下圖所示。
您可以直接在 Google Pay 和錢包主控台中建立票證類別,也可以使用 Google Wallet API 建立。在本程式碼研究室中,您將使用 API 建立通用通行證類別。這項作業會遵循私人後端伺服器建立通行類別的程序。
- 將 google-pay/wallet-android-codelab GitHub 存放區複製到本機工作站
git clone https://github.com/google-pay/wallet-android-codelab.git
- 在終端機或指令列提示中開啟複製的存放區
- 前往
backend
目錄 (這些指令碼會模擬後端伺服器動作)cd backend
- 安裝 Node.js 依附元件
npm install .
- 在
backend
目錄中開啟generic_class.js
- 將
issuerId
的值改為 Google Pay 和錢包主控台中的核發機構 ID// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - 在終端機或指令列提示中執行
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 錢包」按鈕。
- 開啟 Android Studio
- 依序選取「檔案」和「開啟」
- 選取存放區中的
android
目錄 - 選取「開啟」
在應用程式中加入 Google Wallet SDK
- 開啟模組層級 Gradle 建構檔案 (
android/app/build.gradle
) - 將 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" - 儲存檔案
- 依序選取「File」和「Sync Project with Gradle Files」
5. 建立「新增至 Google 錢包」按鈕
在這個步驟中,您將建立「Add to Google Wallet」按鈕,並新增至現有活動。按鈕的素材資源已納入專案。如要加入按鈕,您必須建立個別的版面配置檔案。新增後,按鈕會如下所示。
- 建立新的版面配置檔案:
app/src/main/res/layout/add_to_google_wallet_button.xml
- 將下列內容新增至新版面配置檔案
<?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> - 在結帳活動版面配置檔案 (
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。如果是,按鈕就會在活動中顯示。否則按鈕就會隱藏。
- 在
app/src/main/java/com/google/android/gms/samples/wallet/activity/
中開啟CheckoutActivity.kt
檔案 - 為
PayClient
例項建立類別屬性// TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient - 在
onCreate
方法中將PayClient
屬性例項化// TODO: Instantiate the client
walletClient = Pay.getClient(this) - 建立方法,檢查裝置上是否可使用 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
}
} - 在
onCreate
方法中呼叫fetchCanUseGoogleWalletApi
方法,以便檢查 Google Wallet API 是否可用// TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()
執行應用程式時,您現在應該會在 UI 中看到「Add to Google Wallet」按鈕。
7. 建立通用通行證物件
確認 Google Wallet API 可供使用後,您就可以建立票證,並提示使用者將票證新增至錢包。為使用者建立票證物件有兩種流程。
在後端伺服器上建立通行證物件
在這種做法中,系統會在後端伺服器上建立通行證物件,並以已簽署的 JWT 格式傳回給用戶端應用程式。這類做法最適合使用者採用率高的情況,因為這可確保使用者在嘗試將物件新增至錢包前,物件已存在。
在使用者將票證新增至錢包時建立票證物件
在這種方法中,系統會定義憑證物件,並將其編碼為後端伺服器上的已簽署 JWT。接著,系統會在參照 JWT 的用戶端應用程式中顯示「Add to Google Wallet」按鈕。使用者選取按鈕時,系統會使用 JWT 建立票證物件。這類情況最適合使用者採用情況不固定或不明的情況,因為這可避免建立並未使用的票證物件。本程式碼研究室會使用這種方法。
- 開啟
backend/generic_pass.js
檔案。 - 將
issuerId
的值替換為 Google Pay 和錢包主控台的發卡機構 ID// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - 在終端機或指令列提示中執行
generic_pass.js
檔案node generic_pass.js
- 將輸出符記複製到剪貼簿或文字編輯器
程式碼執行時,會定義新的通行證物件,並將其嵌入 JWT。接著,先前建立的服務帳戶金鑰會簽署 JWT。這可驗證對 Google Wallet API 的要求,因此不需要將憑證儲存在用戶端應用程式中。
在實際工作環境中,您的後端系統會負責建立 JWT 並傳回給用戶端。在本程式碼研究室中,generic_pass.js
指令碼會模擬這項行為,並「傳回」您要在用戶端應用程式中使用的權杖。
8. 將票證新增至 Google 錢包
您已驗證 Google 錢包 API 是否可用,並建立了已簽署的 JWT,因此可以提示使用者將票證新增至錢包。在這個步驟中,您將在「Add to Google Wallet」按鈕中新增事件監聽器,使用 Google Wallet API 將票證儲存至使用者的錢包。
- 開啟
app/src/main/CheckoutActivity.kt
檔案。 - 將
token
的值替換為先前建立的 JWT// TODO: Save the JWT from the backend "response"
private val token = "TOKEN" - 建立類別屬性以儲存要求代碼
// TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000 - 為「新增至 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
作業的結果。
- 開啟
app/src/main/CheckoutActivity.kt
檔案。 - 覆寫
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 先決條件。