使用 Google Wallet API 在網路上建立票證

1. 簡介

總覽

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

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

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

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

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

會議活動的 Google 錢包票證範例

如要進一步瞭解 Google Wallet API，或在網頁上新增 [新增至 Google 錢包] 按鈕，請參閱 Google 電子錢包開發人員說明文件。

傳遞類別和物件

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

類型

說明

票證類別

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

傳遞物件

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

程式碼研究室簡介

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

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

必要條件

目標

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

  • 使用 Google 錢包建立票證物件
  • 建立「新增至 Google 錢包」按鈕

支援

如果困在程式碼研究室的任何時間點，請前往 google-pay/wallet-web-codelab GitHub 存放區查看完整的解決方案。

2. 設定

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

申請 Google 電子錢包發卡機構帳戶

您必須擁有發卡機構帳戶，才能建立及發布 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. 啟動 Node.js 範例應用程式

時間長度 10:00

在這個步驟中，您將執行範例 Node.js 應用程式，做為購物網站和後端伺服器使用。

複製範例存放區

google-pay/wallet-web-codelab 存放區包含一個以 Node.js 為基礎的範例專案和不同的指令碼檔案，這些檔案模擬用於佈建票證類別和物件的後端伺服器。您需要編輯這些條件，在產品詳細資料畫面上加入「新增至 Google 錢包」按鈕。

  1. 將存放區複製到本機工作站
    git clone https://github.com/google-pay/wallet-web-codelab.git

安裝專案依附元件

  1. 在終端機或指令列提示中開啟複製的存放區
  2. 前往 web 目錄 (您將在本程式碼研究室的其餘部分修改的應用程式)
    cd web
  3. 安裝 Node.js 依附元件
    npm install .
  4. 啟動應用程式
    node app.js
  5. 開啟在 http://localhost:3000 上執行的應用程式

範例網頁應用程式，其中有「輸入電子郵件地址」和「建立票證」按鈕的欄位

如果您輸入電子郵件地址並選取「建立票證」，系統不會採取任何動作。在後續步驟中，您將設定應用程式以建立新的票證類別和物件。

4. 建立通用票證類別

在這個步驟中，您將建立票證的基本類別。每當為使用者建立新票證，該票證都會沿用票證類別中定義的屬性。

您在本程式碼研究室中建立的票證類別，採用一般票證的靈活彈性，可建立同時做為身分徽章和挑戰點數追蹤工具的物件。透過這個類別建立票證物件後，該物件會如下圖所示。

您可以直接在 Google Pay 和電子錢包主控台，或使用 Google Wallet API。在本程式碼研究室中，您將使用 API 建立「一般票證」類別。上述程序遵循私人後端伺服器建立票證類別時使用的程序。

  1. 開啟 web/app.js 檔案。
  2. 將 issuerId 的值替換成 Google Pay 的發卡機構 ID。錢包控制台
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. 找出 createPassClass 函式
  4. 在函式中，建立通過驗證的 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 (類別 ID 類似於 1234123412341234123.codelab_class)。輸出記錄中也會包含 Google Wallet API 的回應。

5. 建立一般票證物件

在這個步驟中，您將設定 Node.js 應用程式，以使用先前建立的類別建立一般傳遞物件。為使用者建立票證物件的流程有兩種。

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

在此方法中，票證物件會在後端伺服器上建立，然後以已簽署的 JWT 形式傳回用戶端應用程式。這最適合使用者的採用率較高的情況，因為這個方法能確保物件在使用者嘗試將物件加入錢包前，確實存在。

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

在此方法中，系統會定義票證物件，並編碼至後端伺服器上的已簽署 JWT。系統隨即會在參照 JWT 的用戶端應用程式中，顯示「Add to Google Wallet」按鈕。使用者選取按鈕後，系統會使用 JWT 建立票證物件。這最適合用於使用者採用行為可能變動或不明的情況，因為這樣會讓系統無法建立和不使用傳遞物件。本程式碼研究室將使用這個方法。

  1. 開啟 web/app.js 檔案。
  2. 找出 createPassObject 函式
  3. 在函式中，為使用者定義新的票證物件
    // 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，並傳回可透過「新增至 Google 錢包」按鈕使用的連結。使用者選取按鈕後，系統會提示他們將票證儲存至錢包。

  1. 建立 JWT 憑證附加資訊，並使用服務帳戶私密金鑰進行編碼，接著傳回含有內嵌連結的「新增至 Google 錢包」按鈕
    // 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>`);
  2. 在瀏覽器中重新載入執行的應用程式
  3. 在表單中輸入您的電子郵件地址，然後選取「建立票證」
  4. 畫面上出現時，選取「新增至 Google 錢包」按鈕

已成功在應用程式前端顯示「新增至 Google 錢包」按鈕

7. 恭喜

一般票證物件範例

恭喜，您已成功整合 Google Wallet API 網頁版！

瞭解詳情

前往 google-pay/wallet-web-codelab GitHub 存放區查看完全整合。

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

準備好在正式版中核發自己的票證時，請前往 Google Pay 和錢包控制台，要求取得正式版權限。

詳情請參閱 Web API 必要條件。