應用實例

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

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

以下應用實例僅適用於「儲值卡」類別：

更新票證。
在 Google Pay 應用程式中進行掃描。
地理圍欄通知。
處理過期的票證。
連結已儲存的票證。
從已儲存的票證連出。

更新票證

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

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

如要更新單一票證 (例如儲值卡餘額變更時)，則需對單一 GiftCardObject 進行 update 或 patch。凡是在 GiftCardObject 層級定義的所有欄位，均應採取這樣的做法。

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

在 Google Pay 應用程式中進行掃描

使用者可掃描或手動新增儲值卡詳細資料，藉此將儲值卡新增到的 Google Pay 應用程式中。Google Pay API for Passes 會建立一個 GiftCardObject，這個物件不會參照你先前定義的 GiftCardClass。如要建立新物件或類別，您不需採取任何動作。不過，Google Pay API for Passes 建立的 GiftCardObject 無法更新，其運作方式類似靜態票證。

地理圍欄通知

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
              }
            }
    }
  }
  …
  …
  …
}