ユースケース

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


Google Pay API for Passes を使用すると、クーポンを使用してユーザーにアピールできます。このガイドで説明するコンセプトを学習することで、保存済みの特典の機能をより深く理解できます。

以下では、クーポン カテゴリでのみ使用できるユースケースを説明します。

パスを更新する

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

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

クーポンの有効期限が変更されるなど、1 つのパスを更新するには、1 つの OfferObject に対して update または patch を実行する必要があります。これは、OfferObject レベルで定義されているすべてのフィールドに当てはまります。

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

クーポンの有効期限を通知する

有効期限が切れる前にクーポンを利用するようにユーザーに通知するため、デフォルトでは、クーポンの有効期限が切れる 48 時間前に通知がトリガーされます。通知をトリガーするには、クーポンが次の条件を満たしている必要があります。

  1. ユーザーのデバイスに期限切れの通知がまだ表示されていない。
  2. validTimeInterval.end.date で、有効期限の datetime に将来の有効な日付が設定されている。
  3. ユーザーのデバイスに 12 時間以上保存されている。
  4. 書き込み可能なフィールド disableExpirationNotificationTrue に設定されていない。このフィールドはデフォルトで false に設定されています。

次のスクリーンショットはデフォルトの通知を示しています。この通知は変更できません。

  1. クーポンの有効期限(今日、明日、[x] 日後)
  2. class.title
  3. class.titleImage

クーポンの有効期限通知のヘッダーはカスタマイズできません。

停止時間

クーポンの有効期限通知がユーザーの現地時間で午後 10 時から午前 6 時の間に表示されるように設定されている場合、この時間帯の前後にクーポンが表示されます。

クーポンの有効期限通知時間のカスタマイズ

OfferObjects または OfferClassesmessage.displayInterval.start.date フィールドを使用すると、Offer の有効期限通知を表示するタイミングをカスタマイズできます。カスタム通知時間が設定されている場合、有効期限通知は validTimeInterval.end.date から計算されたデフォルトのロジックではなく、message.displayInterval.start.date に従ってトリガーされます。以下は、カスタマイズされた有効期限通知時間の例です。

{
  “message”: {
   “messageType”: “expirationNotification”,
   “displayInterval”: {
     “start”: {
      “date”: datetime
     }
   }
  }
}

displayInterval.start.date は通知の表示時刻を設定します。有効期限の 30 日前まで設定できます。30 日より前に指定した場合は、30 日前に通知がトリガーされます。このメッセージにはヘッダーと本文のフィールドは必要ありません。ヘッダーと本文のフィールドが含まれていても使用されません。

ジオフェンス通知

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
              }
            }
    }
  }
  …
  …
  …
}