Google Wallet 生产 Class ID 获取？完整创建教程

2025-04-03 09:39:44

搞定 Google Wallet Class ID：从测试迈向生产的关键一步

不少开发者在把 Google Wallet 会员卡集成从测试环境转向生产环境时，都会遇到一个坎：Demo 里的 Class ID 用着挺顺手，但轮到自己正式上线，这个 ‘Class ID’ 该从哪儿来呢？Google Wallet Console 界面翻了个遍，文档也查了，就是找不到地方直接 ‘获取’ 或者 ‘生成’ 一个现成的 Class ID。就像下面这张图显示的，“Loyalty classes” 区域看着挺直观，但新的 Class ID 到底在哪里？

别急，这事儿其实不复杂，只是理解上可能有点绕。

为啥会找不到 Class ID？

这个疑惑通常源于一个常见的误解。Demo 项目能跑通，是因为 Google 已经预先配置好了演示用的 Class ID，让你能快速看到效果。但到了生产环境，情况变了：你需要为你自己的会员卡项目创建一个专属的“模板”，这个模板就是所谓的 “Class ”。

Class ID 不是一个你去“领取”或“发现”的号码，而是你在创建这个 Class（模板）时，需要 自己定义 的一个唯一标识符。 Google Wallet Console 不会凭空给你一个 Class ID，它需要你先创建一个 Class，在这个过程中指定 ID。简单说，流程是：先创建 Class -> 定义 Class ID -> Class 创建成功 -> 你就有了 Class ID。

解决方案：创建你的会员卡 Class

下面是具体步骤，带你一步步在 Google Wallet Console 中创建会员卡 Class 并拿到你需要的 Class ID。

第一步：登录并找到正确位置

登录 Google Pay & Wallet Console: 打开你的浏览器，访问 Google Pay & Wallet Console 并用你的开发者账号登录。确保你已经申请并通过了 Google Wallet API 的访问权限。
导航到会员卡: 在控制台左侧菜单，找到并点击 “Google Wallet API”。然后，在展开的选项中选择“会员卡 (Loyalty cards)”（或者类似的名称，界面可能会微调）。

第二步：动手创建 Class

找到创建按钮: 在“会员卡 (Loyalty classes)” 页面，你应该能看到一个明显的按钮，比如“创建类 (Create class)”或类似的字样。勇敢地点下去！这才是生成 Class ID 的入口。
填写 Class 信息: 点击创建后，会弹出一个表单，需要你填写关于这个会员卡模板的详细信息。这步是关键，特别是 Class ID 的定义：
- 发卡机构名称 (Issuer name): 填你的公司名或品牌名，这个会显示在卡片上。比如：“XX咖啡”或“YY超市”。
- 类 ID (Class ID): 核心来了！ 这里需要你 手动输入 一个字符串作为这个 Class 的唯一标识。
  - 重要规则: 这个 ID 在你的发卡机构 ID (Issuer ID) 下必须是独一无二的。不能跟你的其他 Class ID 重复。
  - 命名建议: 为了清晰和避免冲突，推荐使用 你的IssuerID.自定义性名称 的格式。
    - Issuer ID 是你在注册 Google Wallet API 时，Google 分配给你的那一长串数字 ID（在控制台账户设置或概览里能找到）。
    - 自定义性名称 可以是你的项目名、卡片类型、版本号等，用字母、数字、下划线或点号组合。例如：12345678901234567890.cool_rewards_program_v1 或 12345678901234567890.mycoffeeshop.level1。
  - 务必记下这个 ID ，后续代码集成全靠它。
- 会员计划名称 (Loyalty program name): 你的会员计划叫什么名字？比如“XX咖啡常客积分”或“YY超市尊享会员”。这个也会展示给用户。
- 其他字段: 根据你的会员卡设计，填写其他必填和选填字段，比如：
  - Logo
  - 卡片标题 (Program logo)
  - 背景色
  - 文本模块 (Text modules) - 用于显示积分、等级、提示语等
  - 链接模块 (Links module) - 添加官网、App 下载等链接
  - 条码类型和值 (Barcode type & value) - 如何生成用户的唯一条码或二维码。注意，这里定义的是条码类型和一个 占位符 模式（比如 loyaltyId），具体的值是在创建单个卡片对象 (Object) 时动态提供的。
  - 位置信息 (Locations) - 如果有实体店，可以添加地理位置信息。
  - 等等... 详细配置你的卡片模板。
保存 Class: 仔细检查所有信息，特别是 Class ID 确认无误后，点击页面底部的“保存 (Save)”或“创建 (Create)”按钮。

第三步：找到并确认你的 Class ID

创建成功后，系统会处理你的请求。通常很快，页面会刷新或跳转回“会员卡 (Loyalty classes)”列表。这时，你应该能在列表里看到刚刚创建的那个 Class，以及它对应的、由你亲手定义的 Class ID 。

现在，你就成功获取了用于生产环境的 Class ID！

如何在代码里使用 Class ID

拿到了这个来之不易的 Class ID，怎么用在你的应用集成里呢？主要是在两个环节：

创建会员卡对象 (Object): 当你需要为某个具体用户生成一张会员卡时（比如用户注册会员后），你需要调用 Google Wallet API 来创建一个“Object”。在这个 Object 的数据结构里，必须明确指定它属于哪个 “Class”，这时就要用到你的 Class ID。

示例 (REST API JSON payload 片段):

{
  "classId": "YOUR_ISSUER_ID.your_class_id_here", // <--- 把你刚创建的 Class ID 填在这里
  "id": "YOUR_ISSUER_ID.unique_object_id_for_user_123", // 每个用户的卡片实例也需要一个唯一 ID
  "state": "active",
  "loyaltyPoints": {
    "balance": {
      "string": "500"
    },
    "label": "积分"
  },
  "accountId": "user_account_id_in_your_system",
  "accountName": "用户的昵称",
  // ... 其他根据 Class 定义的字段和数据
}

生成 “添加到 Google Wallet” 按钮或链接的 JWT: 为了让用户能方便地把他们的会员卡保存到 Google Wallet，你通常会提供一个按钮或链接。点击这个按钮/链接会触发一个流程，其中关键一步是生成一个签名的 JSON Web Token (JWT)。这个 JWT 的 payload 里需要包含要添加的卡片信息，其中就包括了 Class ID。

示例 (JWT Payload 片段):

{
  "iss": "your_service_account_email@developer.gserviceaccount.com", // 你的服务账号邮箱
  "aud": "google",
  "typ": "savetowallet",
  "origins": ["https://your-website.com"],
  "payload": {
    "loyaltyObjects": [ // 或者可能是 "genericObjects", "offerObjects" 等，取决于卡类型
      {
        "classId": "YOUR_ISSUER_ID.your_class_id_here", // <--- Class ID 又出现了
        "id": "YOUR_ISSUER_ID.unique_object_id_for_user_123"
        // ... 可能还需要包含足够创建或更新 Object 的信息
      }
    ]
  }
}

一些额外的建议和技巧

Class ID 命名规范: 再次强调，IssuerID.ClassName 是个好习惯。保持一致性，加入版本号（如 _v1, _v2）能帮你更好地管理卡片模板的迭代。
Issuer ID 很重要: 确保你知道你的 Google Wallet Issuer ID，并且在定义 Class ID 时正确使用了它。这个 ID 是你整个 Wallet 集成的基础。
先测试，再上线: 即使你拿到了生产环境的权限和 Class ID，也强烈建议先用这些真实的 ID 在你的测试用户或内部用户中进行充分测试，确保流程顺畅、卡片显示正常。Google Wallet API 通常也支持测试环境或标记测试 Object。
Class 的更新: 一旦 Class 创建完成并且有用户保存了基于这个 Class 的卡片 (Object)，对 Class 的某些修改（比如 Logo、颜色）会自动同步到用户的 Wallet 中。但有些结构性改动可能不会，或者需要特殊处理。修改 Class 前最好查阅官方文档关于 Class 更新的部分。
管理多个 Class: 如果你的业务有多种会员等级或类型的卡片，你可能需要创建多个 Class，每个都有自己唯一的 Class ID。