使用 Google Wallet API 在 Android 上创建卡券

1. 简介

概览

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

但是，这些方法可能并不适用于所有应用场景。若要打造更个性化的体验，您可以使用通用卡券类型。以下是通用卡券类型的一些用例：

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

您可以将通用卡券用于以下任何可呈现的用例：

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

一部演示“添加到 Google 钱包”配置流程的 Android 设备

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

传递类和对象

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

类型

说明

卡券类别

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

传递对象

用户 ID 独有的卡券类实例。

关于此 Codelab

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

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

前提条件

目标

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

  • 将 Google Wallet SDK 添加到您的 Android 应用
  • 检查 Google Wallet API 在 Android 设备上是否可用
  • 创建添加到 Google 钱包按钮

支持

如果您在此 Codelab 中遇到困难，请查看 google-pay/wallet-android-codelab GitHub 代码库包含的完整解决方案以供参考。

2. 设置

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

注册 Google Wallet API 发卡机构账号

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

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

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

启用 Google Wallet API

  1. 登录 Google Cloud 控制台。
  2. 如果您还没有 Google Cloud 项目，请立即创建一个（如需了解详情，请参阅创建和管理项目）
  3. 为您的项目启用 Google Wallet API（也称为 Google Pay for Passs 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 和钱包控制台
  2. 选择用户
  3. 选择邀请用户
  4. 输入服务账号的电子邮件地址（例如 test-svc@myproject.iam.gserviceaccount.com）
  5. 从访问权限级别下拉菜单中选择开发者或管理员
  6. 选择邀请

3. 创建通用卡券类

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

您将在此 Codelab 中创建的卡券类利用通用卡券的灵活性来创建可用作身份徽章和挑战积分跟踪器的对象。从此类创建卡券对象后，它将如下图所示。

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

  1. 将 google-pay/wallet-android-codelab GitHub 代码库克隆到本地工作站
    git clone https://github.com/google-pay/wallet-android-codelab.git
  2. 在终端或命令行提示符中打开克隆的代码库
  3. 导航到 backend 目录（这些脚本模拟后端服务器操作）
    cd backend
  4. 安装 Node.js 依赖项
    npm install .
  5. 在 backend 目录中，打开 generic_class.js。
  6. 将 issuerId 的值替换为您在 Google Pay 中的发卡机构 ID，钱包控制台
    // TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
  7. 在终端或命令行提示符中，运行 generic_class.js 脚本
    node generic_class.js

代码运行时，将创建一个新的卡券类并输出类 ID。类 ID 由发卡机构 ID 后跟开发者定义的后缀组成。在本例中，后缀设置为 codelab_class（类 ID 看起来类似于 1234123412341234123.codelab_class）。输出日志还包含来自 Google Wallet API 的响应。

4. 在 Android Studio 中打开项目

您克隆的 GitHub 代码库包含一个具有空 activity 的 Android 项目。在此步骤中，您将在此活动中进行修改，以在商品页面上添加添加到 Google 钱包按钮。

  1. 打开 Android Studio
  2. 选择文件，然后选择打开
  3. 选择代码库中的 android 目录
  4. 选择打开

将 Google Wallet SDK 添加到您的应用

  1. 打开模块级 Gradle build 文件 (android/app/build.gradle)
  2. 将 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"
  3. 保存文件。
  4. 选择 File，然后选择 Sync Project with Gradle Files

5. 创建 “添加到 Google 钱包”按钮

在此步骤中，您将创建一个添加到 Google 钱包按钮，并将其添加到现有 activity。该按钮的素材资源已包含在项目中。如需添加该按钮，您需要创建一个单独的布局文件。添加后，该按钮将如下所示。

“添加到 Google 钱包”按钮

  1. 创建新的布局文件：app/src/main/res/layout/add_to_google_wallet_button.xml
  2. 将以下内容添加到新的布局文件
    <?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>
  3. 在结账 activity 布局文件 (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 Wallet API 的设备上打开您的应用，则可能会在尝试添加卡券时产生负面的体验。如果用户的设备不支持 Google Wallet API，则隐藏添加到 Google 钱包按钮可避免潜在混淆。有多种原因可能会导致该 API 不可用，例如 Android 或 Google Play 服务版本过旧或者 Google 钱包在用户所在的国家/地区不可用。

在此步骤中，您将向应用添加用于检查 Google Wallet API 在设备上是否可用的逻辑。若是如此，按钮将呈现在 activity 中。否则，该按钮将被隐藏。

  1. 在 app/src/main/java/com/google/android/gms/samples/wallet/activity/ 中打开 CheckoutActivity.kt 文件
  2. 为 PayClient 实例创建类属性
    // TODO: Create a client to interact with the Google Wallet API
private lateinit var walletClient: PayClient
  3. 在 onCreate 方法中实例化 PayClient 属性
    // TODO: Instantiate the client
walletClient = Pay.getClient(this)
  4. 创建一个方法，用于检查设备上是否提供了 Google Wallet 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
    }
}
  5. 在 onCreate 方法中调用 fetchCanUseGoogleWalletApi 方法，以检查 Google Wallet API 是否可用
    // TODO: Check if the Google Wallet API is available
fetchCanUseGoogleWalletApi()

现在，运行应用时，您应该会在界面中看到 Add to Google Wallet 按钮。

“添加到 Google 钱包”按钮现在显示在应用活动中

7. 创建通用卡券对象

现在您已验证 Google Wallet API 可用，可以创建卡券并提示用户将它添加到钱包。为用户创建卡券对象的流程有两个。

在后端服务器上创建卡券对象

在此方法中，卡券对象在后端服务器上创建，并作为已签名的 JWT 返回给客户端应用。这最适合用户采用率高的情况，因为它可以确保在用户尝试将其添加到钱包之前对象已存在。

在用户将卡券添加到钱包时创建卡券对象

在此方法中，传递对象定义并编码到后端服务器上的已签名 JWT 中。然后，引用 JWT 的客户端应用会呈现添加到 Google 钱包按钮。当用户选择该按钮时，JWT 即用于创建卡券对象。这最适合用户采用情况可变或未知的情况，因为它会阻止创建和不使用传递对象。此 Codelab 将用到此方法。

  1. 打开 backend/generic_pass.js 文件
  2. 将 issuerId 的值替换为您在 Google Pay 中的发卡机构 ID，钱包控制台
    // TODO: Define Issuer ID
let issuerId = 'ISSUER_ID';
  3. 在终端或命令行提示符中，运行 generic_pass.js 文件
    node generic_pass.js
  4. 将输出令牌复制到剪贴板或文本编辑器

当您的代码运行时，它将定义一个新的卡券对象，并将其嵌入 JWT。然后，使用您之前创建的服务账号密钥为 JWT 签名。这将对向 Google Wallet API 发出的请求进行身份验证，这样，客户端应用就不需要存储凭据。

在生产环境中，您的后端系统将负责创建 JWT 并将其返回给客户端。在此 Codelab 中，generic_pass.js 脚本会模拟此行为并“返回”供您在客户端应用中使用的令牌。

8. 将卡券添加到 Google 钱包

现在，您已经验证了 Google Wallet API 可用且已创建已签名的 JWT，接下来可以提示用户将卡券添加到其钱包中。在此步骤中，您将向添加到 Google 钱包按钮添加监听器，以便使用 Google Wallet API 将卡券保存到用户的钱包中。

  1. 打开 app/src/main/CheckoutActivity.kt 文件
  2. 将 token 的值替换为您之前创建的 JWT
    // TODO: Save the JWT from the backend "response"
private val token = "TOKEN"
  3. 创建一个类属性来存储请求代码
    // TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000
  4. 为添加到 Google 钱包按钮设置监听器
    // TODO: Set an on-click listener on the "Add to Google Wallet" button
addToGoogleWalletButton = layout.addToGoogleWalletButton.

addToGoogleWalletButton.setOnClickListener {
  walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
}

当用户选择 Add to Google Wallet 按钮时，系统会调用 walletClient.savePassesJwt 方法。此方法提示用户将新的卡券对象添加到 Google 钱包。

9. 处理 SavePassesJwt 结果

在此 Codelab 的最后一步中，您将配置应用以处理 walletClient.savePassesJwt 操作的结果。

  1. 打开 app/src/main/CheckoutActivity.kt 文件
  2. 替换 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 前提条件。