Google Pay を使用したユーザーへのアプローチ

重要な情報を更新するときにメッセージを追加する

すべてのカテゴリにメッセージ セクションがあります。このセクションを使用して、ポイントカード、ギフトカード、クーポン、イベント チケット、搭乗券、交通機関のパスに対する変更など、重要な情報を目立たせることができます。詳しくは、ご利用のパスタイプのパス テンプレート ページをご覧ください。

搭乗券 イベント チケット ギフトカード ポイント クーポン 交通機関のパス

insert、update、patch メソッドでクラスやオブジェクトにメッセージを追加するには、messages[] 配列プロパティを使用します。また、addMessage メソッドを使用して既存のメッセージに追加することもできます（最大 10 件まで）。詳細については、リファレンスをご覧ください。

次のコードでは、現在のクーポンの有効期限 ( validTimeInterval.end) を取得し、有効期限を更新して messages[] 配列に追加します。これにより、保存された Object が Google Pay アプリで表示されたときに、情報の変更を通知できます。

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 でオブジェクトを取得し、PUT で offerObject を更新します。

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 には違いがあります。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 メソッドの詳細については、リファレンスをご覧ください。オブジェクトが削除されたときに、リアルタイムで通知されません。このような操作を行うには、リスナー サービスを実装し、特定のサービスレベル契約を遵守する必要があります。

カテゴリ固有のエンゲージメント方法

パスカテゴリに固有のエンゲージメント方法があります。実装の詳細については、各カテゴリのユースケース ページをご覧ください。

搭乗券 イベント チケット ギフトカード ポイント クーポン 交通機関のパス