ユースケース

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

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

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

パスを更新する。
Google Pay アプリでスキャンする。
リンクされたクーポン。
ジオフェンス通知
期限切れのパスを処理する
保存されたパスにリンクする。
保存したパスからリンクする。
登録とログイン

パスを更新する

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

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

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

注: update と patch の違いについては、パッチ（部分更新）をご覧ください。

どの update ロジックでも、最初に GET リクエストを実行してクラスまたはオブジェクトを取得する必要があります。これにより、クラスまたはオブジェクトの最新バージョンが確実に使用されます。省略したフィールドは消去されます。

一般的に、変更するフィールドのみにデータを指定する場合は、patch を使用するほうが安全です。省略したフィールドは消去されません。ただし、配列を変更する場合は特に注意が必要です。配列を含むパッチリクエストを実行すると、既存の配列も、指定した配列で置換されます。配列内の要素を部分的に変更、追加、削除することはできません。

場合によっては、いつ変更が発生するか、あるいは 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 呼び出し insert、update、patch、modifyLinkedOfferObjects を使用してポイントカードにリンクできます。

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

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

注: 書き込み可能フィールド linkedOfferIds を使用せずに既存の LoyaltyObject を update すると、すべてのクーポンのリンクが解除されます。

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

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

注: patch 呼び出しで、リンクされているすべてのクーポンのリンクを解除するには、linkedOfferIds フィールドを明示的に null または [] に設定する必要があります。

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

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

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

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

注: リンクされた OfferClass にヒーロー画像がない場合、リンクされたクーポンは、このビューの LoyaltyClass の背景色を使用します。

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

注: この画像には、簡略化されたクーポンデザインに必要なすべてのフィールドが含まれています。ただし、有効な OfferClass または OfferObject を作成するために、これらすべてのフィールドが必要というわけではありません。必須フィールドの一覧については、OfferClass insert メソッドと OfferObject insert メソッドをご覧ください。

ジオフェンス通知

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

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

Google Pay API for Passes Merchant Center アカウントの作成時に、Google マップからの位置情報が使用されます。
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 フィールドが Expired、Inactive、または Completed としてマークされている。

保存されたパスにリンクする

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

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

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

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

保存された Google Pay パスから外部にリンクする

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

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

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

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

Google Pay パスでアプリへのリンクを設定する

特定の 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 から参加するか自分のアカウントにログインできます。詳細については、登録とログインをご覧ください。