應用實例

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


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

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

更新票證

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

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

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

有時候,您可能不曉得資料是在何時變更,或是不確定要在什麼時候觸發 updatepatch 要求。在這種情況下,請針對每個類別和物件安排定期的 updatepatch 要求。如果您呼叫 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 呼叫 insertupdatepatchmodifyLinkedOfferObjects 即可將現有優惠連結至會員卡。

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

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

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

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

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

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

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

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

附帶優惠

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

已點選的附帶優惠

地理圍欄通知

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 欄位標記為 ExpiredInactiveCompleted 時。

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

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

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

您可以透過 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 票證定義 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 中搜尋並加入你的會員方案,或登入自己的帳戶。詳情請參閱註冊與登入說明。