触发推送通知

合作伙伴触发的通知

添加消息和通知

背景

用户添加卡券后，您可能需要向其发送与该卡券相关的消息，并确保用户收到通知。使用 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。

在 Passes 类中添加消息并发送通知的 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"
    },
  …

示例 Response，用于添加消息并针对通行卡类进行通知

  // 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 方法更新的特定字段子集（如下所述）触发。在发出更新卡券的 API 调用后，会发生以下情况：

  1. 系统会触发推送通知，并在用户的锁定屏幕上显示，告知用户有卡券更新。
  2. 用户点按通知后，Google 钱包会打开卡券的前端（即卡片视图），用户会在屏幕顶部看到一个带有“查看更新”按钮的标注。
  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
    },
  ]
}

预期行为

当用户位于指定的 MerchantLocation 时，应收到有关其卡券的粘性通知。 如果用户点击通知，系统会在 Google 钱包中打开相应卡券。 用户可以通过滑动操作关闭通知。当用户离开相应位置时，通知会消失。

由 Google 钱包触发的自动通知

即将到来的通知

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

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

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

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

  class.eventName

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

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

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