卡券类和对象概览

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

Google Wallet API 提供了一组预定义的卡券类和卡券对象,您可以为其创建实例,然后用于创建发放给用户的卡券,例如 GiftCardClassGiftCardObjectGenericClassGenericObject 等。

每个卡券类和卡券对象实例均定义为一个 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 Web 令牌 (JWT),其中包含您(颁发者)就将保存在用户 Google 钱包中的卡券对象实例(最重要的是您要向用户签发的卡券对象实例的对象 ID)做出的声明。然后,通过 Add to Google Wallet(添加到 Google 钱包)按钮或 Add to Google Wallet(添加到 Google 钱包)链接将 JWT 传送给用户。

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

如果用户从 Google 钱包应用中移除卡券,则相应的卡券对象实例会自动与用户解除关联,但不会被删除。也就是说,用户可以再次点击添加到 Google 钱包按钮或链接来保存卡券,而无需创建新的卡券对象实例或 JWT。