ユースケース

次のいずれかのパスカテゴリを選択して、使用方法の詳細をご覧ください。


Google Pay API for Passes を使用すると、ギフトカードを使用してユーザーとかかわることができます。このガイドで説明するコンセプトは、保存されたギフトカードの機能をより深く理解するのに役立ちます。

以下では、ギフトカード カテゴリでのみ使用できるユースケースを説明します。

パスを更新する

パスの作成後に変更が発生した場合は、REST API を使用して変更をお客様に配信できます。変更がクラスにのみ影響する場合は、Google Pay Merchant Center を使用することもできます。パスの更新は、お客様とのやり取りで重要な処理の 1 つです。

ロゴが変更された場合など、パスの表示方法を更新するには、GiftCardClassupdate または patch するか、Google Pay Merchant Center を使用するだけで対処できます。この情報は、更新された GiftCardClass に関連付けられているすべての GiftCardObject に渡されます。これは、GiftCardClass レベルで定義されているすべてのフィールドに当てはまります。

1 枚のパスを更新する場合は(ギフトカードの残高が変更されたなど)、1 つの GiftCardObjectupdate または patch する必要があります。これは、GiftCardObject レベルで定義されているすべてのフィールドに当てはまります。

場合によっては、いつ変更が発生するか、あるいは update または patch リクエストをいつトリガーすればよいかわからないことがあります。そのような場合は、すべてのクラスとオブジェクトそれぞれに対して、update または patch リクエストを定期的にスケジュールします。GiftCardClass list メソッドを呼び出すと、特定の発行者アカウントのすべてのクラスを確認できます。また、GiftCardObject list メソッドを呼び出すと、特定のクラスのすべてのオブジェクトを確認できます。

Google Pay アプリでスキャンする

ユーザーは、ギフトカードの詳細をスキャンするか手動で追加することで、自分の Google Pay アプリにギフトカードを追加できます。Google Pay API for Passes では、以前に定義した GiftCardClass を参照しない GiftCardObject が作成されます。新しいオブジェクトまたはクラスの作成に、管理者やユーザーによる操作は必要ありません。ただし、Google Pay API for Passes で作成された GiftCardObject は更新できず、静的パスのように動作します。

ジオフェンス通知

Google は、ユーザーが定義したロケーションへの消費者の近接度に基づいて、消費者の保存されたオブジェクトに関連する通知をトリガーできます。

位置情報は、次の 2 つの方法で追加されます。

  1. Google Pay API for Passes Merchant Center アカウントの作成時に、Google マップからの位置情報が使用されます。
  2. REST API を介してオブジェクトまたはクラスに座標を追加できます。

オブジェクトまたはクラスに座標を追加する方法については、REST API を使用した位置情報の追加をご覧ください。

ジオフェンスのコンセプト

Google は、Google マップの位置情報を使用して、ユーザーが店舗や地域に実際にいるかどうかをアルゴリズムで判断します。この検出は、Google Pay API for Passes Merchant Center アカウントで開発されたすべてのクラスとオブジェクトに適用されます。

このアルゴリズムでは、GPS、Wi-Fi、Bluetooth、移動、滞在時間などの要素が考慮されます。ユーザーが実際に存在すると判断されると、ジオフェンス通知がトリガーされます。

Object で座標が手動で指定されると、座標から 150 m の位置にいるときにジオフェンス通知がトリガーされます。

ジオフェンス通知の頻度、スロットリング、ユーザー オプトアウト

ユーザーは 1 日に最大で 4 つの通知を受信します。

ジオフェンス内に複数のオブジェクトが保存されている場合は、Google Pay API for Passes Merchant Center アカウントごとに 1 つのカルーセル付きの変更不可能な通知が表示されます。カルーセル内でオブジェクトの表示を切り替えることができます。

ジオフェンス通知を機能させるには、ユーザーが 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 アプリの [パス] タブの下に、アーカイブされたパスや無効なパスがすべて含まれた [期限切れのパス] セクションがあります。次の条件の少なくとも 1 つに該当する場合、乗車券は [期限切れのパス] セクションに移動されます。

  • object.validTimeInterval.end.date が期限切れになっている。このパスは、object.validTimeInterval.end.date を過ぎてから 24 時間以内に [期限切れのパス] に移動されます。
  • object.state フィールドが ExpiredInactive、または Completed としてマークされている。

ユーザーがパスを保存したら、その objectId を参照してパスにリンクできます。

次のリンクを使用してパスを参照します。

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

対象のパスは、Google Pay アプリまたはウェブブラウザで表示できます。

保存した Google Pay パスのヘッダーの下で、アプリまたはウェブサイトにリンクできます。この機能は、すべての種類の Google Pay パスでご利用いただけます。

アクセスをリクエストする

店舗販売者向けのサポート フォームを使用して、アクセスをリクエストします。次の点にご注意ください。

  • フォームでは発行者 ID を共有する必要があります。
  • [Issue type] で、[Technical/API Integration] を選択します。
  • [Link your app or website below the Google Pay pass] を選択します。

特定の 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
              }
            }
    }
  }
  …
  …
  …
}