1. 简介
概览
借助 Google Wallet API，您可以通过各种类型的卡券与用户互动：会员卡、优惠、礼品卡、活动门票、公交票卡、登机牌等。每种卡券类型（或卡券类）都有特定于用例的字段和功能，以增强用户体验。
但是，这些方法可能并不适用于所有应用场景。若要打造更个性化的体验，您可以使用通用卡券类型。以下是通用卡券类型的一些用例：
- 停车券
- 图书馆会员卡
- 储值代金券
- 健身房会员卡
- 预留
您可以将通用卡券用于以下任何可呈现的用例：
- 信息最多为三行
- （可选）条形码图片
- （可选）“详细信息”部分
如需详细了解 Google Wallet API 或如何向网页添加添加到 Google 钱包按钮，请参阅 Google 钱包开发者文档。
传递类和对象
Google Wallet API 提供了用于创建以下内容的方法：
类型 | 说明 |
卡券类别 | 单个卡券对象的模板。它包含属于此类的所有卡券对象的通用信息。 |
传递对象 | 用户 ID 独有的卡券类实例。 |
关于此 Codelab
在此 Codelab 中，您将完成以下任务。
- 在演示模式下创建新的发卡机构账号
- 创建用于签发卡券的服务账号
- 创建新的通用卡券类
- 创建新的卡券对象
- 创建添加到 Google 钱包按钮以保存卡券
- 在网页中显示按钮
- 处理卡券保存结果
前提条件
- Git
- 一个有权访问 Google Cloud 控制台的 Google 账号
- Node.js 10 或更高版本
目标
完成此 Codelab 后，您将能够执行以下操作：
- 使用 Google 钱包创建卡券对象
- 创建添加到 Google 钱包按钮
支持
如果您在此 Codelab 中遇到困难，请查看 google-pay/wallet-web-codelab GitHub 代码库包含的完整解决方案以供参考。
2. 设置
在此步骤中，您将在演示模式下创建发卡机构账号。这样，您就可以创建可添加到用户钱包的卡券类和对象。接下来，您将创建 Google Cloud 项目和服务账号。这些卡券将用于以编程方式创建卡券类和对象，具体方式与后端服务器相同。最后，您将授权 Google Cloud 服务账号管理您的 Google 钱包发卡机构账号中的卡券。
注册 Google 电子钱包发行方账号
必须拥有发卡机构账号才能为 Google 钱包创建和分发卡券。您可以使用 Google Pay &钱包控制台。最初，您可以在演示模式下创建卡券。这意味着，只有特定测试用户可以添加您创建的卡券。您可以在 Google Pay 中管理测试用户，钱包控制台。
如需详细了解演示模式，请参阅通用通过前提条件。
- 打开 Google Pay 和钱包控制台
- 按照屏幕上的说明创建发卡机构账号
- 选择 Google Wallet API
- 确认你了解服务条款和隐私权政策
- 将 Issuer ID（颁发者 ID）值复制到文本编辑器或其他位置
- 在管理标签页下，选择设置测试账号
- 添加您将在此 Codelab 中使用的任何电子邮件地址
启用 Google Wallet API
- 登录 Google Cloud 控制台。
- 如果您还没有 Google Cloud 项目，请立即创建一个（如需了解详情，请参阅创建和管理项目）
- 为您的项目启用 Google Wallet API（也称为 Google Pay for Passs API）
创建服务账号和密钥
必须有服务账号和服务账号密钥才能调用 Google Wallet API。服务账号是调用 Google Wallet API 的身份。该服务账号密钥包含一个私钥，用于将您的应用标识为服务账号。此密钥属于敏感信息，因此请务必保密。
创建服务账号
- 在 Google Cloud 控制台中，打开服务账号
- 为您的服务账号输入名称、ID 和说明
- 选择创建并继续
- 选择完成
创建服务账号密钥
- 选择您的服务账号
- 选择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. 启动示例 Node.js 应用
时长：10:00
在此步骤中，您将运行一个充当购物网站和后端服务器的示例 Node.js 应用。
克隆示例代码库
google-pay/wallet-web-codelab 代码库包含一个基于 Node.js 的示例项目和不同的脚本文件，这些文件模拟用于配置卡券类和对象的后端服务器。您将通过修改这些信息，在商品详情屏幕上添加添加到 Google 钱包按钮。
- 将代码库克隆到本地工作站
git clone https://github.com/google-pay/wallet-web-codelab.git
安装项目依赖项
- 在终端或命令行提示符中打开克隆的代码库
- 导航到
web目录（您将在此 Codelab 的其余部分中修改该应用）cd web - 安装 Node.js 依赖项
npm install . - 启动应用
node app.js - 打开在 http://localhost:3000 上运行的应用
如果您输入电子邮件地址并选择创建卡券，则不会执行任何操作。在接下来的步骤中，您将配置应用以创建新的卡券类和对象。
4. 创建通用卡券类
在此步骤中，您将为卡券创建基类。每次为用户创建新卡券时，该卡券都将继承卡券类中定义的属性。
您将在此 Codelab 中创建的卡券类利用通用卡券的灵活性来创建可用作身份徽章和挑战积分跟踪器的对象。从此类创建卡券对象后，它将如下图所示。
您可以直接在 Google Pay 和钱包控制台或使用 Google Wallet API。在此 Codelab 中，您将使用该 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（类 ID 看起来类似于 1234123412341234123.codelab_class）。输出日志还包含来自 Google Wallet API 的响应。
5. 创建通用卡券对象
在此步骤中，您将配置 Node.js 应用，以使用您之前创建的类创建通用卡券对象。为用户创建卡券对象的流程有两个。
在后端服务器上创建卡券对象
在此方法中，卡券对象在后端服务器上创建，并作为已签名的 JWT 返回给客户端应用。这最适合用户采用率高的情况，因为它可以确保在用户尝试将其添加到钱包之前对象已存在。
在用户将卡券添加到钱包时创建卡券对象
在此方法中，传递对象定义并编码到后端服务器上的已签名 JWT 中。然后，引用 JWT 的客户端应用会呈现添加到 Google 钱包按钮。当用户选择该按钮时，JWT 即用于创建卡券对象。这最适合用户采用情况可变或未知的情况，因为它会阻止创建和不使用传递对象。此 Codelab 将用到此方法。
- 打开
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 并返回可在添加到 Google 钱包按钮中使用的链接。当用户选择该按钮时，系统会提示他们将卡券保存到钱包。
- 创建 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>`); - 重新加载浏览器中运行的应用
- 在表单中输入您的电子邮件地址，然后选择创建卡券
- 在系统显示该图标后，选择添加到 Google 钱包按钮
7. 恭喜
恭喜！您已成功集成 Google Wallet API on Web！
了解详情
如需查看完整集成，请访问 google-pay/wallet-web-codelab GitHub 代码库。
创建卡券并申请正式版访问权限
当您准备好在生产环境中发放自己的卡券后，请前往 Google Pay 和钱包控制台，以申请正式版访问权。
如需了解详情，请参阅 Web API 前提条件。