透過 Google Pay 與使用者互動

在更新重要資訊時新增訊息

所有類別都含有訊息區段。請參考本節來醒目顯示各種重要資訊，例如會員卡、儲值卡、優惠、活動票券、登機證和大眾運輸票證方案的任何異動。詳情請參閱票證類型的票證範本頁面：

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

您可以使用 insert、update 或 patch 方法來填入 messages[] 陣列屬性，藉此將訊息新增至類別或物件。或者，您也可以透過 addMessage 方法對現有訊息進行新增 (最多 10 則)。詳情請參閱相關參考資料。

下列程式碼會取得目前優惠到期日 ( validTimeInterval.end)，接著更新到期日並新增至 messages[] 陣列中。這樣一來，使用者在 Google Pay 應用程式中查看已儲存的 Object 時，即可得知資訊已變更。

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();

// Update the version, validTimeInterval.end, and add a message
obj.setVersion(obj.getVersion() + 1L);
obj.setValidTimeInterval(new TimeInterval().setEnd(new DateTime().setDate(new com.google.api.client.util.DateTime(new Date().getTime() + 263000000000L))));

// Get the current messages
List messages = obj.getMessages();

// Define new message
WalletObjectMessage message = new WalletObjectMessage()
  .setHeader("Important Notice")
  .setBody("Your offer has been extended!");

// Add the new message about updates to the Offer Object
messages.add(message);
obj.setMessages(messages);

// Update the Offer Object
OfferObject returnObj = client.offerobject().patch(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject $offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');

// Update the version, validTimeInterval.end, and add a message
$offerObj->setVersion($offerObj->getVersion() + 1);
$validTimeInterval = new Google_TimeInterval();
$startDateTime = new Google_DateTime();
$startDateTime->setDate('2013-06-12T23:20:50.52Z');
$validTimeInterval->setStart($startDateTime);
$endDateTime = new Google_DateTime();
$endDateTime->setDate('2013-12-12T23:20:50.52Z');
$validTimeInterval->setEnd($endDateTime);
$offerObj->setValidTimeInterval($validTimeInterval)

// Get the current messages
$messages = $offerObj->getMessages();

// Define new message
$newMessage = array(
  'header' => 'Important Notice',
  'body' => 'Your offer has been extended!',
  'kind' => 'walletobjects#walletObjectMessage'
);

// Add the new message about updates to the Offer Object
array_push($messages, $newMessage);
$offerObj->setMessages($messages);

// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version, validTimeInterval.end, and add a message
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['validTimeInterval'] = {
     'start' : {'date':'2018-01-20T23:20:50.520Z'}
     ,'end' : {'date':'2018-01-24T23:20:50.520Z'}
    }

// Get the current messages
messages = offer_object['messages']

// Define new message
message = {
   'header': 'Important Notice',
   'body': 'Your offer has been extended!',
   'kind': 'walletobjects#walletObjectMessage'
 }

// Add the new message about updates to the Offer Object
messages.append(message)
offer_object['messages'] = messages

# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

注意：如果未設定 startTime，訊息會在 Object 插入後立即顯示。如未提供 endTime，則會在訊息清單中無限期顯示這則訊息。詳情請參閱 messages[] 屬性。

更新狀態

無論類別為何，所有物件皆擁有 state 屬性。更新物件的狀態是讓客戶知道票證已兌換或已過期的重要方式。

任何更新都應先發出 GET 要求來擷取 Object，以確保使用的是最新版本的物件。餘額變更後，物件的版本也應遞增。如要儲存已更新的 Object，請發出 PUT 要求。

您可以使用下列 REST URI 範例來對物件執行 GET 動作，並對 offerObject 進行 PUT (更新) 動作：

GET https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId
PUT https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId

如要按照類別進一步瞭解不同的 GET 和更新方法，請參閱相關參考資料。

注意：PUT (更新) 方法會使用您 PUT 的新定義來取代整個物件。如果您只想更新特定欄位並保留現有的 Object 資料，請使用參考資料中列出的 PATCH 方法。關於 PUT 和 PATCH 之間的差異，請參閱 patch 語意相關說明，瞭解 PUT 和 PATCH 有何不同。

以下程式碼範例示範如何使用不同語言更新 offerObject。其他類別物件的程式碼也會十分類似：

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();
// Update the version and state
obj.setVersion(obj.getVersion() + 1L);
obj.setState("expired"); //see the Reference API for valid "state" options
// Update the Offer Object
OfferObject returnObj = client.offerobject().update(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');
// Update the version and points
offerObj.setVersion(offerObj.getVersion() + 1);
offerObj.setState("state"); // see the Reference API for valid "state" options
// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version and state
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['state'] = 'expired' # see the Reference API for valid "state" options
# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

本地化

Google Pay API for Passes 允許商家提供本地化內容，系統會根據使用者的語言代碼提供這些內容。為提供這項功能，我們在 API 中包含了額外的欄位。每個本地化欄位都是格式如下的 LocalizedString 巢狀物件：

{
  "kind": "walletobjects#localizedString",
  "translatedValues": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ],
  "defaultValue": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ]
}

defaultValue 是所有 LocalizedStrings 的必填欄位。所有 translatedStrings 中都必須提供語言和值。

語言欄位必須以 BCP 47 語言標記表示 (例如「en-US」、「en-GB」、「es-419」等等)。值是字串的翻譯值。如果使用者的語言代碼相符，系統便會顯示此字串。

系統會根據最符合使用者的語言代碼，向使用者顯示本地化字串。如未提供合適的 translatedValue，系統將會使用 DefaultValue。假如已設定相對應的本地化欄位，系統就不會使用非本地化的欄位。

判斷使用者是否已移除票證

判斷使用者是否已移除票證

如要透過 Google Pay 查看使用者是否已移除自己的票證 (例如會員卡)，請使用以下 GET 呼叫擷取使用者的 Object 並查看其 hasUsers 屬性。

舉例來說，如要使用 GET 查看 loyaltyObject：

GET https://walletobjects.googleapis.com/walletobjects/v1/loyaltyObject/objectId

假如所有使用者都刪除了票證或已移除會員卡，Google 並不會刪除該物件，而是會將物件上的 hasUsers 屬性設為 false。

如果使用者登入您的網站或應用程式，或是透過批次處理程序一次處理大量使用者，您就能即時查看 hasUsers 屬性。

建立物件時，您已定義用來擷取 LoyaltyObject 的物件 ID。如要向使用者提供當前級別和點數餘額等個人化資訊，您必須將 ID 儲存在自己的存放區中。

如要進一步瞭解不同的 GET 方法，請參閱相關的參考資料。物件遭到刪除時，Google 不會提供即時通知。如要接受通知，您必須導入事件監聽器服務並遵循一定的《服務水準協議》。

特定類別提高參與度的方法

某些提高參與度的方法只限於特定票證類別。如需各個類別的實作詳細說明，請參閱「應用實例」頁面：

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