應用實例

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

登機證 活動票券 儲值卡 會員卡 優惠 大眾運輸票證

---

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

以下應用實例僅適用於「會員」類別：

• 更新票證。
• 在 Google Pay 應用程式中進行掃描。
• 附帶優惠。
• 地理圍欄通知。
• 處理過期的票證。
• 連結已儲存的票證。
• 從已儲存的票證連出。
• 註冊與登入。

注意：所有票證類別都具備相同的核心功能。詳情請參閱將票證儲存至 Google Pay、透過 Google Pay 兌換票證及透過 Google Pay 與使用者互動等說明文件。

更新票證

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

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

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

注意：如要進一步瞭解 update 和 patch 之間的差異，請參閱修補 (部分更新) 一節。

任何 update 邏輯都應該以 GET 要求做為開頭來擷取類別或物件，確保系統使用的是最新版類別或物件。系統會清除您省略未填的欄位。

一般來說，如果只想為您要變更的欄位提供資料，使用 patch 是比較保險的做法。這樣一來，您省略未填的欄位就不會遭到清除。但是，修改陣列時應格外小心。含有陣列的修補要求也會以您提供的陣列取代現有的陣列。您無法個別修改、新增或刪除陣列中的項目。

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

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

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

附帶優惠

重要事項：在我們改善平台的期間，大部分的使用者將暫時無法使用附帶優惠。這項功能會在下一個版本中更新。

附帶優惠能讓現有優惠出現在會員卡檢視畫面中，讓使用者更容易發現相關內容。LoyaltyObject 中的可寫入清單欄位 linkedOfferIds 會指出哪些優惠與會員卡相關。

在連結前建立優惠

如要連結附帶優惠，你必須先建立要連結至會員卡的優惠類別與物件。要進一步瞭解如何建立優惠，請參閱優惠一節。與獨立優惠不同，使用者不須特別儲存附帶優惠。OfferObject 中的 id 欄位會用來指向 LoyaltyObject。

將優惠連結至會員卡

使用 REST API 呼叫 insert、update、patch 或 modifyLinkedOfferObjects 即可將現有優惠連結至會員卡。

建立會員卡時使用 insert 呼叫將優惠連結至會員卡，或是使用 update 呼叫將優惠與現有的會員卡建立連結和取消連結時，可以使用既定的格式將 LoyaltyObject 的其餘部分寫入 linkedOfferIds 欄位：

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

注意： 如果您使用 update 更新了現有的 LoyaltyObject，卻未附帶可寫入的 linkedOfferIds 欄位，則所有優惠都會取消連結。

使用 patch 呼叫將優惠與現有的會員卡建立連結和取消連結時，linkedOfferIds 欄位可以是要求中的唯一欄位：

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

注意：如要將所有附帶優惠與 patch 呼叫取消連結，您必須確實將 linkedOfferIds 欄位設為 null 或 []。

然而，為了避免在處理陣列時出錯，請指定需新增和移除的附帶優惠，並透過可行方法省略不應更動的附帶優惠。建議您使用以下範例中的 modifyLinkedOfferObjects 方法：

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

設計含有附帶優惠的活動票券

附帶優惠會顯示在資訊卡區段和詳細資料區段之間的會員卡檢視畫面中，如下所示。輪轉介面最多只能顯示 5 個附帶優惠。如果會員卡連結的優惠超過此數目，使用者可按一下輪轉介面結尾處的 [更多] 按鈕來顯示所有優惠。

注意：如果連結的 OfferClass 中缺少主頁橫幅，則附帶優惠在這個檢視畫面中會使用 LoyaltyClass 的背景色彩。

按一下滑鼠時，附帶優惠將使用簡化的優惠設計，如下所示。

注意：簡化的優惠設計會一律使用白色背景。

注意：這張圖片包含完成簡化優惠設計所需的所有欄位。 不過，建立有效的 OfferClass 或 OfferObject 並不需要上述所有欄位。如需必要欄位清單，請參閱 OfferClass insert 和 OfferObject insert 方法。

地理圍欄通知

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

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

1. 您在建立 Google Pay API for Passes Merchant Center 帳戶時，系統會使用 Google 地圖中的地理位置資訊。
2. 您可以透過 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 票證標題下方，連結至您的應用程式或網站。這項功能適用於所有類型的 Google Pay 票證。

注意：只有在您完成至少兩項與 Google Pay for Passes API 的整合之後，才能使用這項功能。整合內容必須是應用程式、網站或電子郵件。

要求存取權

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

• 您必須在表格中分享您的核發者 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
              }
            }
    }
  }
  …
  …
  …
}

註冊與登入

會員註冊與登入功能可讓使用者在 Google Pay 中搜尋並加入你的會員方案，或登入自己的帳戶。詳情請參閱註冊與登入說明。