應用實例

請選取下列其中一個票證類別，進一步瞭解相關使用方式。

Google Pay API for Passes 可讓你透過優惠與使用者互動。本指南討論的概念將協助你進一步瞭解已儲存優惠的功用。

以下應用實例僅適用於「優惠」類別：

更新票證。
優惠到期通知。
地理圍欄通知。
處理過期的票證。
連結已儲存的票證。
從已儲存的票證連出。

更新票證

如果票證在建立後有所異動，請使用 REST API 向使用者告知相關變更。如果相關變更只會影響類別，您也可以使用 Google Pay Merchant Center。票證更新是與使用者互動的重要方式。

如要更新票證的顯示方式 (例如標誌變更時)，您只需要對 OfferClass 進行 update 或 patch，或使用 Google Pay Merchant Center 即可。Google 會將這項資訊套用到與更新後的 OfferClass 相關聯的所有 OfferObject。凡是在 OfferClass 層級定義的所有欄位，均應採取這樣的做法。

如要更新單一票證 (例如優惠到期時間變更時)，您必須對單一 OfferObject 進行 update 或 patch。凡是在 OfferObject 層級定義的所有欄位，均應採取這樣的做法。

有時候，您可能不曉得資料是在何時變更，或是不確定要在什麼時候觸發 update 或 patch 要求。在這種情況下，請針對每個類別和物件安排定期的 update 或 patch 要求。如果您呼叫 OfferClass list 方法，就可以找到特定發卡機構帳戶的所有類別。如果呼叫 OfferObject list 方法，就可以找到特定類別的所有物件。

優惠到期通知

為了提醒使用者在優惠到期前使用優惠，系統會在優惠到期的 48 小時前觸發預設通知。優惠必須符合下列條件才能觸發通知：

必須未曾在使用者的裝置上觸發過到期通知。
validTimeInterval.end.date 中必須設有落在未來的有效到期 datetime。
必須已儲存在使用者的裝置上超過 12 小時。
可寫入的欄位 disableExpirationNotification 不得設為 True。這個欄位根據預設是設為 false。

以下螢幕截圖顯示無法修改的預設通知範例：

優惠將於 (今天、明天、[x] 天後) 到期

`class.title`

`class.titleImage`

您無法自訂優惠到期通知的標頭。

暫停顯示時段

如果根據設定，優惠到期通知是在使用者當地時間下午 10 點到上午 6 點之間顯示，則優惠會在這段時間範圍之前或之後顯示。

自訂優惠到期通知時間

您可以使用 OfferObjects 或 OfferClasses 中的 message.displayInterval.start.date 欄位自訂 Offer 到期通知的顯示時間。如果設定了自訂通知時間，到期通知的觸發依據將是 message.displayInterval.start.date，而不是從 validTimeInterval.end.date 計算得出的預設邏輯。以下是自訂到期通知時間的範例：

{
  “message”: {
   “messageType”: “expirationNotification”,
   “displayInterval”: {
     “start”: {
      “date”: datetime
     }
   }
  }
}

displayInterval.start.date 是用來設定通知顯示的時間，最多可設定為到期日前 30 天。如果指定的時間超過 30 天，就會在 30 天前觸發通知。這則訊息不需要標頭和內文欄位，就算包含這些欄位，系統也不會使用。

地理圍欄通知

Google 可根據消費者與您所定義位置的距離，觸發與消費者已儲存物件相關的通知。

地理位置資訊的新增方式包含以下兩種：

您在建立 Google Pay API for Passes Merchant Center 帳戶時，系統會使用 Google 地圖中的地理位置資訊。
您可以透過 REST API 將座標新增至物件或類別中。

如要瞭解如何將座標新增至物件或類別中，請參閱使用 REST API 新增地理位置資訊。

地理圍欄概念

Google 會使用 Google 地圖中的地理位置資訊，以演算法來判斷使用者是否位於特定商店或區域。透過 Google Pay API for Passes Merchant Center 帳戶建立的所有類別和物件都適用這項偵測功能。

這套演算法的偵測依據包含全球衛星定位系統、Wi-Fi、藍牙、動作、停留時間和其他因素。如果系統判斷使用者確實在某個位置，就會觸發地理圍欄通知。

您在 Object 中手動指定座標之後，系統就會在使用者距離該座標 150 公尺時觸發地理圍欄通知。

地理圍欄通知的頻率、限制和停用設定

使用者每天最多可以接收四則通知。

如果一個地理圍欄中同時存有多個物件，則系統會向各個 Google Pay API for Passes Merchant Center 帳戶顯示一則含有輪轉介面且無法修改的通知訊息。物件會在這個輪轉介面中循環顯示：

如要讓地理圍欄通知順利運作，使用者必須在 Google Pay 應用程式的通知設定中啟用「商品最新消息」，並為裝置啟用定位服務。

使用 REST API 新增地理位置資訊

您可以在類別或物件中指定位置陣列 (緯度和經度)。Google 會根據與類別或物件相關聯的位置清單確認使用者目前所在的地理位置，並在使用者距離其中一個位置 150 公尺以內時發出通知。以下提供程式碼範例，示範如何在類別或物件中指定位置：

資源

{
  ... //Class or Object content

  "locations": [{
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.422087,
    "longitude": -161446
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.429379,
    "longitude": -121.12272999999999
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.333646,
    "longitude": -122.884853
  }]
}

Java

List<LatLongPoint> locations = new ArrayList<LatLongPoint>();
locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude(
    -122.161446));
locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude(
    -121.12272999999999));
locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude(
    -122.884853));

yourClassOrObject.setLocations(locations);

PHP

$locations = array(
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.442087,
    'longitude' => -122.161446
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.429379,
    'longitude' => -122.12272999999999
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.333646,
    'longitude' => -121.884853
  )
);

Python

offer_class_object = {
  # class or object content
  'locations': [{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.442087,
    'longitude': -122.161446
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.429379,
    'longitude': -122.12272999999999
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.333646,
    'longitude': -121.884853
  }]
}

處理過期的票證

開啟 Google Pay 應用程式後，使用者可在「票證」分頁下方的「過期的票證」專區查看所有封存票證和無效票證。如果票證符合下列一或多項條件，系統就會將其移至「過期的票證」專區：

當 object.validTimeInterval.end.date 過期時。在 object.validTimeInterval.end.date 到期後，票證隨時會移至「過期的票證」，最多不會超過 24 小時。
當 object.state 欄位標記為 Expired、Inactive 或 Completed 時。

連結已儲存的票證

使用者儲存票證後，請參照其 objectId 以連結票證。

請使用以下連結來參照票證：

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

您可以透過 Google Pay 應用程式或網路瀏覽器查看票證。

從已儲存的 Google Pay 票證連出

您可以在已儲存的 Google Pay 票證標題下方，連結至您的應用程式或網站。這項功能適用於所有類型的 Google Pay 票證。

要求存取權

請使用商家的支援表格要求存取權。請注意以下幾點：

您必須在表格中分享您的核發者 ID。
請在「Issue type」(問題類型)下方，選取 [Technical/API Integration] (技術/API 整合)。
請選取 [Link your app or website below the Google Pay pass] (在 Google Pay 票證下方連結您的應用程式或網站)。

設定 Google Pay 票證上的應用程式連結

請針對特定 Google Pay 票證定義 appLinkData，以設定應用程式或網站的 URI。URI 可以是任何格式，但建議使用動態連結。

您可以參考下方原始碼 appLinkData 欄位的格式和結構定義：

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}