触发推送通知

合作伙伴触发的通知

添加消息和通知

背景

用户添加卡券后，您可能希望向他们发送与卡券相关的消息，并确保他们收到相关通知。使用 Add Message API 请求（message_type 等于 TEXT_AND_NOTIFY ）时，会发生以下情况：

  1. 系统会在“卡券背面”（又称“详细信息 模板”）中添加“消息” 项，并向保存了该卡券的用户发送推送通知。
  2. 用户点按通知后，系统会打开 Google 钱包，并显示卡券正面（又称“卡片视图”），用户会在屏幕顶部看到一个标注，其中包含“查看消息”按钮。
  3. 点击该标注后，用户会进入卡券背面，其中会突出显示新的未读消息。

向用户发送包含通知的消息时的一些注意事项

  • 用户必须为其卡券启用通知功能，才能接收与消息相关的推送通知。
  • 消息可能包含指向您的网站或应用的 URI。超链接必须是与卡券相关的网站或应用。如果用户点击的链接与卡券无关，则违反了 使用限制政策 。
  • 在 24 小时内，您最多可以发送 3 条会触发推送通知的消息。如果您向用户发送垃圾信息，Google 可能会限制您的推送通知发送配额。
  • 用户在锁定屏幕上看到的推送通知由 Google 钱包控制。
  • 您可以使用 UPDATE 或 PATCH 方法，通过常规类或对象 端点修改或移除消息数据。

集成步骤

如果您想在添加新发卡机构消息后通知用户，则需要使用 AddMessage API，并更新AddMessageRequest ，以便包含新文本的Message 具有MessageType TEXT_AND_NOTIFY，而不是TEXT。

在卡券类中添加消息和通知的 JSON 请求示例

  …
  "id": ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Class message header",
        "body": "My Class message body with a <a href="https://wallet.google">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

在卡券对象中添加消息和通知的 JSON 请求示例

  …
  "id": OBJECT_ID",
  "classId": "ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Object message header",
        "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

为卡券类添加消息和通知的响应示例

  // The updated resource
  …
    {
      "kind": "walletobjects#walletObjectMessage",
      "header": "My Object message header",
      "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
      "id": "message_id",
      "messageType": "textAndNotify"
    },
  …

异常处理

如果尝试通知超过 3 次，系统会返回 QuotaExceededException 响应。如需进一步更新 卡券，可以使用“TEXT”而不是 “TEXT_AND_NOTIFY”，如集成 步骤中所述。

更新字段和通知

背景

用户添加卡券后，您可能希望在更新某些 字段时触发推送通知。通知将显示在用户的锁定屏幕上，并告知他们卡券有 更新。此通知仅适用于使用 UPDATE 和 PATCH API 方法定义的特定字段子集 below。发出更新卡券的 API 调用后，会发生以下情况：

  1. 系统会触发推送通知，并在用户的锁屏上显示，告知他们 卡券已更新。
  2. 用户点按通知后，系统会打开 Google 钱包，并显示卡券正面（又称“卡片视图”），用户会在屏幕顶部看到一个标注，其中包含“查看更新”按钮。
  3. 点击该按钮后，用户会进入一个屏幕，其中会显示 更新更改的字段。

发送字段更新通知时的一些注意事项

  • 用户必须为其卡券启用通知功能，才能接收与更新相关的推送通知 。
  • 只有当活动或航班的开始时间在 3 小时内时，系统才会触发通知，以避免向用户发送垃圾信息。
  • 在 24 小时内，您最多可以发送 3 条会触发推送通知的更新。 如果您向用户发送垃圾信息，Google 可能会限制您的推送通知发送配额。
  • 用户在锁定屏幕上看到的推送通知由 Google 钱包控制。
  • notifyPreference 字段是一个临时字段 ，仅在此请求中存在。对于您希望触发通知的未来请求，您 必须在类或对象请求中重置此字段。

集成步骤

如需触发这些通知，您需要使用现有的 UPDATE 或 PATCH 调用，并指定 notifyPreference。更新类或对象中的字段时，您可以 向类或对象请求添加新字段 notifyPreference，以触发 通知。

在类中更新和通知的 JSON 请求示例

    …
    "dateTime":
        {
            "kind": "walletobjects#eventDateTime",
            "doorsOpen": "2024-09-23T19:20:50.00"
        },
    "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
    "notifyPreference": "notifyOnUpdate",
    …

将 notifyPreference 设置为 notifyOnUpdate 将触发通知，前提是更新的字段目前受支持。

支持的字段

EventTicketClass
  • eventName
  • eventVenue.name
  • eventvenue.address
  • eventDateTime.doorsOpen
  • eventDateTime.start
EventTicketObject
  • eventSeat.seat
  • eventSeat.row
  • eventSeat.section
  • eventSeat.gate

可在附近使用时发送通知

此功能会向已启用通知并授予 Google 钱包应用精确位置信息访问权限（始终开启）的用户显示推送通知，提醒他们已保存与当前位置相关的卡券。

集成步骤

使用方法

如需使用此功能，您需要向类和对象添加位置。每个类最多可以添加 10 个位置，每个对象最多可以添加 10 个位置。在类或对象定义中使用 MerchantLocations。您可以在使用 insert、patch 或 update 方法时添加这些位置。

向类或对象添加位置后，Google 会在用户位于附近时向其发送通知。Google 会决定用户需要靠近到什么程度，以及需要在该区域停留多长时间才会发送通知。Google 还会控制通知的文本。

以下是设置了 MerchantLocations 的 LoyaltyClass 示例： 
{
  "kind": "walletobjects#loyaltyClass",
  "programLogo": {
  "kind": "walletobjects#image",
  "sourceUri": {
    "uri":
    ...
  }
  },
  "localizedProgramName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Program Name",
    }
  },
  "id": Id1234,
  "version": "1",
  "allowMultipleUsersPerObject": true,
  "reviewStatus": "underReview",
  "enableSmartTap": false,
  "localizedIssuerName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Issuer Name"
    }
  },
  "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
  "merchantLocations": [
    {
      "latitude": 37.79020867928078,
      "longitude": -122.39004
    },
    {
      "latitude": 37.42587,
      "longitude": -122.08620
    },
  ]
}

预期行为

当用户位于指定的 MerchantLocations 之一时，应收到有关其卡券的固定通知。 如果他们点击通知，系统会在 Google 钱包中打开他们的卡券。 用户可以通过滑动操作关闭通知。当用户离开该位置时，通知将消失。

Google 钱包触发的自动通知

即将到来的通知

Google 钱包会在活动开始前三小时向用户发送通知。活动时间由 class.dateTime.start. 定义。

若要接收此通知，用户必须启用通知功能。如需检查此功能是否已启用，用户可以 转至设置 > 通知 ，并查看卡券的动态是否已 开启。

如果用户启用了在锁屏状态上显示通知的设置，那么通知会显示在通知区域和锁屏状态中。

通知采用以下不可修改的格式： 

  class.eventName

如果用户点按通知并解锁设备，Google 钱包应用中会显示他们的卡券。

如果用户有多张卡券，系统只会显示即将可用的卡券。如果他们根据将多个活动门票归为一组添加了已分组的 卡券，通知仅会显示组中的一张卡券。不过，当用户点按该通知时，可以左右滑动以查看该组中的其他卡券。

通知会被固定，而不是在用户打开后自动关闭。自动关闭的时间是 class.dateTime.start 之后 60 分钟。