ユースケース

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


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

以下では、ポイント カテゴリでのみ使用可能なユースケースについて説明します。

パスを更新する

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

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

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

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

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

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

リンクされたクーポン

リンクされたクーポンを使用すると、既存のクーポンをポイントカード ビュー内に表示でき、ユーザーは関連性の高いコンテンツを容易に見つけることができます。LoyaltyObject の書き込み可能なリスト フィールド linkedOfferIds は、ポイントカードに関連付けられているクーポンを示します。

リンク前のクーポンの作成

クーポンをリンクするには、ポイントカードにリンクされるクーポンクラスおよびクーポン オブジェクトがすでに作成されている必要があります。クーポンの作成の詳細については、クーポンをご覧ください。スタンドアロンのクーポンとは異なり、リンクされたクーポンでは、ユーザーがクーポンを明示的に保存する必要はありません。OfferObject にある id フィールドは、LoyaltyObject を参照するために使用されます。

既存のクーポンは、REST API 呼び出し insertupdatepatchmodifyLinkedOfferObjects を使用してポイントカードにリンクできます。

ポイントカードの作成時に insert 呼び出しを使用してクーポンをポイントカードにリンクするとき、または update 呼び出しを使用してクーポンを既存のポイントカードにリンクするときとリンク解除するときに、フィールド linkedOfferIds は、形式が確立された他の LoyaltyObject を使って書き込むことができます。

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

patch 呼び出しでクーポンを既存のポイントカードにリンクするときと、リンクを解除するとき、リクエストに含めることができるフィールドは linkedOfferIds だけです。

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

ただし、配列を処理する際のミスを避けるために、追加する必要があるリンクされたクーポンと、削除する必要があるリンクされたクーポンを指定します。変更しないリンクされたクーポンは省略できます。次の例に示すように、modifyLinkedOfferObjects メソッドを使用することをおすすめします。

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

リンクされたクーポンのあるポイントカードのデザイン

リンクされたクーポンは、次のように、ポイントカード ビューのカード セクションと詳細セクションの間に表示されます。カルーセルに表示されるのは、最大 5 件のリンクされたクーポンだけです。5 件を超えるクーポンがポイントカードにリンクされている場合は、カルーセルの端にある [その他] ボタンをクリックすると、すべてを表示できます。

リンクされたクーポン

リンクされたクーポンをクリックすると、次のように、簡略化されたクーポン デザインが使用されます。

リンクされたクーポンをクリック

ジオフェンス通知

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

登録とログイン

ポイント プログラムの登録とログイン機能により、ユーザーはポイント プログラムを検索し、Google Pay から参加するか自分のアカウントにログインできます。詳細については、登録とログインをご覧ください。