透過 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://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId
    PUT https://walletobjects.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
        }
      ]
    }
    

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 不會提供即時通知。如要接受通知,您必須導入事件監聽器服務並遵循特定的《服務水準協議》。

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

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