透過 Google Pay 互動

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

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

您可以使用 insertupdatepatch 方法來填入 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()

更新狀態

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

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

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

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

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

以下提供程式碼範例,讓您瞭解如何使用不同語言更新 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
    }
  ]
}

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

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

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

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

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

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

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

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

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

可即時查看 hasUsers 屬性,前提是使用者登入您的網站或應用程式,或是透過批次處理程序一次處理大量使用者。

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

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

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

部分提高參與度的方法只限於票證類別。如需各個類別的採用方式詳細說明,請參閱應用實例。以下列出幾個提高特定類別參與度的方法: