此页面由 Cloud Translation API 翻译。

卡券类和对象概览

您可以发放供最终用户保存在 Google 钱包中的所有卡券几乎都由两个组件定义：卡券类和卡券对象。每次向用户发放卡券时，您都需要一个卡券类和卡券对象实例，该实例可告知 Google Wallet API 要构建哪种类型的卡券，以及要在卡券上显示的详细信息，例如礼品卡的值或票据持有人的姓名。

Google Wallet API 提供了一组预定义的卡券类和卡券对象，您可以根据这些类和卡券对象（例如 GiftCardClass、GiftCardObject、GenericClass 和 GenericObject 等）创建实例，然后使用这些对象创建向用户签发的卡券。

每个卡券类和卡券对象实例均定义为一个 JSON 对象，该对象具有一组必需属性和可选属性，分别对应于相应卡券类型使用的具体用例。

卡券类

将卡券类视为用于创建一个或多个卡券的共享模板您将发布给用户。卡券类定义将包含的一组通用属性所有引用它的卡券。

例如，以下 EventTicketClass 实例定义了即将举办的活动的所有已售门票的通用字段（场馆、活动名称、发卡机构、日期/时间）。

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW"
}

卡券类的每个实例都需要指定 id 属性。该类 ID 用作唯一标识符，每当您使用它创建新的卡券对象时，都会引用该标识符实例。

卡券对象

虽然卡券类的实例可指定一组共用属性，以用于一个或多个卡券，卡券对象会指定发送给特定用户的特定卡券的唯一详细信息。

例如，使用 Google Wallet API 创建活动门票卡券时，EventTicketObject 实例包含分配给该票券的座位的属性，因为这些值对于每个座位都是唯一的车票已签发。

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "9"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "L"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "45"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "7C"
      }
    }
  },
  "barcode": {
    "type": "BARCODE_TYPE_UNSPECIFIED",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}

卡券对象的每个实例都需要指定 id 属性。该对象 ID 用作唯一标识符，供您在向用户签发卡券时参考。

卡券类如何与卡券对象配合使用

卡券对象必须通过引用其类 ID 或包含完整的卡券类定义来扩展卡券类的实例。卡券类和卡券对象实例之间的这种关系表示您可以通过卡券类实例来设置和更新所有已发放卡券通用的属性，和属性。

例如，在下面这个简单的“活动门票”卡券图表中，我们展示了在共享 EventTicketClass 中定义的字段与 EventTicketObject 中定义的特定门票字段的组合方式，以构建最终发放的卡券。请注意卡券类的 ID 是如何在卡券对象的 classId 属性中引用的。

对卡券类实例所做的更改将立即传播到所有卡券对象实例引用它的对象。用户将看到您对卡券类实例所做的任何更改都会体现出来 Google 钱包应用中的卡券。

将卡券添加到用户的 Google 钱包

如需将卡券添加到用户的 Google 钱包，您需要创建一个包含声明的 JSON 网络令牌 (JWT) 您（发卡机构）针对将保存在用户 Google 钱包中的卡券对象实例进行构建 - 最重要的是，您要向用户发出的卡券对象实例的对象 ID。JWT 系统随后会通过添加到 Google 钱包按钮或添加到 Google 钱包将该应用发送给用户链接。

当用户点击将已发放的卡券添加到 Google 钱包中的按钮或链接后，编码到 JWT 中的卡券对象实例与该用户的 Google 账号相关联。这意味着当用户再次点击该按钮时，该卡券对象的链接已存在，因此重复副本将不会添加到用户的电子钱包中。

如果用户从 Google 钱包应用中移除卡券，相应的卡券对象实例为它会自动解除与用户的关联，但不会将其删除。也就是说，用户可以点击 添加到 Google 钱包按钮或重新关联，即可保存卡券，无需需要创建新的卡券对象实例或 JWT。