使用 Google Wallet API 在网页上创建卡券

1. 简介

概览

借助 Google Wallet API，您可以通过各种类型的卡券与用户互动：会员卡、优惠券、礼品卡、活动门票、公交票卡、登机牌等。每种卡券类型（或卡券类）都附带特定于用例的字段和功能，以提升用户体验。

不过，这些可能并不适用于所有用例。如需打造更个性化的体验，您可以使用通用卡券类型。以下是通用卡券类型的一些用例：

  • 停车券
  • 图书馆会员卡
  • 储值代金券
  • 健身房会员卡
  • 预留

凡是能够以以下形式展示的用例，您都可以为其使用通用卡券：

  • 最多三行信息
  • （可选）条形码图片
  • （可选）“详情”部分

会议活动的 Google 钱包卡券示例

如需详细了解 Google Wallet API 或如何向网页添加添加到 Google 钱包按钮，请参阅 Google 钱包开发者文档。

传递类和对象

Google Wallet API 公开了用于创建以下内容的方法：

类型

说明

卡券类

单个卡券对象的模板。它包含属于此类的所有卡券对象共有的信息。

传递对象

与用户 ID 唯一对应的卡类实例。

关于此 Codelab

在此 Codelab 中，您将完成以下任务。

  1. 在演示模式下创建新的发卡机构账号
  2. 创建用于签发卡券的服务账号
  3. 创建新的通用卡券类
  4. 创建新的卡券对象
  5. 创建添加到 Google 钱包按钮以保存卡券
  6. 在网页中显示按钮
  7. 处理卡券保存结果

前提条件

目标

完成此 Codelab 后，您将能够执行以下操作：

  • 使用 Google 钱包创建卡券对象
  • 创建添加到 Google 钱包按钮

支持

如果您在 Codelab 中的任何步骤遇到问题，可以参阅 google-pay/wallet-web-codelab GitHub 代码库中的完整解决方案。

2. 设置

在此步骤中，您将在演示模式下创建一个发卡人账号。这样，您就可以创建可添加到用户钱包的卡类和对象。接下来，您将创建一个 Google Cloud 项目和服务账号。这些类和对象将用于以与后端服务器相同的方式以编程方式创建通行密钥类和对象。最后，您将授权 Google Cloud 服务账号管理 Google 钱包发卡人账号中的卡券。

注册 Google 钱包发卡机构账号

您必须拥有发卡人账号，才能为 Google 钱包创建和分发卡券。您可以使用 Google Pay & Wallet 控制台进行注册。最初，您将能够在演示模式下创建卡券。这意味着，只有特定的测试用户才能添加您创建的卡券。您可以在 Google Pay & Wallet 控制台中管理测试用户。

如需详细了解演示模式，请参阅通用通行前提条件。

  1. 打开 Google Pay & Wallet 控制台
  2. 按照屏幕上的说明创建发卡人账号
  3. 选择 Google Wallet API
  4. 确认您了解服务条款和隐私权政策
  5. 将颁发者 ID 值复制到文本编辑器或其他位置
  6. 在管理标签页下，选择设置测试账号
  7. 添加您在此 Codelab 中将使用的所有电子邮件地址

启用 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菜单
  3. 依次选择添加密钥和创建新密钥
  4. 选择 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 & Wallet 控制台
  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 目录（您将在此 Codelab 的其余部分中修改此应用）
    cd web
  3. 安装 Node.js 依赖项
    npm install .
  4. 启动应用
    node app.js
  5. 打开在 http://localhost:3000 上运行的应用

一个示例 Web 应用，其中包含用于输入电子邮件地址的字段和一个“创建卡券”按钮

如果您输入电子邮件地址并选择创建卡券，系统不会执行任何操作。在后续步骤中，您将配置应用以创建新的卡券类和对象。

4. 创建通用卡券类

在此步骤中，您将为卡券创建基类。每当为用户创建新的卡券时，该卡券都会继承卡券类中定义的属性。

您在此 Codelab 中创建的卡券类利用通用卡券的灵活性来创建一个既可用作身份徽章，又可用作挑战积分跟踪器的对象。通过此类创建卡券对象时，其将如下图所示。

您可以直接在 Google Pay 和钱包控制台中或使用 Google Wallet API 创建卡券类。在此 Codelab 中，您将使用该 API 创建通用卡券类。这遵循了专用后端服务器创建通行密钥类的过程。

  1. 打开 web/app.js 文件
  2. 将 issuerId 的值替换为 Google Pay & Wallet 控制台中的发卡机构 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 创建卡券对象。这最适合用户采用情况不稳定或未知的情况，因为它可以防止创建了但未使用的通行密钥对象。本 Codelab 将使用此方法。

  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 钱包

“Add to Google Wallet”（添加到 Google 钱包）按钮在应用前端上成功呈现

7. 恭喜

通用传递对象示例

恭喜，您已成功在网站上集成 Google Wallet API！

了解详情

如需查看完整集成，请参阅 google-pay/wallet-web-codelab GitHub 代码库。

创建卡券并申请正式版发布权限

当您准备好在生产环境中发布自己的卡券时，请前往 Google Pay 和钱包控制台，申请正式版发布权限。

如需了解详情，请参阅 Web API 前提条件。