程式碼研究室簡介
1. 簡介
總覽
您可以透過 Google Wallet API 提供各種票證，與使用者互動，例如會員卡、優惠、禮物卡、活動票券、大眾運輸車票、登機證等。每個票證類型 (或票證類別) 都會提供特定用途的欄位和功能，以提升使用者體驗。
不過，這些方法可能不適用於所有用途。如要打造更符合個人需求的體驗，您可以使用通用票證類型。以下是通用票證類型的幾個範例用途：
- 停車證
- 圖書館會員卡
- 儲值券
- 健身房會員卡
- 保留項目
您可以使用通用票證，用於以下任何用途：
- 最多三列資訊
- (選用) 條碼圖片
- (選用) 詳細資料專區
如要進一步瞭解 Google Wallet API，或在網頁中新增「Add to Google Wallet」按鈕，請參閱 Google Wallet 開發人員說明文件。
傳遞類別和物件
Google Wallet API 提供方法，可建立下列項目：
類型 | 說明 |
票證類別 | 個別票證物件的範本。其中包含屬於此類別的所有通行證物件共用的資訊。 |
傳遞物件 | 使用者 ID 專屬的票證類別例項。 |
程式碼研究室簡介
在本程式碼研究室中，您將完成下列工作。
- 在示範模式中建立新的核發機構帳戶
- 建立服務帳戶以核發票證
- 建立新的一般票證類別
- 建立新的通行證物件
- 建立「新增至 Google 錢包」按鈕，以便儲存票證
- 在網頁中顯示按鈕
- 處理票證儲存結果
必要條件
- Git
- 可存取 Google Cloud 控制台的 Google 帳戶
- Node.js 10 以上版本
目標
完成本程式碼研究室後，您將能夠執行下列操作：
- 使用 Google 錢包建立票證物件
- 建立「新增至 Google 錢包」按鈕
支援
如果在程式碼研究室中遇到任何問題，請參考 google-pay/wallet-web-codelab GitHub 存放區中的完整解決方案。
2. 設定
在這個步驟中，您將在示範模式下建立核發機構帳戶。這樣一來，您就能建立可新增至使用者錢包的票證類別和物件。接下來，您將建立 Google Cloud 專案和服務帳戶。這些類別和物件會以與後端伺服器相同的方式，透過程式輔助方式建立。最後，您將授權 Google Cloud 服務帳戶管理 Google 錢包發卡機構帳戶中的票證。
申請 Google 錢包發卡機構帳戶
您必須擁有發布者帳戶，才能建立及發布 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」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. 啟動 Node.js 範例應用程式
時間長度 10:00
在這個步驟中，您將執行用於購物網站和後端伺服器的 Node.js 應用程式範例。
複製範例存放區
google-pay/wallet-web-codelab 存放區包含以 Node.js 為基礎的範例專案，以及模擬用於佈建憑證類別和物件的後端伺服器的不同指令碼檔案。您將編輯這些檔案，在產品詳細資料畫面中加入「Add to Google Wallet」按鈕。
- 將存放區複製到本機工作站
git clone https://github.com/google-pay/wallet-web-codelab.git
安裝專案依附元件
- 在終端機或指令列提示中開啟複製的存放區
- 前往
web目錄 (這是您將在本程式碼研究室的其餘部分中修改的應用程式)cd web - 安裝 Node.js 依附元件
npm install . - 啟動應用程式
node app.js - 開啟在 http://localhost:3000 上執行的應用程式
如果輸入電子郵件地址並選取「建立票證」，系統不會顯示任何內容。在後續步驟中，您將設定應用程式，以便建立新的票證類別和物件。
4. 建立通用通行證類別
在這個步驟中，您將為票證建立基礎類別。每次為使用者建立新票證時，系統都會繼承票證類別中定義的屬性。
您在本程式碼研究室中建立的票證類別會利用通用票證的彈性，建立可同時做為身分證件和挑戰點追蹤器的物件。從這個類別建立票證物件時，會如下圖所示。
您可以直接在 Google Pay 和錢包主控台中建立票證類別，也可以使用 Google 錢包 API。在本程式碼研究室中，您將使用 API 建立通用通行證類別。這項作業會遵循私人後端伺服器建立通行類別的程序。
- 開啟
web/app.js檔案。 - 將
issuerId的值改為 Google Pay 和錢包主控台中的核發機構 ID// TODO: Define Issuer ID
const issuerId = 'ISSUER_ID'; - 找出
createPassClass函式 - 在函式中建立已驗證的 HTTP 用戶端，並使用 Google Wallet API 建立新的票證類別
// TODO: Create a Generic pass class
let genericClass = {
'id': `${classId}`,
'classTemplateInfo': {
'cardTemplateOverride': {
'cardRowTemplateInfos': [
{
'twoItems': {
'startItem': {
'firstValue': {
'fields': [
{
'fieldPath': 'object.textModulesData["points"]'
}
]
}
},
'endItem': {
'firstValue': {
'fields': [
{
'fieldPath': 'object.textModulesData["contacts"]'
}
]
}
}
}
}
]
},
'detailsTemplateOverride': {
'detailsItemInfos': [
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.imageModulesData["event_banner"]'
}
]
}
}
},
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.textModulesData["game_overview"]'
}
]
}
}
},
{
'item': {
'firstValue': {
'fields': [
{
'fieldPath': 'class.linksModuleData.uris["official_site"]'
}
]
}
}
}
]
}
},
'imageModulesData': [
{
'mainImage': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
},
'contentDescription': {
'defaultValue': {
'language': 'en-US',
'value': 'Google I/O 2022 Banner'
}
}
},
'id': 'event_banner'
}
],
'textModulesData': [
{
'header': 'Gather points meeting new people at Google I/O',
'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
'id': 'game_overview'
}
],
'linksModuleData': {
'uris': [
{
'uri': 'https://io.google/2022/',
'description': 'Official I/O \'22 Site',
'id': 'official_site'
}
]
}
};
let response;
try {
// Check if the class exists already
response = await httpClient.request({
url: `${baseUrl}/genericClass/${classId}`,
method: 'GET'
});
console.log('Class already exists');
console.log(response);
} catch (err) {
if (err.response && err.response.status === 404) {
// Class does not exist
// Create it now
response = await httpClient.request({
url: `${baseUrl}/genericClass`,
method: 'POST',
data: genericClass
});
console.log('Class insert response');
console.log(response);
} else {
// Something else went wrong
console.log(err);
res.send('Something went wrong...check the console logs!');
}
}
程式碼執行時，會建立新的通行證類別並輸出類別 ID。類別 ID 由核發機構 ID 和開發人員定義的後置字串組成。在這種情況下，後置字串會設為 codelab_class (類似 1234123412341234123.codelab_class 的類別 ID)。輸出記錄也會包含 Google Wallet API 的回應。
5. 建立通用通行證物件
在這個步驟中，您將設定 Node.js 應用程式，以便使用先前建立的類別建立通用傳遞物件。為使用者建立票證物件的流程有兩種。
在後端伺服器上建立通行證物件
在這種做法中，系統會在後端伺服器上建立通行證物件，並以已簽署的 JWT 格式傳回給用戶端應用程式。這類做法最適合使用者採用率高的情況，因為這可確保使用者在嘗試將物件加入錢包前，物件已存在。
在使用者將票證新增至錢包時建立票證物件
在這種方法中，系統會定義憑證物件，並將其編碼為後端伺服器上的已簽署 JWT。接著，系統會在參照 JWT 的用戶端應用程式中顯示「Add to Google Wallet」按鈕。使用者選取按鈕時，系統會使用 JWT 建立票證物件。這類情況最適合使用者採用度不穩定或不明時，因為這可避免建立和未使用的票證物件。本程式碼研究室會使用這種方法。
- 開啟
web/app.js檔案。 - 找出
createPassObject函式 - 在函式中為使用者定義新的票證物件
// TODO: Create a new Generic pass for the user
let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
let objectId = `${issuerId}.${objectSuffix}`;
let genericObject = {
'id': `${objectId}`,
'classId': classId,
'genericType': 'GENERIC_TYPE_UNSPECIFIED',
'hexBackgroundColor': '#4285f4',
'logo': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg'
}
},
'cardTitle': {
'defaultValue': {
'language': 'en',
'value': 'Google I/O \'22'
}
},
'subheader': {
'defaultValue': {
'language': 'en',
'value': 'Attendee'
}
},
'header': {
'defaultValue': {
'language': 'en',
'value': 'Alex McJacobs'
}
},
'barcode': {
'type': 'QR_CODE',
'value': `${objectId}`
},
'heroImage': {
'sourceUri': {
'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
}
},
'textModulesData': [
{
'header': 'POINTS',
'body': '1234',
'id': 'points'
},
{
'header': 'CONTACTS',
'body': '20',
'id': 'contacts'
}
]
};
// TODO: Create the signed JWT and link
res.send("Form submitted!");
如果您重新載入應用程式、輸入電子郵件地址並提交表單，就不會看到任何輸出內容。後端應用程式會定義通行證物件，但不會傳回任何輸出。接下來，您將票證轉換為「新增至 Google 錢包」連結。
6. 建立「新增至 Google 錢包」按鈕
在最後一個步驟中，您將建立已簽署的 JWT，並傳回可用於「Add to Google Wallet」按鈕的連結。使用者選取按鈕時，系統會提示他們將票證儲存到電子錢包。
- 建立 JWT 權利要求，使用服務帳戶私密金鑰進行編碼，並傳回含有內嵌連結的「Add to Google Wallet」按鈕
// TODO: Create the signed JWT and link
const claims = {
iss: credentials.client_email,
aud: 'google',
origins: [],
typ: 'savetowallet',
payload: {
genericObjects: [
genericObject
]
}
};
const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
const saveUrl = `https://pay.google.com/gp/v/save/${token}`;
res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`); - 重新載入在瀏覽器中執行的應用程式
- 在表單中輸入電子郵件地址，然後選取「建立票證」
- 選取「新增至 Google 錢包」按鈕
7. 恭喜
恭喜！您已成功在網路上整合 Google Wallet API！
瞭解詳情
請前往 google-pay/wallet-web-codelab GitHub 存放區，查看完整的整合程序。
建立票證並要求正式版存取權
準備好在正式版中發行自己的票證時，請前往 Google Pay 和錢包主控台申請正式版存取權。
詳情請參閱「Web API 先決條件」。