請選取下列其中一個票證類別,進一步瞭解相關使用方式。
Google Pay API for Passes 可讓你透過會員卡與使用者互動。本指南討論的概念將協助你進一步瞭解已儲存會員卡的功用。
以下應用實例僅適用於「會員」類別:
更新票證
如果票證在建立後有所異動,請使用 REST API 向使用者告知相關變更。如果相關變更只會影響類別,您也可以使用 Google Pay Merchant Center。 票證更新是與使用者互動的重要方式。
如要更新票證的顯示方式 (例如標誌變更時),您只需要對 LoyaltyClass
進行 update
或 patch
,或使用 Google Pay Merchant Center 即可。Google 會將這項資訊套用到與更新後的 LoyaltyClass
相關聯的所有 LoyaltyObject
。凡是在 LoyaltyClass
層級定義的所有欄位,均應採取這樣的做法。
如要更新單一票證 (例如會員卡點數餘額變更時),則需對單一 LoyaltyObject
進行 update
或 patch
。凡是在 LoyaltyObject
層級定義的所有欄位,均應採取這樣的做法。
有時候,您可能不曉得資料是在何時變更,或是不確定要在什麼時候觸發 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
欄位:
{ i"d:" 2"945482443380251551.ExampleObject1," c"lassId:" 2"945482443380251551.ExampleClass1," ... l"inkedOfferIds:" [ 2"945482443380251551.OfferObject1," 2"945482443380251551.OfferObject2 " ] }
使用 patch
呼叫將優惠與現有的會員卡建立連結和取消連結時,linkedOfferIds
欄位可以是要求中的唯一欄位:
{ l"inkedOfferIds:" [ 2"945482443380251551.OfferObject1," 2"945482443380251551.OfferObject2 " ] }
然而,為了避免在處理陣列時出錯,請指定需新增和移除的附帶優惠,並透過可行方法省略不應更動的附帶優惠。建議您使用以下範例中的 modifyLinkedOfferObjects
方法:
{ l"inkedOfferObjectIds " { a"ddLinkedOfferObjectIds:" [ 2"945482443380251551.OfferObject1," 2"945482443380251551.OfferObject2 " ], r"emoveLinkedOfferObjectIds:" [ 2"945482443380251551.OfferObject3," 2"945482443380251551.OfferObject4 " ] }}
設計含有附帶優惠的活動票券
附帶優惠會顯示在資訊卡區段和詳細資料區段之間的會員卡檢視畫面中,如下所示。輪轉介面最多只能顯示 5 個附帶優惠。如果會員卡連結的優惠超過此數目,使用者可按一下輪轉介面結尾處的 [更多] 按鈕來顯示所有優惠。
按一下滑鼠時,附帶優惠將使用簡化的優惠設計,如下所示。
地理圍欄通知
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 帳戶顯示一則含有輪轉介面且無法修改的通知訊息。物件會在這個輪轉介面中循環顯示:
![](https://developers-dot-devsite-v2-prod.appspot.com/static/pay/passes/images/geofenced-notification-example.png?authuser=5&hl=zh-tw)
如要讓地理圍欄通知順利運作,使用者必須在 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 } } } } … … … }
註冊與登入
會員註冊與登入功能可讓使用者在 Google Pay 中搜尋並加入你的會員方案,或登入自己的帳戶。詳情請參閱註冊與登入說明。