卡券类和对象概览

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

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

每个卡券类和卡券对象实例均定义为 JSON 对象,该对象包含一组必需属性和可选属性,这些属性与适用于该卡券类型的特定用例相对应。

Pass 类

您可以将卡券类视为用于创建一个或多个将发行给用户的卡券的共享模板。Pass 类定义了一组通用属性,这些属性将包含在引用它的所有卡券中。

例如,以下 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"
}
  

Pass 类的每个实例都需要一个由您指定的 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 中定义的特定门票的字段如何组合来构建最终签发的卡券。请注意卡券对象的 classId 属性中如何引用卡券类的 ID。

对卡券类实例所做的更改将立即传播到引用该实例的所有卡券对象实例。用户下次同步时,将看到您对卡券类实例所做的任何更改都会反映在其 Google 钱包应用中的卡券上。

向用户的 Google 钱包添加卡券

如需将卡券添加到用户的 Google 钱包,您需要创建一个 JSON Web 令牌 (JWT),其中包含您(颁发者)针对将保存在用户的 Google 钱包中的卡券对象实例(最重要的是您要向用户签发的卡券对象实例的对象 ID)做出的声明。然后,通过 Add to Google Wallet 按钮或 Add to Google Wallet 链接将 JWT 提供给用户。

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

如果用户从 Google 钱包应用中移除卡券,系统会自动解除与用户关联的卡券对象实例,但不会将其删除。这意味着,用户可以再次点击添加到 Google 钱包按钮或链接,保存卡券,而无需创建新的卡券对象实例或 JWT。