觸發推播通知

合作夥伴觸發的通知

新增訊息並通知

背景

使用者新增票證後，您可能想傳送與票證相關的訊息，並確保使用者收到通知。使用 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"
    },
  …

範例 Response，可新增訊息並通知「Pass Class」

  // 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」，詳情請參閱「整合步驟」。

更新欄位並發送通知

背景

使用者新增票證後，您可能會想在更新特定欄位時觸發推播通知。通知會顯示在使用者螢幕鎖定畫面上，告知他們票證有更新。只有在更新或修補下列欄位時，才會觸發這項通知。呼叫 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 會觸發通知，前提是目前支援更新的欄位。

支援的欄位

FlightObject
  • boardingAndSeatingInfo.seatNumber
  • boardingAndSeatingInfo.seatAssignment

鄰近分享通知

如果使用者已啟用通知，並授予 Google 錢包應用程式精確位置資訊的「一律允許」存取權，系統就會顯示推播通知，提醒他們已儲存與目前位置相關的票證。

整合步驟

使用方法

如要使用這項功能，請在類別和物件中新增位置資訊。每個類別和物件最多可新增 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.localScheduledDepartureDateTime 定義。

如要收到這種通知，使用者必須先啟用通知功能。如要確認是否已啟用通知功能，使用者可依序前往「設定」>「通知」，查看是否已啟用「票證最新消息」。

如果使用者已 啟用螢幕鎖定的通知功能，則該通知會顯示在通知區域和螢幕鎖定畫面中。

通知的格式如下 (此格式無法修改)： 

  Boarding pass for your flight to class.destination.airportIataCode

使用者只要輕觸通知並解鎖裝置，相關票證就會顯示在 Google 錢包應用程式中。

如果使用者同時擁有多張票證，系統只會顯示時間最接近當下的可用票證。如果使用者新增了群組票證 (如將多份登機證分成一組一節所述)，則系統只會顯示該群組中的一張票證。不過使用者輕觸通知時，可以向左或向右滑動來查看群組中的其他票證。

使用者開啟通知後，該通知會固定顯示且不會自動關閉，在 class.localScheduledDepartureDateTime 過後 60 分鐘，該通知才會自動關閉。

航班更新通知

在使用者新增了一或多張登機證之後，如果航班的某些欄位發生變更，該名使用者就會在裝置上收到推播通知。不過，這種情況只有在符合特定條件時才會發生。

出發地航廈和登機門

如果您變更了 class.origin.terminal 或 class.origin.gate，並且符合下列條件，系統就會傳送欄位已變更的通知。

  • 距離 class.localScheduledDepartureDateTime 不到三小時。

通知訊息的格式如下：「順風航空已將登機門變更為 A1」。您無法更改這個格式。

登機時間和起飛時間

如果您變更了 class.localBoardingDateTime 或 class.localEstimatedOrActualDepartureDateTime，並且符合下列條件，系統就會傳送欄位已變更的通知。

  • 距離 class.localScheduledDepartureDateTime 不到 24 小時。
  • 時間分別提前或延後 10 分鐘以上。

通知的格式如下：「順風航空已將登機時間變更為晚上 6:00」。通知格式或語言無法自訂。